Las pruebas de especificación corrigieron la deriva arquitectónica: un agente arregló 637 tamaños de fuente de una sola vez

Existe un experimento conocido: se pide a ChatGPT que haga una copia exacta de una imagen sin cambiar nada y se repite el proceso 101 veces. Al final, la fotografía de Dwayne Johnson se convierte en una masa caricaturesca. Cada paso por separado es casi fiel, pero el resultado acumulado es algo completamente distinto.

Con el código gestionado por un agente de IA sucede lo mismo. El autor del análisis lo denomina deriva arquitectónica. El ejemplo más claro está en el frontend: la tipografía está definida y es la misma en todas partes, pero cada página emplea tamaños propios y el estilo general del sitio se descompone. El principio se aplica a cualquier área del desarrollo: la fuente de verdad empieza a divergir.

La verdad está en la especificación, no en el código

El autor no lee el código en absoluto; solo controla las especificaciones. La lógica es sencilla: la especificación es el plano y el código es la pieza. La pieza se compara con el plano, no con otra pieza. Dos fuentes de verdad generan caos.

Toda la documentación se encuentra en la carpeta docs de la raíz del proyecto. A fecha del 5 de noviembre de 2026, contenía 7.478 archivos .md distribuidos en 11 niveles de anidamiento. El 95,3% de las carpetas tenía como máximo 7 archivos y el 97,4%, como máximo 9. Es la regla de “7 más o menos 2”, que facilita tanto a las personas como a los agentes entender dónde está cada cosa. Los agentes escriben y leen las especificaciones, mientras que una persona las consulta en un formato cómodo desde el panel de administración.

Por ejemplo, todas las reglas tipográficas están reunidas en un único archivo typography.md. Allí se definen 22 roles, cada uno con su familia, tamaño para escritorio y móvil, peso y color. Por ejemplo, el párrafo de un artículo usa Charis 21/30 y el estilo base, Inter 14/21. Todo el sitio emplea dos familias y únicamente los pesos 400 y 700. La regla principal es que no puede existir ningún estado fuera del registro: una nueva combinación implica una nueva fila aprobada mediante un veredicto.

Obligar a leer y verificar de forma determinista

Por sí solas, las especificaciones funcionan de manera probabilística: el agente puede seguirlas o puede ignorarlas. Por eso existen dos capas de protección.

La primera es el archivo AGENTS.md. En él se establece que, antes de una tarea, el agente debe leer la documentación de la carpeta correspondiente. Si hace falta auditar los costes de la nube, entra en la carpeta dedicada a la nube y revisa todos los proveedores. Según la estimación del autor, las reglas se respetan en 9 de cada 10 casos.

La segunda capa son las pruebas de especificación para el “décimo caso”. Una prueba lee las tablas de typography.md, reúne los pares de tamaños permitidos y recorre todo el frontend. Cualquier par ajeno a la especificación hace fallar la compilación e indica el nombre del archivo y la línea.

Lo que reveló la prueba

Hasta el 6 de noviembre, la prueba utilizaba una lista de bloqueo con nueve pares obsoletos. Mientras preparaba el artículo, el autor descubrió que el código contenía unos 150 pares ajenos a la especificación. En una sola pasada, el agente ajustó 637 usos a la especificación, añadió las 4 filas que faltaban y reescribió la prueba para usar una lista de elementos permitidos. Esta es la principal lección práctica: una lista de bloqueo solo detecta lo que ya se conoce; una lista de elementos permitidos detecta todo lo demás.

Si la documentación y el código aun así divergen, ayuda seguir este orden: primero las pruebas, después la autorreparación en producción—sobre la que el autor promete otro artículo—y solo entonces una persona. Su tarea no consiste en detectar el fallo, sino en entender por qué logró pasar y cerrar esa brecha.

Limitaciones y conclusión

El enfoque exige disciplina: hay que mantener miles de documentos de forma coherente, y los ejemplos del autor se centran principalmente en la tipografía, donde la verificación es sencilla. Escribir pruebas de especificación para la lógica de negocio resulta más difícil. Es la experiencia de un solo proyecto, las cifras son autodeclaradas y la encuesta situada bajo el artículo recibió un voto.

La conclusión práctica para quienes trabajan con agentes es trasladar las reglas a especificaciones legibles por máquinas, establecer en AGENTS.md su lectura obligatoria antes de cada tarea y convertir las desviaciones más frecuentes en pruebas basadas en listas de elementos permitidos. El autor publicó en GitHub el propio armazón—AGENTS.md, CLAUDE.md y una carpeta docs sin código—, por lo que se puede empezar con una plantilla ya preparada.