Aprender AI-DLC creando un juego, parte 4: lo que vio la revisión

Esta es la parte 4 de una serie sobre aprender AI-DLC creando un juego, World Rift Conflict, en Godot con un backend en AWS. La parte 3 mostró lo que se construyó: un comando que ejecuta las pruebas de inicio de sesión en cuatro plataformas. Esta parte muestra la otra mitad de ese trabajo: lo que las revisiones y comprobaciones de AI-DLC detectaron antes de que nada se ejecutara.

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 (este artículo)
• Parte 5: dentro de una etapa

En resumen

1. Tres etapas tuvieron un agente revisor aparte. Dos dijeron NOT-READY con tres hallazgos mayores cada una; la revisión del código dijo READY.
2. El hallazgo más útil era sobre mí, no sobre el código: los requisitos habían relajado en silencio una regla que yo había aceptado menos de una hora antes.
3. La revisión del diseño encontró una barrera de producción que comprobaba la configuración, pero no la build que de verdad se iba a ejecutar.
4. Las revisiones de Inception tienen una sola pasada. Los arreglos posteriores no se vuelven a revisar, así que es en la aprobación donde tuve que leerlos.
5. Cada lección se convirtió en una regla del proyecto que leen las etapas siguientes. De este trabajo salieron diez.

Cómo funciona una revisión aquí

Una etapa con revisor escribe primero sus documentos. Después AI-DLC registra una petición de revisión y entrega los documentos a otro agente con otro papel: un responsable de producto para los requisitos y un revisor de arquitectura para el diseño y el código. El revisor solo lee los archivos que recibe, nunca el diario del autor, y escribe sus hallazgos en una tabla con una gravedad para cada uno.

Dos detalles importan:

• El revisor nunca ve lo que pensaba el autor. Tiene que juzgar los documentos tal como están escritos.
• La clase decide qué pasa después. Las revisiones de Inception son consultivas: una pasada, y los hallazgos van a mi aprobación. La revisión de Code Generation es adversarial: hasta dos pasadas, con arreglos entre medias.

Requisitos: una regla aceptada, relajada en silencio

La revisión del responsable de producto volvió NOT-READY, con 3 hallazgos mayores y 4 menores. El primero de los mayores (cito el original en inglés):

FR19 says deleting test accounts in the test backend "needs no extra go". The team's affirmed Deployment practice says every AWS action, and it names "deleting test users", waits for the person's go. The person was never asked about this.

Es decir: el requisito FR19 decía que borrar cuentas de prueba no necesitaba autorización, mientras que la práctica acordada del equipo dice que toda acción en AWS, y nombra expresamente "borrar usuarios de prueba", espera mi autorización. Y nadie me lo había preguntado.

Tenía razón. Menos de una hora antes, en Practices Discovery, había aceptado que toda acción en AWS, incluido borrar usuarios de prueba, espera mi autorización. El borrador de requisitos quería ejecuciones que no necesitaran nada de mí, así que decidió sin más que borrar cuentas no contaba. Los dos objetivos eran razonables; elegir entre ellos me tocaba a mí, no al borrador.

Así que el agente me lo preguntó, con el compromiso explicado: una autorización permanente solo para cuentas del dominio de prueba en el grupo de prueba, o una autorización en cada ejecución. Elegí la permanente. Quedó escrita en las reglas como una enmienda, y cualquier otra acción en AWS sigue esperándome.

Los otros dos hallazgos mayores eran de los que yo no habría visto:

• La comprobación de producción no tenía criterio de aceptación. El requisito decía "se muestra la pantalla de inicio de sesión", pero el juego web dibuja en un único canvas, así que nada en la página dice qué hay en pantalla. El requisito se acotó a lo observable: la página responde, el motor arranca y la consola no muestra errores.
• Faltaban los casos límite de la limpieza. Una ejecución interrumpida no puede limpiar lo suyo. Los arreglos: la siguiente ejecución limpia primero; una cuenta de prueba se distingue de una real por el dominio de su correo; los correos con códigos guardados caducan al día; y solo se permite una ejecución a la vez por máquina.

Diseño: una barrera que miraba lo que no era

La revisión de arquitectura del diseño también volvió NOT-READY con 3 hallazgos mayores. El que más me hace pensar:

A stale or copied export pointing at production would pass the guard

Es decir: una exportación antigua o copiada que apuntara a producción pasaría la barrera.

El diseño tenía una barrera de producción: antes de una ejecución, comparar el ID del grupo de usuarios de prueba con el de producción y negarse si coinciden. Pero la barrera leía los IDs de archivos de configuración, mientras que la build del juego que de verdad se ejecuta lleva su propia copia de la configuración dentro. Una build de prueba olvidada de otro día, o copiada por error, podía apuntar a producción sin que la barrera se enterara.

El arreglo: cada build de prueba registra para qué grupo se construyó, y el controlador lo compara con el grupo de prueba aprobado antes de lanzar el juego. Ante cualquier diferencia, se niega. Esa comprobación tiene ahora su propia prueba de regresión.

Los otros dos:

• Faltaba la estimación de coste. Los requisitos decían que el diseño mostraría que el entorno de prueba no pasa de unos 5 dólares al mes, y no lo hacía. Ahora sí: menos de 0,15 dólares al mes con 100 ejecuciones.
• Tareas sin dueño. Nada se encargaba de desplegar el backend de prueba ni el buzón, los pasos que necesitan mi autorización, ni de limpiar los correos. Un componente número 16, TestEnvironment, es ahora dueño de toda acción en AWS que necesite autorización. Eso también se convirtió en regla para los diseños futuros.

Código: READY, con cinco notas

La revisión del código ejecutó por su cuenta las suites locales (29 pruebas de Godot, 89 de TypeScript, 8 de la plantilla, todas pasando). Dijo READY, con cinco notas menores. Dos de ellas cambiaron lo que hice después en Build and Test:

• El nuevo paso de Amplify no se había probado donde se ejecuta. Las pruebas de Godot solo se habían ejecutado en mi máquina, no dentro de la imagen de build propia, así que el primer push habría sido su primera ejecución allí. Un fallo bloquearía el despliegue de producción. El paso se ejecutó en la imagen desde una copia limpia antes de cualquier push: 29 de 29.
• El hook web solo se había probado con dobles. Las ejecuciones completas en Chromium, Firefox y WebKit lo usaron después de verdad.

El límite de una pasada

Después de arreglar los requisitos, intenté que se volvieran a revisar. AI-DLC se negó:

Cannot request review pass 2 for "requirements-analysis" because this stage allows 1 review pass. Do not ask the reviewer again; include the findings in the approval summary for the human.

Es decir: esta etapa permite una sola pasada de revisión; no se vuelve a pedir, y los hallazgos van en el resumen de la aprobación para la persona.

Es a propósito. Los documentos de Inception son cuestión de criterio, y una segunda pasada automática sobre todo retrasa a quien tiene que decidir. Pero significa que comprobar los arreglos me toca a mí: cada aprobación enumeraba los hallazgos, los arreglos y el hecho de que los arreglos no se habían vuelto a revisar.

Las comprobaciones pequeñas

No todo lo detectó un revisor:

• Trazabilidad. La comprobación del diseño marcó FR2.1 y FR2.2 como ausentes. Eran IDs de la prueba de concepto citados en los requisitos de este trabajo, así que los asigné a los escenarios que los cubren.
• Secciones obligatorias. Dos documentos de Build and Test tenían muy pocos encabezados para leerse como documentos estructurados. Añadí las secciones antes de aprobar.
• Barreras sobre el agente. Un hook bloqueaba comandos de shell mientras no existía un plan aprobado: "Code generation cannot run mutation-capable shell commands ... code-generation-plan.md is missing or empty." Otro obligaba al agente a registrar el veredicto de cada revisión antes de hacer nada más. Los dos evitaron hacer cosas en el orden equivocado.
• Un objetivo que no podía pasar. Un requisito pedía que "la factura del primer mes" confirmara el coste. Esa factura todavía no existe, así que AI-DLC la contó como no verificada y me obligó a aceptarlo de forma explícita. Esa fue culpa de mi redacción.

En números: 57 ejecuciones de sensores, 54 pasaron.

Adónde van las lecciones

Al final de cada etapa, AI-DLC muestra las notas del diario de la etapa y pregunta cuáles guardar. Una nota guardada se convierte en una línea de las reglas del proyecto, que cada etapa posterior lee antes de empezar. De este trabajo salieron diez. Las que cambiaron etapas posteriores:

• Cuando un requisito o un diseño cambie o relaje una práctica acordada, preguntar primero a la persona.
• En un diseño, cada acción en AWS que necesita autorización tiene un único componente dueño.
• Antes de pedir autorización para un despliegue, comprobar en modo lectura lo que permite la cuenta. Esa comprobación encontró mi zona DNS en la parte 3 y eliminó un paso manual.
• Probar cualquier cambio de amplify.yml dentro de la imagen de build antes de un push.
• Escribir criterios de aceptación que se puedan comprobar dentro del trabajo.
• Rellenar las preguntas estándar de una etapa con lo que ya está decidido y preguntar solo lo que sigue abierto.

Lo que me diría a mí mismo

• Lee los hallazgos de la revisión como preguntas para ti, no como defectos. El mejor era sobre una decisión que solo yo podía tomar.
• La falta de contexto del revisor es justo lo útil. Juzga lo que dicen los documentos, no lo que todos querían decir.
• Cuando una etapa permite una sola pasada de revisión, lee tú los arreglos en la aprobación. Nadie más lo hará.
• Guarda las reglas. La segunda mitad de este trabajo fue más rápida porque la primera dejó por escrito lo que aprendió.

Qué viene después

Las pruebas se ejecutan solas y las reglas que les dieron forma están escritas. La parte 5 mira de cerca una etapa, paso a paso. Después empieza el juego real: un trabajo mvp y sus primeras etapas, de una idea de juego a un alcance aprobado.