Capítulo 07 de 10 · 10 min de lectura
El bucle: tarea, test, código
El método, visto desde fuera, es un bucle corto que se repite: encargo, rojo, verde, revisión, commit. Esta es la sesión de acorta tal como quedó en Git.
La sesión, commit a commit
Los capítulos anteriores han enseñado las piezas por separado: la spec, los tests, el fichero de reglas, el encargo. Falta verlas juntas, en el orden en que pasan. Esta es la sesión en la que se construyó acorta, recorrida por sus commits, desde las specs hasta el cierre de la v1 (lo que vino después, un cambio de requisitos, tiene su capítulo). Para cada uno, lo que cambió y el estado de la suite entera justo después, medido ejecutando los tests en ese commit.
spec rojo verde arreglo de tests otro
3f7b8e3 Specs de la v1, reglas para agentes y bitácora de la entrevista
El contrato de acorta antes de escribir código: producto y alcance (000), plan técnico (001), reglas de dominio con criterios numerados (002), almacén SQLite (003), API y redirección (004), CLI (005), interfaz web (006) y fases de implementación (007). AGENTS.md fija cómo trabajan los agentes y bitacora/001 recoge la entrevista, las decisiones tomadas por defecto y el cambio pedido en la revisión.
- .gitignore+15
−0 - AGENTS.md+21
−0 - CLAUDE.md+9
−0 - README.md+7
−0 - bitacora/001-entrevista.md+81
−0 - specs/000-especificacion.md+63
−0 - specs/001-plan-tecnico.md+72
−0 - specs/002-enlaces.md+174
−0 - specs/003-almacen.md+51
−0 - specs/004-api.md+93
−0 - specs/005-cli.md+54
−0 - specs/006-web.md+55
−0 - specs/007-fases.md+42
−0
Recórrela con «Siguiente» o con las flechas del teclado. Hay un ritmo que se repite seis veces, una por pieza del programa:
- Un commit de spec que cierra los huecos que destapó el paso rojo.
- Un commit en rojo: los tests de la pieza y un esqueleto que compila. La barra de ese paquete aparece en rojo, y las demás siguen como estaban.
- Un commit en verde: la implementación. La barra pasa a verde y no se toca ningún test.
Dos veces se cuela un commit de arreglo entre el rojo y el verde: un test estaba mal y se corrigió aparte. Una vez, el verde de la interfaz llega cinco commits después de su rojo, con los casos de uso enteros en medio: dos agentes trabajaron a la vez. Y antes del primer ciclo hay dos commits que no vuelven a repetirse: las specs enteras y el esqueleto del módulo.
Quién hace qué
En la sesión hay dos papeles, y conviene no mezclarlos.
El orquestador es la sesión principal. Especifica, reparte, revisa y hace los commits. No escribe el código de las piezas. En acorta lo hizo un agente de código con una persona detrás, pero el papel es el mismo si lo haces tú a mano.
Cada pieza la implementa un agente que arranca sin saber nada del proyecto y solo puede tocar los ficheros de su fase. La tabla está en la spec de fases:
| Fase | Qué | Rutas que puede tocar | Depende de |
|---|---|---|---|
| 1 | Dominio | link/** |
0 |
| 2 | Almacén | store/** |
1 |
| 3 | Casos de uso | shortener/** |
1, 2 |
| 4 | API, redirección y estáticos | server/** |
3 |
| 5 | CLI | cmd/acorta/** |
3, 4 |
| 6 | Interfaz web | web/** |
4 |
La columna de rutas es la que hace posible lo demás. Si un agente solo puede tocar store/, revisar su trabajo es revisar store/, y dos agentes con rutas distintas no se pisan: la 5 y la 6 podían ir en paralelo.
Las tareas son pequeñas por la misma razón. Un paquete cabe en el contexto de un agente con su spec, se verifica en minutos y, si sale mal, se tira y se repite sin tocar lo demás.
Un ciclo entero
Esto es lo que pasa entre dos commits en verde consecutivos. Lo cuenta la bitácora de la fase 1, que es la que mejor se lee.
Encargo rojo. El orquestador escribe el encargo de seis partes del capítulo anterior y se lo da a un agente nuevo: solo los tests, con la función vacía, y que enseñe que fallan.
Informe. El agente devuelve lo que se le pidió: ficheros, recuento, la tabla criterio → test y las ambigüedades que ha encontrado. En la fase 1 fueron ocho.
Revisión. El orquestador comprueba el informe por su cuenta y decide qué hacer con cada ambigüedad. La bitácora lo dice así:
Comprobado de primera mano, sin fiarse del informe: solo hay ficheros nuevos en
link/;gofmtygo vetlimpios; los tests compilan y fallan; y los 20 criterios que tocan alinkaparecen nombrados en algún test (los 4 que faltan, COD-02 a COD-04 y CAD-06, son del paqueteshortener).
Las ambigüedades se cierran en la spec, no en el código: de ahí sale el commit de spec que precede a cada rojo. Después, un encargo corto para que el agente ajuste los tests a la spec nueva, y el commit en rojo.
Encargo verde. Al mismo agente: implementa hasta que pase la suite, sin tocar los tests, y si un test está mal, párate y dilo.
Verificación y commit. git diff sobre los tests, vacío. Suite en verde. Y una lectura del código y del informe con la spec al lado, que es lo que no hace ninguna herramienta. Commit en verde.
Son siete pasos, y en la fase 1 el agente trabajó unos tres minutos en total. La bitácora remata con una frase que vale para toda la sesión:
Lo que más tiempo llevó de la fase no fue código: fue decidir qué decía la spec.
Cuando el agente para
Dos de los 26 commits son arreglos de tests, y los dos siguen el mismo guion. El agente llega al verde menos uno o dos, mira los tests que fallan, concluye que ninguna implementación correcta podría pasarlos, y en vez de retocarlos lo dice. Uno buscaba un botón por un texto que ya había cambiado. Otro medía una columna en bytes. El orquestador los corrige en un commit propio, con el porqué en el mensaje, y el ciclo sigue.
Hay una tercera parada que no dejó commit de arreglo, porque el agente no paró: el del servidor repartió las rutas a mano cuando el plan técnico decía otra cosa, y entregó «desviaciones de la spec: ninguna». Se vio leyendo el informe. Lo que se decidió fue aceptar el cambio y cambiar la spec en el mismo commit, que por eso toca dos ficheros de specs/.
La verificación final también falló a la primera, y lo que falló fue el guion de verificación, no el programa:
Seis comprobaciones del primer intento, y las seis eran errores del guion de verificación, no de acorta: el guion llamaba a
list -base-url, un flag que la spec acababa de eliminar, y esperaba los cuerpos de texto sin su salto de línea final, que la spec 004 exige. El binario hacía lo que dice la spec; el guion estaba escrito de memoria.
Cuánto tardó
Las fechas de los commits son públicas. Los 24 de la v1, de las specs a la verificación final, van de las 19:06 a las 19:31 del mismo día. Veinticinco minutos y medio de reloj entre el primero y el último, y no es el tiempo total del proyecto: antes hubo una entrevista, una spec de ocho ficheros y una revisión humana, que es la parte que no se automatiza.
Lo que sí dice es dónde está el coste. En la fase 1, la única con tiempos anotados, el agente trabajó unos tres minutos en total. El resto fue leer informes, decidir qué decía la spec y verificar. Con agentes rápidos, el cuello de botella es la persona que revisa, y el método está hecho para que esa revisión sea corta: rutas acotadas, tests que nombran su criterio, informes con una forma fija.
Al cerrar: 100 criterios, 246 tests de Go y 38 de la interfaz, todo en verde.
La bitácora
Todo lo que cuenta este capítulo está escrito en bitacora/, y no de memoria. Por cada fase hay un fichero con el encargo tal como se dio, el informe tal como llegó y la revisión. Es la regla que el orquestador se puso a sí mismo en CLAUDE.md:
Por cada fase, guardar en
bitacora/el encargo dado al agente y su informe, tal cual.
Sirve para revisar después, para que el siguiente agente sepa qué pasó, y para esto: cada cita de este tutorial se puede comprobar contra ese fichero.
Lo que viene
El bucle funciona porque hay alguien revisando entre el informe y el commit. El capítulo siguiente trata de esa revisión: qué mirar en lo que entrega un agente, y las trampas que un verde puede esconder.