Tu agente de programación copia tu peor código
Los agentes de programación copian la arquitectura que ven. Aprende qué hechos arquitectónicos conviene documentar (atributos de calidad, límites y ADR) y cómo comprobar su efecto.
Arquitectura de software · Fundición de software · Documentación de arquitectura

El vídeo está en inglés. La transcripción de abajo es una traducción.
El diff que parecía correcto
Este es un diff concreto de uno de mis proyectos de ejemplo. El agente de programación ha añadido una funcionalidad, los tests pasan, la comprobación de tipos está limpia y la revisión parecía correcta. Pero el código nuevo del módulo de facturación importa el almacén de datos del módulo de pedidos y lee los pedidos directamente del almacén de datos del otro módulo.
¿Era malo el código? No: era correcto, legible y estaba probado. Simplemente nadie le había dicho al agente que esa llamada está prohibida.
Esto ha pasado más de una vez en un proyecto de un cliente. Y cuando di la misma tarea a 5 sesiones nuevas de agente, pasó 5 de 5 veces. Te voy a mostrar qué lo detuvo realmente.
Después de este episodio podrás mirar una mala salida de un agente y preguntarte qué hecho arquitectónico faltaba en realidad. Y podrás escribir ese hecho donde el agente lo lee. Verás una configuración pequeña y concreta, y una forma de comprobar si funciona: la misma tarea, el mismo modelo, el mismo prompt, ejecutados varias veces, antes y después.
Los agentes copian lo que ven
Esto es lo que me sorprendió. Con la versión limpia de mi ejemplo, el agente no cometió ese error. Cinco sesiones de cinco mantuvieron la facturación fuera de los datos de pedidos sin que nadie se lo dijera. El código limpio transporta su arquitectura, y el agente la lee.
Así que cambié una cosa. Hice que la base de código pareciera una real tras unos años, donde alguien ya ha tomado un atajo. Importaron directamente el almacén de datos de pedidos aquí, en el módulo de usuarios, para leer el número de pedidos del usuario. El número de pedidos se lee aquí abajo, accediendo directamente al almacén de datos de pedidos. Y nadie les dijo que eso era un error, ni estaba escrito en ningún sitio.
Estos son los diffs de los agentes que trabajaron sobre el código. Sobre ese código erosionado, todas las sesiones copiaron el atajo. Tres de ellas incluso lo envolvieron con elegancia: un port en facturación más un adapter en facturación que importa pedidos. Parece puertos y adaptadores, pero la dependencia apunta en la dirección equivocada. Los tests estuvieron en verde todas las veces.
La mayoría de las malas salidas de un agente son una solución local correcta. El agente sigue el precedente que encuentra en el código, y solo el equipo sabe que ese precedente es erróneo.
El agente ve los archivos que abre, no tu historia. Los atributos de calidad, los límites de contexto y las opciones descartadas viven en las cabezas, en wikis que nadie abre y en reuniones antiguas.
Un ejemplo: un agente rompe el límite, lo corregimos en la revisión, y en la siguiente sesión lo rompe otra vez. Las correcciones en el chat desaparecen con la sesión. Solo persiste lo que está en el repositorio.
Quizá digas ahora: «Un modelo mejor inferirá la arquitectura en el futuro». Con código limpio ya lo hace, pero solo puede inferir lo que el código muestra. Cuando el código contradice tu intención, el agente no distingue la regla de la excepción, y no sabe por qué facturación no debe leer datos de pedidos.
Qué escribir
Tres tipos de conocimiento cambian más la salida del agente: los atributos de calidad, los límites de contexto y las decisiones con sus razones.
Debes tener los atributos de calidad como enunciados comprobables. No solo «nuestro sistema tiene que ser muy rápido y escalable», sino «300 milisegundos para el checkout en el 95 % de los casos, con carga normal». Facturación puede desplegarse sin pedidos. Esto guía al agente. «Escalable», a secas, no.
Bounded contexts: nómbralos, enumera quién puede hablar con quién y explica cómo, por ejemplo mediante eventos o APIs, nunca mediante el almacén de datos del otro módulo. Un párrafo y un diagrama pequeño en forma de texto.
Y los ADR: contexto, decisión, consecuencias y, sobre todo, las alternativas descartadas. Si no, el agente vuelve a proponer la alternativa descartada, con total seguridad. Y en una base de código erosionada, la alternativa descartada suele estar ahí mismo, en el código, esperando a ser copiada.
Un ejemplo: el ADR de mi muestra. Facturación lee los datos de pedidos solo a través de un port propio. Uso el formato Y-statement, que es una frase de seis partes. Dice así. En el contexto de emitir facturas para pedidos, ante las preocupaciones que tenemos, que son dos: versiones independientes de facturación y pedidos, por un lado, y propiedad de datos independiente, por otro. ¿Qué decidimos? Decidimos usar un port en facturación que el composition root rellena desde la API pública del módulo de pedidos, y descartamos otras opciones, como que facturación importe el almacén de pedidos o un adapter dentro de facturación que importe pedidos. Buscamos que facturación pueda desplegarse sin pedidos, aceptando una función más de conexión.
Quizá digas: «Es mucho que escribir». Cierto, así que aquí tienes un consejo para ahorrar tiempo. Empieza por la decisión que tu agente ya ha roto. Escribe el ADR a partir del comentario de revisión que hiciste. Y haz lo mismo la próxima vez que tu agente no haga lo que quieres.
Ponlo donde el agente lee
El conocimiento solo ayuda si está en el contexto del agente en el momento adecuado y si es lo bastante corto como para usarse.
En mi ejemplo hizo falta muy poco. Un CLAUDE.md corto que dice: cada módulo es dueño de sus datos, un módulo importa solo sus propios archivos, cuando necesita algo de otro módulo declara un port, y el composition root, src/app.ts, rellena los ports. Además, ese composition root vacío, para que haya un lugar evidente para la conexión.
En un sistema real, CLAUDE.md crece hasta contener el propósito del sistema, los tres atributos de calidad principales, el mapa de contextos y reglas como «antes de cambiar nada que afecte a varios módulos, lee docs/adr/», y un índice de ADR con resúmenes de una línea. Este índice importa. El agente abre el ADR relevante para la tarea en lugar de cargarlo todo. Por eso conviene que los títulos de los ADR sean afirmaciones, como «Un bounded context nunca lee datos de otros bounded contexts».
Antes: facturación lee el almacén de pedidos. Después: facturación declara un port, pedidos publica el método de lectura y src/app.ts conecta ambos. En las cinco sesiones.
Para ser justos, es un modelo, una funcionalidad, cinco ejecuciones cada vez. Tu agente y tu base de código pueden comportarse de otra manera, así que mídelo con tu propio código. Ejecuta la misma tarea varias veces antes y después, y compara los diffs.
Hazlo cumplir y mantenlo vivo
La documentación que el agente lee es la primera capa. Las comprobaciones que hacen fallar el build son la segunda. El agente hace barato mantener la documentación al día.
Convierte las reglas más importantes en fitness functions: un test de arquitectura, por ejemplo con ArchUnit, import-linter o algo equivalente, que falle ante cualquier import que cruce el límite de un módulo. Las violaciones heredadas, si existen, van a una lista que solo puede reducirse.
Aquí me sorprendió otra vez. En mis ejecuciones, el test nunca se puso en rojo. Los agentes lo leyeron antes de su primera edición y lo siguieron. Incluso sin CLAUDE.md, el test y el composition root vacío mantuvieron a las cinco sesiones dentro de sus límites. Así que el test también es documentación, y una que, por suerte, no puede quedarse obsoleta sin que el build te avise.
¿Detectará este test a un agente que lo ignora todo? Mis ejecuciones no podían mostrarlo, porque ningún agente lo hizo. Precisamente por eso está ahí. No cuesta nada mientras el agente se comporta, y detiene el merge cuando no lo hace. También sirve como buen juez. Ejecútalo tras cualquier sesión de agente, y cada línea en rojo nombra un import nuevo que cruza el límite.
Quizá pienses: «Eso es solo documentación, nunca la mantuvimos al día». Bueno, hay una cosa que cambia cuando introducimos agentes de programación. Antes, la documentación no tenía ningún lector que actuara según ella a diario. Ahora lo tiene. Un ADR obsoleto produce código erróneo de forma visible en pocos días, así que la obsolescencia se detecta.
Haz que el agente participe en el mantenimiento. Cuando un cambio contradice un ADR, el agente debe o bien seguirlo, o bien proponer un ADR nuevo en el mismo pull request. Una persona revisa esa decisión, no la prosa.
Así que mantenlo pequeño. Diez ADR precisos valen mucho más que cien que nadie lee. Por supuesto, nada de esto sustituye a las revisiones como es debido, y hasta un ADR puede estar equivocado. Pero al menos hace visible el desacuerdo.
Cierre y pruébalo tú mismo
Recuerda: tu agente copia la arquitectura que ve. Si tu código ya no la muestra, escríbela donde el agente lee.
Así que haz esto. Toma los tres últimos comentarios de revisión en los que le dijiste a un agente o a un colega: «aquí no lo hacemos así». Escribe cada uno como un ADR breve o como una línea de atributo de calidad, enlázalos desde CLAUDE.md y vuelve a ejecutar una de las mismas tareas. Compara los diffs. Opcionalmente, añade un test de arquitectura para la regla que más importó.
¿Quieres probarlo en la práctica? Usa el enlace a Architecture Practice Lab en la descripción de este vídeo. Obtienes el repositorio de ejemplo erosionado de este episodio. Dale la misma tarea a tu propio agente, Claude u otro, y comprueba si mantiene los límites. Después escribe la arquitectura, inténtalo de nuevo y recibe feedback de mi agente revisor, que entrené con reglas de buena arquitectura.
¡Hasta pronto!