Aprender AI-DLC creando un juego, parte 5: dentro de una etapa

Esta es la parte 5 de una serie sobre aprender AI-DLC creando un juego, World Rift Conflict, en Godot con un backend en AWS. Las partes 1 a 4 siguieron el trabajo. Esta se detiene a mirar de cerca una pieza del método: qué pasa dentro de una sola etapa, desde que empieza hasta que la apruebo.

Partes publicadas:

• Parte 1: configuración
• Parte 2: prueba de concepto
• Parte 3: tests E2E automáticos
• Parte 4: lo que vio la revisión
• Parte 5: dentro de una etapa (este artículo)

El ejemplo de principio a fin es la etapa Domain Design de la parte 3: la etapa que diseñó las pruebas de extremo a extremo automáticas. Todo lo citado sale de sus registros.

En resumen

1. Una etapa no es un prompt. Es un bucle entre un motor determinista, que decide qué pasa después, y el agente, que hace el trabajo dentro del paso que le dieron.
2. Cada etapa sigue los mismos ocho pasos: preguntar, cargar las reglas, hacer el trabajo (preguntas, documentos, diario), revisar, comprobar, aprender, aprobar e informar.
3. Salen dos tipos de registro: los documentos que lee una persona y un rastro de auditoría de cada pregunta, respuesta, revisión y aprobación.
4. El motor rechaza los pasos dados fuera de orden. Eso hace que el bucle sea fiable, y también es de donde vino casi toda mi fricción al principio.

Quién hace qué

En cada etapa participan tres partes:

• El motor (aidlc engine orchestrate) es un pequeño programa de línea de comandos. Lee el estado del flujo y el grafo de etapas y devuelve exactamente un siguiente paso en JSON. Nunca escribe los documentos.
• El agente (aquí, Claude Code) ejecuta el motor, hace el paso que este indica e informa del resultado. Dentro de una etapa asume el papel principal de esa etapa: el arquitecto en Domain Design.
• La persona responde las preguntas y aprueba la etapa. Nada avanza más allá de una etapa sin esa aprobación.

1. Preguntar qué hacer a continuación

Cada paso empieza con el mismo comando:

aidlc engine orchestrate next

Responde con una directiva. Para Domain Design decía, entre otras cosas:

{
  "kind": "run-stage",
  "stage": "domain-design",
  "lead_agent": "aidlc-architect-agent",
  "mode": "inline",
  "produces": ["components.md", "decisions.md", "traceability.json"],
  "reviewer": "aidlc-architecture-reviewer-agent",
  "review_class": "advisory",
  "next_stage": "Code Generation"
}

La directiva real tiene rutas completas y más campos. Dice quién lidera, qué debe producir la etapa, qué consume (los requisitos aprobados, la base de conocimiento del código, las prácticas del equipo), qué comprobaciones se ejecutan sobre los resultados y quién los revisa. El agente no decide nada de eso.

2. Cargar las reglas

Antes de empezar el trabajo, el motor entrega las reglas que aplican, por partes, cada una con un recibo:

{
  "kind": "load-steering",
  "stage": "domain-design",
  "part": 1,
  "parts": 2,
  "next": "aidlc engine orchestrate continue e-UQxc3J"
}

Las reglas vienen por capas: los valores por defecto de la organización, las prácticas del equipo acordadas en Practices Discovery, las reglas propias del proyecto y las de la fase. Una capa más concreta puede añadir a una más general, pero no contradecirla. Solo después de la última parte llega la directiva run-stage. Si se pide un next nuevo a mitad de camino, la entrega vuelve a la parte 1, así que ninguna etapa empieza con la mitad de sus reglas.

3. Hacer las preguntas

La mayoría de las etapas preguntan antes de escribir. Las preguntas van a un archivo con una línea [Answer]: bajo cada una, cada opción explicada y una última X. Other (please specify):

## Q1. What kind of test backend?

A. **One long-lived Amplify sandbox named `e2e`.** ... (Recommended)
B. **A second Amplify Hosting branch, `test`.** ...
C. **A new sandbox for every run, deleted after it.** ...
X. Other (please specify)

[Answer]: A

Elegí que me guiara, así que el agente las hizo por tandas en el chat y escribió mis respuestas en el archivo. Antes de mostrar cada tanda registra la pregunta, y después la respuesta, así que el rastro de auditoría guarda exactamente lo que vi y lo que elegí:

aidlc engine log decision --stage domain-design --decision "Q1-Q4: ..." --options "Q1:A,B,C,X;..."
aidlc engine log answer --stage domain-design --details 'Q1: A; Q2: A; Q3: A; Q4: A'

El archivo sigue siendo la fuente de verdad. Podría haberlo editado yo directamente, y el motor habría leído el mismo archivo.

4. Escribir los documentos y llevar un diario

Después, quien lidera escribe lo que produce la etapa. En Domain Design: un catálogo de componentes con un bloque legible por máquina y una vista para personas, los registros de decisiones de arquitectura y un archivo de trazabilidad que asigna cada requisito al componente que lo cumple.

Al mismo tiempo, el agente lleva un diario de la etapa, memory.md, con cuatro apartados: Interpretations, Deviations, Tradeoffs y Open questions. Una entrada de esta etapa (en el original, en inglés):

Tradeoffs — The hook presses buttons by emitting signals instead of simulated input, so it works headless; keyboard focus and Enter-to-submit stay untested end to end (ADR-007).

Es decir: el hook pulsa los botones emitiendo señales en lugar de simular entradas, así funciona sin ventana; el foco del teclado y enviar con Enter quedan sin probar de extremo a extremo.

El diario es el único archivo que el agente mantiene a mano fuera de los documentos. Importa en el paso 6.

5. La revisión

Si la etapa tiene revisor, el agente registra una petición de revisión y el motor abre un hueco para exactamente un archivo de revisión. Otro agente, el revisor de arquitectura, lee los documentos y los archivos de origen, nunca el diario, y escribe sus hallazgos en ese archivo con una gravedad para cada uno. Después, el agente registra el veredicto que dice el archivo:

aidlc engine log review --stage domain-design --reviewer aidlc-architecture-reviewer-agent --iteration 1 --verdict 'NOT-READY'

La revisión de Domain Design era consultiva: una pasada, los arreglos hechos después y los hallazgos mostrados en mi aprobación. La parte 4 trata de lo que encontraron esas revisiones.

6. Las comprobaciones y los aprendizajes

Cuando la etapa pide aprobación, unas pequeñas comprobaciones automáticas llamadas sensores se ejecutan sobre sus resultados: secciones obligatorias, cobertura de las fuentes, trazabilidad. En Domain Design, la de trazabilidad señaló dos IDs de requisitos que faltaban en el diseño. Los asigné antes de decidir.

Después viene el paso de los aprendizajes. El motor lee el diario y ofrece sus entradas como candidatas:

aidlc engine learnings surface --slug domain-design

Elegí cuáles guardar, y el motor las escribió en las reglas del proyecto:

aidlc engine learnings persist --slug domain-design --selections-json <file>

De esta etapa, una regla guardada dice que las pruebas de Godot manejan la interfaz con texto y señales, nunca con entradas simuladas. Todas las etapas posteriores la leyeron. Así llega la lección de una etapa a la siguiente sin que nadie edite un archivo de etapa.

7. La aprobación

El agente abre la aprobación, presenta un resumen de lo que produjo la etapa y hace una pregunta con opciones fijas: Approve, Request Changes y, a veces, una opción para añadir una etapa omitida. Mi respuesta vuelve al motor con mis palabras:

aidlc engine orchestrate report --stage domain-design --result awaiting-approval
aidlc engine orchestrate report --stage domain-design --result approved --user-input 'Approve'

Una respuesta Request Changes también se registra, con mis comentarios, y la etapa vuelve sobre sí misma antes de abrir la aprobación de nuevo.

8. Informar y seguir

El informe de aprobación responde con el siguiente paso:

{
  "narration": "Progress: 4 of 7 stages done. Next: Code Generation.",
  "kind": "done",
  "workflow_continues": true
}

Y el bucle empieza otra vez con next.

Dónde está la fricción

El motor es estricto con el orden. Rechaza los pasos dados antes de tiempo, y lo mismo hacen unos hooks que se ejecutan en cada llamada a una herramienta. Tres veces en este proyecto detuvieron al agente:

• Empezar trabajo de Code Generation antes de que su plan estuviera aprobado: "Code generation cannot run mutation-capable shell commands ... code-generation-plan.md is missing or empty."
• Ejecutar un comando mientras las reglas seguían llegando: "The Code Generation rules are still arriving (part 1 of 2 has been loaded)."
• Pedir una segunda revisión donde la etapa permite una: "Cannot request review pass 2 ... this stage allows 1 review pass."

Cada vez, el mensaje decía qué hacer en su lugar, y hacerlo era la solución. El primer día parece lento. Después, es la razón por la que confío en que una etapa marcada como aprobada pasó por todos los pasos.

Lo que me diría a mí mismo

• Lee la directiva, no el archivo de la etapa, para saber qué hará esta ejecución de la etapa. El alcance y la configuración la cambian.
• Lleva el diario con honestidad. Es la materia prima de los aprendizajes, y los aprendizajes son lo que mejora las etapas siguientes.
• Cuando una barrera rechace algo, haz lo que dice su mensaje. Rodearla tira a la basura el registro que protege.

Qué viene después

La parte 6 retoma el trabajo. Hasta entonces, uno de estos análisis a fondo cubre cualquier día sin avance en el proyecto.