Aprender AI-DLC creando un juego, parte 1: configuración

Parte 1 de la serie de AI-DLC con un juego: los comandos de configuración (aidlc config para Claude Code, aidlc update a 2.11.1, el chequeo doctor, la primera petición /aidlc poc), el plan de prueba de concepto de cuatro etapas con la captura de intención aprobada, y las tres carpetas del proyecto: .claude para el proceso, aidlc para los registros, game y amplify para el producto

Estoy creando un juego, World Rift Conflict, en Godot con un backend en AWS y algunas funciones de IA. También lo uso para aprender AI-DLC, el AI-Driven Development Life Cycle de AWS Labs. AI-DLC es el único proceso en este proyecto: sin issues de GitHub, sin specs propias, sin Gantt. Lo que AI-DLC pregunta, lo respondo; lo que registra, lo conservo.

Esta serie es el registro de construcción, ordenado. Cada parte cubre un hito. La parte 1 es la configuración, hasta la primera etapa del primer trabajo. Comparé AI-DLC con otros flujos de trabajo con IA en un artículo anterior; esta serie cuenta cómo es usarlo de verdad.

Partes hasta ahora:

Resumen

  1. AI-DLC se instala como un binario aidlc autónomo más una estructura de proyecto: aidlc config --harness <tool> escribe los agentes, hooks, skills y reglas en la carpeta de la herramienta (.claude/ para Claude Code) y los registros compartidos en aidlc/.
  2. Primero lo instalé para Kiro y después pasé todo a Claude Code. Las dos instalaciones pueden convivir; solo uso una.
  3. aidlc update actualiza solo el binario. Cada proyecto se queda en su versión anterior hasta que aidlc config --harness <tool> lo actualiza, una vez por herramienta instalada.
  4. /aidlc --doctor es el chequeo de salud. Sus avisos son orientativos; los que vi eran inofensivos.
  5. La primera ejecución fue un poc: cuatro etapas, cuatro puntos de aprobación. La captura de intención hizo seis preguntas, un agente revisor comprobó el resultado y las notas que conservé se volvieron reglas del proyecto.

Tres capas

Me costó ver qué partes del repositorio pertenecen a quién, así que este es el mapa con el que me quedé.

Tres capas del proyecto: el desarrollador conversa con Claude Code, que ejecuta el framework AI-DLC y el motor aidlc con servidores MCP para documentación y consultas de AWS; el motor y las etapas escriben estado, auditoría, artefactos y reglas en la carpeta de registros aidlc; la generación de código escribe el juego en Godot 4.7, que inicia la sesión de los jugadores con Amazon Cognito, definido con AWS Amplify Gen 2
  • El proceso vive en .claude/: la skill /aidlc (el director con el que converso), 14 agentes (producto, arquitecto, desarrollador, calidad, dos revisores, etc.), hooks que mantienen los registros honestos y sensores que revisan lo que escribe cada etapa. El motor aidlc decide qué etapa va después y cuándo detenerse para mi aprobación.
  • Los registros viven en aidlc/: las reglas del método (org.md, team.md, project.md), una carpeta por cada trabajo (una intención) con su estado, preguntas, artefactos y registro de auditoría, y un catálogo de conocimiento para mis propios documentos. Todo se guarda en git.
  • El producto es el juego en Godot y su backend en Amplify. Por ahora es solo un plan: la primera intención trata de iniciar la sesión de un jugador con Amazon Cognito.

Instalarlo

El binario ya estaba en mi máquina. Configurar el proyecto es un comando por herramienta. Empecé con Kiro, porque ahí estaba trabajando:

aidlc config --harness kiro-ide --project-dir . --dry-run < /dev/null
# config plan for …/world-rift-conflict: create=335 update=0 merge=0 preserve=0 remove=0 conflict=0

Trescientos treinta y cinco archivos, antes de una sola línea de código del juego. Vale la pena correr la simulación siempre: dice exactamente qué va a crear, actualizar o borrar, y si algo choca con archivos que ya tienes.

Después pasé a Claude Code. La razón fue práctica: ahí tengo más margen y quería una sola herramienta para todo el proyecto. Añadir la estructura de Claude Code junto a la de Kiro fue el mismo comando con otra herramienta, más los servidores MCP por defecto de AI-DLC:

aidlc config --harness claude --project-dir . --mcp defaults --yes < /dev/null
# configured …/world-rift-conflict for Claude Code 2.11.0; next: open Claude Code in this project
# (if it is already open in this folder, exit it and start it again) and run `/aidlc --doctor`

Se integró con mi configuración de Claude Code y conservó mis reglas y skills. Los cinco servidores MCP son context7 (documentación de librerías) y cuatro servidores de AWS (aws-mcp, aws-pricing, aws-iac, aws-serverless) que usan la cadena normal de credenciales de AWS. Dos cosas me hicieron tropezar:

  • context7 lee CONTEXT7_API_KEY del entorno en el que arranca Claude Code, no de un .env del proyecto. La puse en el perfil de mi shell.
  • El primer arranque de cada servidor uvx es lento, porque descarga sus dependencias de Python. aws-iac mostró "connecting..." hasta que terminó.

Además, Claude Code tiene que confiar en la carpeta una vez. Hasta entonces ignora los comandos permitidos del proyecto, y cada comando de AI-DLC se convierte en una petición de permiso.

Reglas que chocan

Mis proyectos personales siguen otro flujo de trabajo, con sus propias reglas globales para agentes: issues, specs, una rama staging, los agentes nunca hacen push. Esas reglas se cargan en todos los proyectos, también en este. Así que el proyecto tiene sus propios archivos de reglas, importados desde su CLAUDE.md, que dicen qué reglas globales no aplican aquí y dejan que AI-DLC decida.

Git fue el caso más claro. Lo que AI-DLC trae por defecto es desarrollo trunk-based sobre main: cada porción del trabajo de construcción usa una rama corta y se fusiona con squash en main en local. AI-DLC nunca hace push. Conservé a propósito una regla del flujo anterior: subir a GitHub es tarea mía, y el agente me avisa cuando toca. Cómo deben funcionar aquí las ramas y los pull requests queda como pregunta abierta para la etapa Practices Discovery de AI-DLC, que un poc se salta.

El doctor y la actualización

/aidlc --doctor es lo primero que hay que ejecutar, y lo primero que hay que volver a ejecutar cuando algo no cuadra. Mi primera ejecución limpia dijo:

0 problems, 2 warnings.
Warnings are advisory - if everything works, ignore them.

Un aviso decía que una comprobación había fallado 63 veces porque no había estado del flujo que leer. Es lo esperado antes de que exista la primera intención. El otro decía que faltaba la caché de actualizaciones, y eso llevó a la actualización:

aidlc update --check
# binary 2.11.0, latest 2.11.1
aidlc update
# Updated aidlc from 2.11.0 to 2.11.1. Project files were not changed. Run 'aidlc config' between workflows to refresh them.

Esa última línea importa. El binario pasó a 2.11.1 pero el proyecto no, y el doctor lo dijo: Project runtime stamp: 2.11.0; selected engine: 2.11.1. Con dos herramientas instaladas, a aidlc config hay que decirle cuál:

aidlc config --harness claude --dry-run
# config plan for …/world-rift-conflict: create=16 update=195 merge=1 preserve=154 remove=0 conflict=0
aidlc config --harness kiro-ide --dry-run
# config plan for …/world-rift-conflict: create=28 update=198 merge=1 preserve=132 remove=4 conflict=0

Apliqué los dos, para que la copia de Kiro que no uso no se quedara en otra versión, y reinicié VS Code (Developer: Reload Window). Un /clear no basta: los archivos actualizados solo se cargan con un reinicio completo.

La primera ejecución

El primer trabajo es pequeño a propósito. Antes de planificar el juego entero, quería comprobar que la configuración funciona de principio a fin con la dependencia más arriesgada: el plugin de Amplify para Godot se hizo para Godot 4.3, y yo uso 4.7.

/aidlc poc Prove a Godot 4.7 game can sign a player in with the AWS Amplify plugin

AI-DLC creó una carpeta de registro para este trabajo y propuso el plan: captura de intención, análisis de requisitos, generación de código, compilación y pruebas. Cuatro etapas, cuatro puntos de aprobación.

La captura de intención preguntó cómo quería responder (guiado, editando el archivo o conversando libremente) y luego hizo seis preguntas: el problema, quién se beneficia, cómo se ve el éxito, por qué ahora, qué queda fuera y quién decide. En modo guiado cada una llega como una pregunta con opciones clicables en el chat, y cada respuesta se escribe en un archivo de preguntas que se queda en el repositorio.

Dos momentos destacaron:

  • Preguntó en vez de adivinar. El selector de Claude Code muestra como máximo cuatro opciones, así que una pregunta de cinco opciones llegó en dos mitades, y elegí algo en las dos. La siguiente pregunta fue una aclaración de una línea sobre cuál de las dos respuestas quería decir.
  • La revisión no se limitó a decir "se ve bien". Un agente revisor con rol de líder de producto leyó la declaración de intención y devolvió cuatro observaciones: "sesión válida" nunca se definía, faltaban algunos supuestos (¿el registro necesita confirmar el correo? ¿el plugin funciona en una exportación web?), el problema era más amplio que las comprobaciones y no había límite de tiempo. Aun así su veredicto fue READY, porque la revisión es orientativa: las observaciones me llegan en el punto de aprobación, y aprobar las registra como riesgos aceptados.

Antes de la aprobación, AI-DLC me mostró sus propias notas de la etapa y me preguntó cuáles conservar. Conservé tres y las guardó como reglas del proyecto. La siguiente etapa empieza con ellas cargadas.

Lo que me diría el primer día

  • Decide el proceso antes de ejecutar cualquier script de configuración. Yo ejecuté primero el script de arranque de mi flujo anterior y tuve que deshacerlo.
  • Lee cada simulación. Los números son el mejor resumen de lo que AI-DLC le va a hacer a tu repositorio.
  • Trata los avisos del doctor como preguntas, no como alarmas. Los dos míos tenían explicaciones aburridas.
  • Empieza con un poc. Es lo bastante corto para aprender el ciclo de preguntas, revisión y aprobación sin apostar todo el proyecto.

Lo que viene

La parte 2 termina la prueba de concepto: los requisitos, el código que AI-DLC planifica y escribe (en un poc empieza a construir sin esperar a que apruebe el plan), y si un build de Godot 4.7 de verdad inicia la sesión de un jugador, en escritorio y en el navegador.

Artículos relacionados