CRAFT: Construir con IA sin perder el control

Contextualize · Refine · Act · Formalize · Teardown

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

Un LLM predice el siguiente token basándose en patrones estadísticos. No entiende tu proyecto, tu negocio ni tus 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 produce tareas atómicas y contenidas:

1. Cualquier modelo competente puede ejecutarlo. Si el trabajo está bien dividido, no necesitas el último modelo de frontera.
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.

Esto no caduca. Contextualizar, planificar, ejecutar, auditar y limpiar seguirá siendo válido independientemente de la herramienta o el modelo. Y en el ciclo de testing, antifrágil: cada error descubierto fortalece el sistema con un nuevo test.

1. Contextualize

Define las reglas y el alcance antes de empezar

El agente no conoce tus preferencias ni el contexto de tu proyecto. Necesitas un archivo de contexto que el agente lea automáticamente al iniciar cada sesión. En Claude Code es CLAUDE.md, en Copilot es AGENTS.md — la herramienta da igual. El principio: el contexto debe vivir en un archivo que el agente lea sin que se lo pidas.

Nivel global

Tus preferencias personales que aplican a todos tus proyectos: estilo de código, restricciones universales, convenciones de naming, patrones que siempre usas o siempre evitas.

Nivel proyecto

Contexto específico de este proyecto: stack, decisiones arquitectónicas, edge cases de negocio, antipatrones conocidos, deuda técnica, relaciones no obvias en la arquitectura.

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

Define el alcance como comportamientos

Comparte con el agente tus ideas en bullet points: qué quieres construir y por qué. Discútelo. Deja que te desafíe, desafíale tú. Cuando estéis alineados, pídele que traduzca esos requisitos a escenarios de comportamiento concretos y verificables.

En la práctica, el agente usará una sintaxis tipo GIVEN/WHEN/THEN (el estándar BDD — Gherkin). Tú no necesitas conocer la sintaxis — el agente la domina. Lo que importa es que cada requisito quede definido como algo que se puede comprobar, no como una descripción vaga.

Guarda estos escenarios en tu archivo de contexto. Esto define el "qué" de tu aplicación y sobrevive entre sesiones.

A medida que el proyecto crezca, un solo archivo puede no ser suficiente. Frameworks como OpenSpec organizan specs en archivos independientes que el agente lee bajo demanda. Los principios son los mismos — contexto persistente, specs como comportamiento — solo cambia la escala.

Herramientas de contexto automático

Existen herramientas (MCPs) que inyectan contexto al agente automáticamente: documentación actualizada, schemas de tu framework, etc. Úsalas si encajan en tu stack. Reducen el trabajo manual, pero no sustituyen el contexto humano de tu archivo de proyecto.

2. Refine

Planifica solo la sesión actual

El scope completo ya está definido en tus specs. Aquí decides qué porción ejecutas ahora.

Selecciona los escenarios que vas a implementar en esta sesión. Deja que el agente proponga un plan táctico (el "cómo"). Interrógalo: busca dependencias ocultas, complejidad innecesaria, casos borde. Refina hasta que el plan tenga sentido para ti.

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

No planifiques en detalle lo que vas a construir en 3 sesiones. El plan detallado es solo para lo inmediato. Lo demás cambiará cuando construyas.

3. Act

Ejecuta y valida

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

Revisa diffs en archivos modificados y archivos completos en archivos nuevos. Interroga cada decisión que no entiendas. Pasa linters. Tu responsabilidad profesional es auditar el código — aunque no lo hayas escrito, lleva tu nombre.

Si el plan resulta incorrecto durante la ejecución, vuelve a Refine. Esto no es un fallo — es parte normal del ciclo.

Tests en lógica de negocio clave

Testea lo que importa: lógica crítica, flujos donde un error silencioso tendría consecuencias reales, código donde "si falla, duele".

Cuando encuentres un bug en lógica de dominio: crea un test que falle, aplica el fix, verifica que pase. Si no pasa, tu hipótesis era incorrecta — investiga más.

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

Documenta el estado, no lecciones abstractas

Ya auditaste. Ahora preserva el trabajo para que la próxima sesión arranque sin fricción.

Commits granulares

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

Actualiza el archivo de contexto

• Marca los escenarios completados — mantén la spec original intacta, solo añade un marcador.
• Si al construir descubriste que un escenario futuro necesita un enfoque diferente, actualízalo ahora.
• Añade decisiones técnicas no obvias que el agente necesite en la próxima sesión.
• No documentes lo que se infiere del código o de los manifiestos.

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

5. Teardown

Cierra la sesión

Si los cuatro pasos anteriores están bien hechos, puedes cerrar la conversación y empezar de cero. El archivo de contexto queda como fuente de verdad. El agente lo lee, entiende dónde estás, y continúa.

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

La opción por defecto es limpiar. Si no puedes hacerlo sin que el agente se pierda, vuelve al paso 4 — falta contexto documentado.

Compactar (resumir la conversación sin cerrarla) solo tiene sentido cuando estás en medio de un debugging complejo con contexto diagnóstico que todavía no merece documentarse. Si dependes siempre de compactar, no estás documentando lo suficiente en Formalize.

Escalar los mismos principios

Los principios no cambian con el tamaño del proyecto. Las herramientas sí:

Principio	Proyecto pequeño	Proyecto grande
Contexto persistente	Un archivo en el repo	Archivos por dominio (OpenSpec)
Specs como comportamiento	Escenarios en el archivo de contexto	Framework BDD (Cucumber, Behat) con archivos .feature
Plan por sesión	En la conversación	Sistema de tickets vinculado a specs

Empieza simple. Un archivo, escenarios escritos a mano, plan en la conversación. Cuando crezca demasiado, escala la herramienta. Los principios ya los tienes.