CRAFT: Construir con IA sin perder el control

Contextualize · Refine · Act · Formalize · Teardown

flowchart LR
    Contextualize --> Refine
    Refine --> Act
    Act --> Formalize
    Formalize --> Teardown
    Refine <--> Teardown

Un LLM predice el siguiente token basándose en patrones estadísticos. No entiende tu proyecto, tu negocio ni tu circunstancias. Solo genera texto plausible dado un contexto.

CRAFT es un proceso de 5 fases para trabajar con agentes IA de forma profesional. El objetivo: que el humano mantenga el criterio y el control mientras aprovecha la velocidad del agente.

Para quién es esto

CRAFT está diseñado para Individual Contributors. Los principios escalan a equipos, pero el foco es tu flujo personal.

No importa si estás empezando o si llevas años en esto. Si quieres construir con IA sin depender de la suerte, esto te interesa.

Por qué funciona

Cada fase de CRAFT produce tareas atómicas y contenidas. Esto tiene dos ventajas:

1. Cualquier modelo competente puede ejecutarlo. No necesitas el último modelo de frontera ni contextos enormes. Si el trabajo está bien dividido, un modelo estándar lo resuelve.
2. Puedes auditar todo. Si cada tarea es pequeña, puedes revisar cada output. Si el plan tiene 50 pasos y 40 archivos, no puedes. CRAFT te obliga a mantener el scope bajo control.

Esto no caduca. El proceso de contextualizar, planificar, ejecutar, auditar y limpiar seguirá siendo válido. Es robusto por diseño. Y en el ciclo de testing, antifrágil: cada error descubierto fortalece el sistema con un nuevo test.

1. Contextualize (Contextualizar)

Define las reglas antes de empezar

El agente no conoce tus preferencias ni el contexto de tu proyecto. Como mínimo, necesitas un archivo global. Si el proyecto tiene contexto específico, añade uno de proyecto.

Archivo global (AGENTS.md, CLAUDE.md) o equivalente

Tus preferencias personales que aplican a todos tus proyectos:

• Estilo de código ("no uses any", “no uses barrel indexes”, etc).
• Restricciones universales ("máximo 300 líneas por archivo", "no hardcodees strings más de una vez", etc).
• Convenciones de naming y formato.
• Patrones que siempre usas, o siempre evitas.
• Cualquier patrón técnico que no forme parte de un canon.

(Opcional) Archivo de proyecto (PROJECT.md, CONTEXT.md ) o equivalente

Contexto específico de este proyecto, en el caso de que lo tengas, si no siempre puedes crearlo más adelante. En él, incluye:

• Edge cases de negocio que no son evidentes en el código.
• Antipatrones conocidos.
• Convenciones específicas del equipo o proyecto.
• Decisiones arquitectónicas y el porqué detrás de ellas.
• Puntos de fricción: servicios legacy, contratos de datos, deuda técnica conocida.
• Lecciones aprendidas trabajando en este codebase.
• Si la arquitectura existente tiene relaciones no obvias, documéntala en formato texto (Mermaid o similar antes que imagen).

Herramientas de contexto automático (MCP y similares)

Existen herramientas que inyectan contexto al agente automáticamente: documentación actualizada (Context7), schemas de tu framework (Laravel Boost), etc. Úsalas si encajan en tu stack. Reducen el trabajo manual de contextualización, pero no sustituyen tus archivos de proyecto — esos tienen el contexto humano que ninguna herramienta puede generar.

No añadas obviedades. Si el agente puede inferirlo mirando package.json, la estructura de carpetas o las dependencias, sobra.

2. Refine (Refinar)

Crea un plan pragmático y efectivo

Nunca empieces a escribir código sin un plan. No necesitas un documento articulado con user stories (si no quieres), pero sí compartir una lista de bullet points con las claves que solo tú tienes en la cabeza.

Antes de nada: acota el scope

Si pides algo enorme, el plan será enorme y —créeme— no lo vas a revisar de verdad. Busca la unidad mínima de valor: una feature, un flujo, un componente. Algo que puedas validar y revisar sin perder la cabeza.

Comparte con el agente:

• El por qué: el objetivo de lo que quieres construir. Esto ayuda al agente a entender el contexto y a aportar mejoras e incluso desafíos.
• Definition of Done: el aspecto del artefacto finalizado, para definir hasta dónde quieres llegar.
• Puntos de fricción: servicios legacy, contratos de datos, contexto que solo tú conoces.
• Si lo que vas a construir afecta a la arquitectura o introduce componentes nuevos, dibújalo antes de codificar. Un diagrama rápido puede ahorrarte tiempo de contextualización.

Deja que la IA proponga un plan. Luego, interrógalo: busca casos borde, dependencias ocultas, complejidad innecesaria. Refina hasta que el plan tenga sentido para ti.

Si no puedes revisar el plan en 1 minuto, es demasiado grande. Divide.

3. Act (Actuar)

Ejecuta el plan de forma atómica y contenida

Un agente IA es como un excelente desarrollador junior cargado de cafeína: rápido pero confiado en exceso. Nunca confíes ciegamente en su output. Valida absolutamente todo.

Revisa archivo por archivo e interroga al agente con cada área sospechosa o mejorable:

• Si no entiendes el rationale de una decisión, pregunta.
• Si no sabes qué hace una sentencia, pregunta.
• Si no sabes por qué instaló una dependencia (esto indica un agujero en tu planificación), pregunta.
• Si ves posibilidades de refactorización, proponlas.
• Pasa cualquier linter o validador (ESLint, TSC, etc).

Tu responsabilidad profesional es auditar el código. Aunque no lo hayas escrito, llevas tu nombre. Si no puedes explicar cómo funciona, no debería llegar a producción.

Tests obligatorios en lógica de negocio clave

No necesitas testear cada línea de código. Testea lo que importa:

• Lógica de negocio crítica (cálculos, validaciones, transformaciones de datos).
• Flujos donde un error silencioso tendría consecuencias reales.
• Cualquier código que "si falla, duele".

Cuando encuentres un bug en lógica de dominio

1. Primero, crea un test que reproduzca el escenario y falle.
2. Luego, corrige el error.
3. El test debe pasar automáticamente.

Si el test no pasa tras el fix, tu hipótesis era incorrecta. Este patrón blinda tu código contra regresiones futuras y te obliga a entender el problema antes de "solucionarlo".

El agente rellena lo que no sabe con suposiciones plausibles. Tú tienes el contexto real: el negocio, el usuario, la historia. Esa es tu ventaja.

4. Formalize (Formalizar)

Preserva el artefacto y documenta lo aprendido

Ya auditaste. Ahora toca guardar el trabajo de forma que tu yo del futuro (o tu equipo) lo entienda.

Commits granulares

• Un commit por cambio lógico, no un commit gigante al final.
• Mensajes que expliquen el qué y el por qué.
• Si algo sale mal, puedes revertir sin perder todo.

Crea/Actualiza el archivo de proyecto (PROJECT.md)

• Añade lo no obvio, como lecciones aprendidas.
• Decisiones arquitectónicas que no son evidentes en el código.
• Workarounds temporales y por qué existen.

Si mañana no puedes entender por qué se hizo algo, falta documentación o el commit message es malo.

5. Teardown (Limpiar)

Prepara el siguiente ciclo

Si has hecho bien los pasos anteriores —archivos de contexto actualizados, commits granulares con buenos mensajes, lecciones aprendidas documentadas— tienes la opción de empezar de cero. No necesitas arrastrar tokens de conversaciones anteriores. El agente leerá tus archivos de contexto y entenderá el proyecto a la primera.

Esa es la prueba de que lo has hecho bien: poder cerrar la conversación, abrir una nueva, y que el agente siga el ritmo sin perderse.

Esto es opcional.

Las ventanas de contexto son cada vez más grandes. El drifting ocurre menos. Hay sesiones donde tiene sentido continuar.

La decisión:

• Limpiar — Funcionalidad completada o cambio de foco. Empieza de cero.
• Compactar — Debugging complejo o refactorización con decisiones en curso. Resume y continúa.

Compactar vs Limpiar

• Limpiar (/clear o nueva conversación): Borrón y cuenta nueva. El agente parte solo de tus archivos de contexto.
• Compactar (si tu herramienta lo permite): Resume la conversación actual en un sumario y continúa con menos tokens pero sin perder el hilo.

Compactar es útil cuando el contexto de la sesión tiene valor que no está (todavía) en tus archivos. Pero si dependes siempre de compactar, probablemente no estás documentando lo suficiente en Formalize.

La opción por defecto debería ser limpiar.

Si puedes hacerlo sin fricciones, es que los cuatro pasos anteriores están funcionando. Si no puedes —si cada vez que limpias el agente se pierde— es señal de que falta contexto documentado.

Poder empezar de cero es la prueba de que tu documentación funciona. Si no puedes, vuelve al punto 4.