Design your repo so agents work better

Tu codebase influye más en el resultado del agente que tu prompt o tu AGENTS.md. Y eso es una buena noticia: es lo único de la lista que puedes diseñar en lugar de redactar mejor.

La idea no es mía: la desarrolla AI Hero en un artículo que me hizo repensar mis repos, y se apoya en un concepto clásico de diseño de software. - Source: How To Make Codebases AI Agents Love - AI Hero

Lo que el agente ve (spoiler: no ve tu mapa mental)

Tú tienes un mapa mental del proyecto: aquí está la autenticación, allá el editor, esto es la facturación. El agente no. Lo que ve es una lista de módulos que pueden importarse entre sí, sin agrupaciones ni jerarquía. Y el agente es, en palabras del artículo, "un nuevo empleado sin memoria" que entra cada vez a preguntar "¿qué estoy haciendo?". - Source: How To Make Codebases AI Agents Love - AI Hero

Si estás lanzando veinte de esos "nuevos empleados" al día sobre tu repo, el repo tiene que ser navegable para ellos.

Los 3 costos de un codebase hostil

Feedback loops pobres: el agente no sabe si su cambio hizo lo que quería.
Difícil de navegar: no encuentra archivos ni cómo probar.
Burnout cognitivo: terminas tú sosteniendo el hilo entre el agente y el código, parcheando a mano.

Fuente: How To Make Codebases AI Agents Love - AI Hero

Los tres son medibles: tiempo del build/test, número de "no encuentro X" del agente, y cuántas veces tuviste que intervenir.

La solución: módulos profundos

El concepto viene de A Philosophy of Software Design: mucha implementación detrás de una interfaz simple. En lugar de veinte módulos chicos e interconectados, siete u ocho bloques grandes con una interfaz clara. Todo lo que exporta sale por esa interfaz. - Source: How To Make Codebases AI Agents Love - AI Hero

Esto se traduce en el sistema de archivos: cada módulo con su carpeta y su interfaz pública. El agente lee las interfaces y entiende el proyecto sin abrir la implementación.

Grey box: tú la interfaz, la IA la implementación

La parte que hace esto funcionar: los módulos grey box. Tú diseñas y controlas la interfaz; delegas la implementación al agente; los tests fijan el comportamiento. Mientras pasen, no necesitas leer lo de dentro (aunque puedas, si quieres aplicar gusto o afinar rendimiento). - Source: How To Make Codebases AI Agents Love - AI Hero

Es la versión práctica de "no revises cada línea generada": revisas los límites y el contrato, y dejas que los tests te avisen.

Las 3 decisiones de repo que aplico

Módulos profundos con interfaz explícita. Cada dominio, una carpeta; todo lo que entra o sale, por su interfaz. Si el agente tiene que abrir cinco archivos para entender un concepto, ahí falta un módulo.
Tests que fijan el comportamiento, no la implementación. Son el contrato que permite delegar. Y son el feedback loop del agente.
Documentación progresiva. Un AGENTS.md chico en el root y reglas por dominio en archivos aparte. El agente lee la interfaz y, si necesita más, las migas de pan.

Y una cuarta operativa: feedback loops rápidos. Build, test y lint en segundos. Sin eso, el agente trabaja a ciegas y tú revisas de más.

Cómo empezar esta semana

Dibuja tu mapa mental en un papel: siete u ocho bloques, no cuarenta.
Compara con el sistema de archivos y marca dónde no coinciden.
Elige un módulo de los que el agente toca seguido y dale una interfaz explícita con tests.
Mide antes y después: ¿el agente encontró los archivos sin ayuda? ¿Cuántos pasos tardó?
Repite semanalmente. Hay incluso una skill pública que audita el repo y propone interfaces más profundas (/improve-codebase-architecture). - Source: 5 Agent Skills I Use Every Day - AI Hero

Esto conecta con el resto de la serie: es la pieza de "entorno y verificación" del harness (las 9 piezas), y es la base sobre la que funciona el flujo completo.

¿Tu codebase está diseñado para humanos con memoria o para agentes sin memoria? Si tienes más de veinte módulos en la raíz, ya sabes la respuesta. Cuéntame en los comentarios.