Llevo meses programando con agentes de código, y la pregunta que más me hacen no es «¿funciona?», sino «¿cómo te fías de lo que te entrega?». He intentado contestarla con un tutorial entero: iadev.xavi.net, diez capítulos para programar con IA con método, cada uno con una demo que se ejecuta en el navegador y con un proyecto real detrás del que se puede leer cada línea.
Este artículo cuenta qué hay dentro, qué me ha sorprendido construyéndolo y por dónde empezar si quieres probarlo.
El problema, en un experimento
El tutorial empieza con una prueba que cualquiera puede repetir. Le di el mismo encargo de una línea a once agentes de tres proveedores: «Hazme un acortador de URLs en JavaScript: un módulo sin dependencias que guarde los enlaces en memoria». Los once escribieron un programa que funciona. Y los once son distintos: qué pasa si acortas dos veces la misma URL, si un alias vale con espacios, si una dirección javascript: se acepta. Cada agente decidió por su cuenta, en silencio, porque nadie le había dicho nada.
Ese es el problema que resuelve el método, y no es un problema de la IA. Es de lo que no le dijiste. Los once programas están en el capítulo 1, ejecutables, con un selector de proveedor para comparar.
Qué hay en los diez capítulos
El método es SDD más TDD, especificaciones y tests primero, adaptado a trabajar con agentes. Cada capítulo tiene una idea, una demo y fragmentos reales del proyecto que lo acompaña.
| Capítulo | La idea | La demo |
|---|---|---|
| 1. Sin método | La IA decide lo que no le dijiste | Un prompt vago, once programas distintos |
| 2. Qué es SDD | La spec es el contrato | Detector de ambigüedades en una spec |
| 3. Escribir la spec con la IA | Que te entreviste, pero no con setenta preguntas | Constructor de criterios Dado / Cuando / Entonces |
| 4. Qué es TDD | El rojo demuestra que el test prueba algo | El ciclo, paso a paso |
| 5. De criterios a tests | Cuántos tests pide un criterio y cuáles se olvidan | La matriz criterio ↔ test de un proyecto real |
| 6. El contexto del agente | Lo que no lee, no existe | Monta un AGENTS.md y mira qué pasó con cada versión |
| 7. El bucle | Una sesión entera, commit a commit | 26 commits con el estado de la suite tras cada uno |
| 8. Revisar lo que hace la IA | Las trampas con las que un verde miente | Seis entregas, cuatro con trampa |
| 9. Cambiar requisitos | El cambio empieza en la spec | La spec ilumina los tests y ficheros que arrastra |
| 10. Calidad continua | Quién prueba los tests | Muta el código y mira quién se entera |
Y una plantilla para empezar: siete ficheros de texto, con las reglas que el agente lee al arrancar y los esqueletos de la spec. Se instala con un curl | tar y vale para un proyecto nuevo o para uno que ya tienes.
Un proyecto real detrás, no ejemplos inventados
La regla que me puse fue que ninguna afirmación del tutorial se apoyara en código inventado. Para eso construí acorta, un acortador de URLs en Go con interfaz en Vue, siguiendo el método al pie de la letra: la spec primero, los tests en rojo antes que el código, un agente por pieza con sus rutas acotadas, y cada encargo y cada informe guardados tal cual en una bitácora.
A día de hoy son 113 criterios numerados, 366 tests y 39 commits, públicos. Cuando un capítulo dice «el agente encontró ocho huecos en la spec», enlaza al fichero donde están los ocho. Cuando dice que un commit en verde no tocó ningún test, se puede comprobar con un git diff.
Lo que me ha sorprendido
Algunas cosas las sabía y otras no me las esperaba. Todas están medidas en el tutorial, con los datos a la vista.
- Pedir que pregunte funciona demasiado bien. «Hazme todas las preguntas que necesites» dio 23, 30 y 70 preguntas según el modelo. Nadie contesta setenta. El capítulo 3 es sobre cómo quedarse con las cuatro que cambian el producto y dejar a la vista lo que el modelo decide solo.
- Una regla de tres líneas cambia lo primero que hace el agente. Con la plantilla en una carpeta vacía, dos agentes de proveedores distintos preguntaron antes de escribir nada; sin ella, se pusieron a programar. Y cuando quité esa regla del fichero que se lee siempre pero la dejé en otro, un agente la encontró y el otro no. Lo que tiene que pasar siempre va en el fichero que se lee siempre (capítulo 6).
- El paso rojo es un revisor de specs. En acorta, escribir los tests destapó entre tres y nueve huecos por fase en una spec que ya había pasado una revisión humana. Los tres criterios que se añadieron después de aprobarla hablaban de lo que pasa cuando algo falla (capítulo 5).
- Cincuenta y dos huecos que no lo eran. La regla decía «el test nombra el identificador del criterio», y cada agente la cumplió a su manera: unos con guion en el nombre del caso, otros sin guion en el nombre de la función. Un informe automático habría dado 52 criterios sin test. La lección fue de redacción de reglas: decir dónde y con qué forma.
- Cambiar un requisito cuesta sobre todo spec y tests. Añadir autenticación a acorta fueron 85 líneas de spec, 842 de tests y 196 de código, y ni una línea en los tres paquetes que no tenían que cambiar (capítulo 9).
- Los mutantes confirman lo que la spec ya sabía. Rompí el código de acorta cincuenta veces a propósito. Los tests cazaron 47 de los 48 cambios válidos. El superviviente era una línea que la spec declaraba sin criterio porque no se puede provocar desde fuera. Y siete de los muertos los mató un solo test, casi siempre el del borde (capítulo 10).
Cómo está hecho el tutorial
Es una web estática hecha con Astro, servida desde Cloudflare Workers, sin framework de interfaz: las demos son islas pequeñas de JavaScript con su lógica separada del DOM para poder probarla.
Lo que más me importaba era aplicarle al tutorial su propia medicina. Cada afirmación que hace una página sobre acorta, sobre un experimento o sobre su propia demo está fijada por un test que la comprueba contra los ficheros reales: 162 tests en total. Antes de cada despliegue se ejecutan, y después un navegador sin interfaz recorre cada demo, en local y contra la web publicada. Han cazado cosas: dos cifras mal escritas en el capítulo 7 y un bloque que se veía cuando no debía en el 6. No llegaron a publicarse por eso.
Y lo escribí como cuenta el propio tutorial: con un agente de código orquestando, otros agentes implementando las piezas de acorta, modelos de tres proveedores en los experimentos, y yo decidiendo lo que cambia el producto y revisando el resto con la spec al lado. El capítulo 8 lo dice sin rodeos: lo que entrega un agente, sea código o prosa, se revisa contra la fuente, no contra su propio informe.
Por dónde empezar
- Lee el capítulo 1. Son diez minutos y la demo es el argumento entero.
- Baja la plantilla a una carpeta vacía, abre tu agente de código y dile qué quieres construir. Mira qué hace antes de escribir código.
- Clona acorta y lee
bitacora/002-fase-1-dominio.md: una fase entera, con los encargos y los informes tal cual.
mkdir mi-proyecto && cd mi-proyecto && git init
curl -fsSL https://iadev.xavi.net/plantilla.tgz | tar -xzSi algo de lo que dice el tutorial no se sostiene, el sitio para decirlo es el repositorio de acorta: cada afirmación tiene un fichero y un test detrás, y prefiero una corrección a una duda. El tutorial está en iadev.xavi.net.