Craft: Construir con IA sin perder el control

Spec · Build · Close

flowchart LR
    Spec -->|spec.md| Build
    Build -->|tech-plan + code| Close
    Build -.->|iterar| Build
    Close -.->|siguiente feature| Spec

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 3 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 artefactos concretos y verificables:

1. Cualquier modelo competente puede ejecutarlo. Si el trabajo está bien definido, 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.
3. Los errores fortalecen el sistema. Cada iteración descubre algo que la planificación no previó. Eso es normal, no un fallo.

Esto no caduca. Especificar, construir, reconciliar y cerrar seguirá siendo válido independientemente de la herramienta o el modelo.

1. Spec

Define el qué antes de tocar código

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. La herramienta da igual. El principio: el contexto debe vivir en un archivo que el agente lea sin que se lo pidas.

Contexto global y de proyecto

Global: tus preferencias personales que aplican a todos tus proyectos. Proyecto: stack, decisiones arquitectónicas, edge cases de negocio, deuda técnica, relaciones no obvias.

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

Define el alcance como comportamientos

Comparte con el agente tus ideas: 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 (GIVEN/WHEN/THEN).

Lo que importa es que cada requisito quede definido como algo que se puede comprobar, no como una descripción vaga. Guarda estos escenarios. Esto define el "qué" de tu aplicación y sobrevive entre sesiones.

Auditoría de la spec

Antes de dar por buena una spec, atácala: ¿qué pasa con estados vacíos? ¿Con errores? ¿Cuántos elementos puede haber? ¿Quién puede ver o modificar esto? Si no has pensado en los bordes, el agente rellenará los huecos con suposiciones plausibles — y tú no te darás cuenta hasta producción.

El tiempo invertido en la spec se multiplica. Cada ambigüedad resuelta aquí ahorra una iteración entera después.

2. Build

Planifica, ejecuta, itera

El alcance ya está en la spec. Aquí decides cómo hacerlo y en qué orden.

Planificación

Deja que el agente proponga un plan técnico: decisiones de arquitectura (con trade-offs), tareas atómicas agrupadas por dependencias, y qué se puede paralelizar. Interrógalo: busca dependencias ocultas, complejidad innecesaria, casos borde.

El plan debe incluir qué criterio de aceptación cubre cada tarea. Si un criterio no tiene tarea, falta trabajo. Si una tarea no cubre ningún criterio, sobra.

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

Ejecución

El agente ejecuta las tareas. Revisa diffs. Interroga cada decisión que no entiendas. Tu responsabilidad profesional es auditar el código — aunque no lo hayas escrito, lleva tu nombre.

Tests donde importa: lógica de negocio, integridad de datos, autenticación, contratos de API. No necesitas testearlo todo — testea lo que si falla, duele.

Iteración

Si algo falla o descubres un gap, ajusta el plan y repite. El agente registra qué cambió y por qué en un log de iteraciones. Esto es parte normal del ciclo, no un fallo.

Si un gap en la spec bloquea tareas, el agente te pregunta, registra la decisión, y continúa. La spec formal no se toca aquí — eso es trabajo de Close.

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.

Regla de oro

No hagas commits durante Build. Todo el código se commitea en Close, una vez que funciona y está reconciliado.

3. Close

Reconcilia, asegura, persiste

Ya construiste. Ahora haz que el registro coincida con la realidad.

Reconciliación de la spec

Compara lo que dice la spec con lo que realmente se construyó. Si implementaste algo que no estaba en la spec, añádelo. Si algo no se implementó, márcalo. Si algo cambió durante la ejecución, actualiza el criterio. La spec deja de ser un plan y pasa a ser un registro de lo que existe.

Esto es clave: la spec se actualiza al final, una vez. No durante la ejecución, donde cada cambio genera ruido.

Controles pre-commit

Antes de commitear, dos comprobaciones automáticas:

1. Seguridad: buscar secrets hardcodeados en el diff (API keys, tokens, claves privadas). Si se encuentra algo, se para.
2. Calidad: ejecutar las herramientas de lint, formateo y tipado del proyecto. Errores mecánicos se corrigen antes de commitear.

Commits y cierre

Un commit por cambio lógico. Mensajes que expliquen el qué y el por qué. Actualiza el contexto del proyecto con decisiones no obvias. Si mañana no puedes entender por qué se hizo algo, falta documentación o el commit message es malo.

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.

El ciclo de iteración

La diferencia fundamental con un proceso lineal: Build se ejecuta múltiples veces. Cada iteración descubre algo que la planificación no previó. Cada descubrimiento se registra, el plan se ajusta, y se sigue.

La spec no se toca durante Build — se reconcilia en Close, una sola vez, cuando la realidad se ha estabilizado. Esto evita versionado ruidoso y mantiene la spec como fuente de verdad.

flowchart TB
    S[Spec aprobada] --> P[Plan + tareas]
    P --> E[Ejecutar]
    E --> D{Funciona?}
    D -->|No| A[Ajustar plan] --> E
    D -->|Si| C[Close: reconciliar + commit]

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
Specs como comportamiento	Escenarios en el archivo de contexto	Framework BDD 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.