Le pides a Claude que añada una funcionalidad. El resultado parece correcto. Código limpio, imports bien puestos, comentarios seguros. Entonces lo lees despacio y te das cuenta de que el agente se ha inventado una convención interna que no existe, ha ignorado la que sí existe y ha nombrado la función con un estilo que descartaste hace seis meses en una PR que nadie enlazó a la IA. El agente no se equivocó. Trabajó con lo que podía ver.
Esa es la pregunta honesta detrás de "¿está mi repo listo para la IA?": no si has instalado el último modelo, sino si un agente que aterriza en tu base de código por primera vez puede entender de verdad cómo funcionan las cosas. AGENTS.md, CLAUDE.md, DESIGN.md, skills, workflows, postmortems, OpenSpec — la pila de convenciones no para de crecer, y desde dentro es casi imposible saber si la señal que emites es la señal que el agente recibe.
Cómo lee un repositorio la IA
Cuando le pides a un agente que haga algo, no carga tu repositorio entero en su cabeza. No puede. El artículo Effective context engineering for AI agents de Anthropic lo explica con claridad: un modelo tiene un presupuesto de atención finito, y "cada nuevo token introducido reduce ese presupuesto en alguna medida". Una ventana de contexto de 200K tokens no garantiza que el modelo esté prestando la misma atención a todos los tokens. Está prestando progresivamente menos atención según se llena el presupuesto con cosas que no son determinantes para la tarea.
Por eso los agentes trabajan como un contratista nuevo cuidadoso: buscan un índice y lo siguen. El primer sitio donde miran es el fichero de entrada acordado. AGENTS.md es ya un estándar abierto — un único fichero en markdown plano compatible con OpenAI Codex, Cursor, Amp, Google Jules y Factory. GitHub Copilot siguió una ruta paralela con .github/copilot-instructions.md. La interfaz es sencilla: un fichero, texto plano, agnóstico de herramientas. El agente lo lee antes que tu código y lo usa para decidir qué más cargar.
Aquí es donde la mayoría de equipos se equivocan en el diseño. Convierten AGENTS.md en un documento de 500 líneas que lo contiene todo — reglas de testing, notas de despliegue, visión general de la arquitectura, convenciones de nomenclatura, política de seguridad, glosario. El agente lo lee con diligencia. Cuando llega a la línea 300, la regla de la línea 50 ya se está desvaneciendo. La guía de Anthropic es directa: encontrar "el conjunto más pequeño posible de tokens de alta señal" que el modelo necesita para hacer el trabajo.
La trampa está en confundir la existencia del fichero con la preparación real. El estudio AGENTbench de ETH Zúrich ejecutó 138 tareas Python en 12 repositorios reales y comprobó que los ficheros de contexto generados por LLMs empeoraban las cosas en 5 de 8 escenarios. Añadían entre 2,45 y 3,92 pasos de razonamiento extra por tarea y aumentaban los costes de inferencia entre un 20 y un 23%. El culpable no era la idea del fichero de contexto. Era el contenido: verboso, autogenerado, lleno de cosas que el agente podría haber inferido por sí solo. Un análisis de madurez que solo pregunta "¿existe el fichero?" está midiendo lo incorrecto. La pregunta es si el fichero contiene señal.
AGENTS.md como índice, no como muro
El patrón que sí funciona es el mismo que el modelo prefiere: carga just-in-time. Anthropic describe la técnica directamente — los agentes "mantienen identificadores ligeros... y usan esas referencias para cargar datos dinámicamente en el contexto en tiempo de ejecución". Aplicado a un repositorio de código: mantén AGENTS.md como un índice pequeño, y deja que apunte a ficheros temáticos que el agente carga solo cuando la tarea realmente los necesita.
- •Comandos build / test / lint
- •Reglas que aplican a todos los cambios
- •Enlaces a los docs por tema de abajo
Una forma concreta que escala a bases de código reales:
AGENTS.md— 50 a 100 líneas. Nombre del proyecto, comandos install / test / lint, las dos o tres reglas que aplican a todos los cambios, y una lista de enlaces a los docs por tema de abajo. Nada más.docs/testing.md— Cómo se organizan los tests en este repo, qué se mockea, qué espera el runner de CI. Se carga cuando el agente edita o añade tests.docs/api.md— Convenciones de endpoints, formas de error, patrones de auth. Se carga cuando el cambio toca código de API.docs/architecture.md— Fronteras entre módulos y reglas de dependencias. Se carga para refactors.
Dos reglas prácticas hacen funcionar este patrón. Primero, lo más importante va en la parte alta de cada fichero que el agente vaya a leer — aproximadamente las primeras 200 líneas. Ahí es donde la atención del modelo es más nítida, y también donde aplica el límite de líneas que Claude Code lee de CLAUDE.md. Lo que esté por debajo es invisible. Segundo, el índice enlaza a ficheros específicos, no a carpetas genéricas — "consulta docs/testing.md antes de cambiar tests" es una señal sobre la que el agente puede actuar; "la documentación está en docs/" no lo es.
Cuando el agente decide que está editando tests, sigue el enlace y carga docs/testing.md. Cuando despliega un cambio de API, carga docs/api.md. Las 200 líneas que importan están en contexto. Las 1.800 que no, se quedan en disco. El presupuesto de atención se mantiene enfocado en el trabajo.
Una nota específica de Claude: Claude Code busca concretamente CLAUDE.md, no AGENTS.md, así que el fichero tiene que existir igualmente en repositorios donde Claude forma parte del flujo. La solución pragmática es un symlink — ln -s AGENTS.md CLAUDE.md — para que Claude y el resto de herramientas lean la misma fuente única de verdad en lugar de dos ficheros que acaban divergiendo en silencio. Trátalo como una peculiaridad de la herramienta, no como una razón para mantener dos índices.
Por qué más es peor — la putrefacción del contexto
El hallazgo de ETH Zúrich tiene una explicación estructural. La investigación Context Rot de Chroma evaluó 18 modelos frontier y comprobó que la precisión cae más de un 30% para el contenido situado en el centro de un contexto largo, incluso dentro de una ventana de 200K tokens. Un AGENTS.md inflado entierra las reglas que importan bajo las que fueron fáciles de escribir. El agente lee el fichero, ofrece una respuesta segura y la instrucción relevante estaba en la página tres de un documento que tendría que tener media página.
Las mejores prácticas de Claude Code de Anthropic lo dicen directamente: el contexto conciso y enfocado supera al contexto exhaustivo. La guía de HumanLayer para escribir un buen CLAUDE.md llega a la misma conclusión desde la experiencia práctica. El modo de fallo no es un fichero que falta. El modo de fallo es uno que es demasiado largo.
La pregunta no es "¿tengo un AGENTS.md?". La pregunta es "¿actuaría de forma diferente un contratista experto, llegando en frío, después de leerlo?"
Cómo puntuar tu repositorio — herramientas automáticas de readiness
Factory.ai presentó Agent Readiness como un framework para puntuar repositorios contra cinco niveles de madurez en nueve pilares: estilo, compilación, testing, documentación, entorno de desarrollo, calidad de código, observabilidad, seguridad y herramientas de IA. Microsoft respondió con microsoft/agentrc, una CLI y extensión de VS Code con la misma forma de cinco niveles y nueve pilares. kodustech/agent-readiness es la alternativa open-source que hace el mismo análisis sin la capa comercial.
El agente puede navegar la estructura de ficheros, pero no tiene contexto sobre convenciones, comandos ni restricciones.
Estilo consistente, linter y formateador configurados, README básico presente.
AGENTS.md conciso, tests funcionando, CI en verde, entorno de desarrollo reproducible. La mayoría de equipos se queda aquí.
Logging estructurado, métricas y bucles de feedback — el output del agente se puede verificar contra señales reales.
Cobertura completa, seguridad endurecida, el agente opera de extremo a extremo sin supervisión.
La lógica detrás de todas ellas es idéntica: escanear el repositorio, puntuar cada pilar, producir un nivel de madurez. L1 es un repositorio en el que el agente apenas puede orientarse. L3 es el objetivo habitual — un repositorio en el que un agente puede ser productivo sin que le lleven de la mano. L5 es operación autónoma completa con observabilidad y seguridad endurecidas. La mayoría de equipos pequeños están entre L1 y L2 sin saberlo.
Estas herramientas son útiles como listas de verificación. No sustituyen a leer de verdad el fichero que consume el agente. Un repositorio puede pasar todos los checks automáticos y tener aun así un AGENTS.md que contradice la base de código porque nadie lo actualizó tras el último refactor. La puntuación es una señal, no una garantía.
Una restricción práctica que conviene conocer: Claude Code lee CLAUDE.md hasta un límite de líneas. Si tu fichero es lo bastante largo como para alcanzar ese límite, las instrucciones del final son invisibles. La putrefacción del contexto se aplica también a tus propios ficheros de configuración, no solo al contexto de la aplicación.
Cómo alcanzar L3
Para una base de código sana, L3 son unas pocas semanas de trabajo enfocado. Para un repositorio legacy con tests débiles y sin documentación, son meses — no porque la lista sea larga, sino porque cada elemento se compone con los demás. El camino es corto de describir y honesto de recorrer:
- Un linter y un formateador que corran automáticamente. No configurados-pero-ignorados. Corriendo en CI y bloqueando la fusión si fallan. Esto solo elimina toda una categoría de ruido del output del agente.
- Comprobación de tipos o análisis estático. TypeScript strict, mypy, equivalente. El linter pilla el estilo; los tipos pillan una categoría de bugs que de otro modo el agente entregaría con total seguridad.
- Una suite de tests con cobertura significativa. No un 100%. Significativa. Tests que ejerciten el camino feliz y los casos límite obvios dan al agente una señal que puede leer: ¿rompió el cambio algo real?
- Instalaciones reproducibles. Un lockfile y una versión de runtime fijada. "Funciona en mi máquina" deshace todas las demás garantías.
- Un entorno de desarrollo reproducible. Un
devcontainer.json, unMakefile, undocker-composeque funcione — elige uno. El agente necesita poder ejecutar el código para verificar su output. - Un
READMEque explique cómo arrancar las cosas. Una página. Clonar, instalar, ejecutar. Si un colaborador nuevo no puede ser productivo en una hora, el agente tampoco podrá. - Un
.env.exampleo equivalente. El agente necesita saber qué variables de entorno existen sin ver tus secretos. No tenerlo es uno de los modos de fallo silenciosos más habituales. - Convenciones de commit y PR escritas. Formato de título, política de squash, quién revisa. Los agentes que abren PRs necesitan esto o entregan código con una forma que los humanos rechazan.
- Un
AGENTS.mdque contenga solo información no inferible. Comandos de compilación personalizados, convenciones de nomenclatura propias, restricciones que el agente no puede derivar del código. Si el agente podría averiguarlo leyendo la base de código, no pertenece al fichero. - Una lista de "qué no hacer" dentro de
AGENTS.md. "No llames al helper de auth antiguo." "Esta carpeta se va a eliminar, no la amplíes." "Los tests en/integrationnecesitan Docker corriendo." Las instrucciones en positivo no cubren las trampas; la lista de gotchas suele ser la sección de mayor señal del fichero. - Una señal de CI que el agente pueda leer. Pasa o falla, no "la build pasó pero hay 47 avisos que probablemente deberías revisar".
Los hallazgos de ETH Zúrich y Chroma recorren todos estos elementos: conciso, curado por humanos, rico en señal supera siempre a verboso y exhaustivo.
Recomendaciones de IBERANT
Estas son las cosas que vale la pena hacer antes de preocuparte por los niveles de madurez.
Escribe un AGENTS.md conciso. Una página como máximo. Si no puedes encajar las reglas no obvias en una página, el problema no es el límite de la página. Es que tienes demasiadas reglas no obvias.
Escribe solo lo que el agente no puede inferir del código. Tu convención de nomenclatura está en cada fichero. Tu pipeline de CI está en .github/workflows. Escribe las cosas que no son ya visibles.
Trata los ficheros de contexto como código. Pasan por revisión en pull request. Las líneas muertas se eliminan. Una instrucción obsoleta es activamente dañina — el agente la sigue y produce algo incorrecto que parece correcto.
Haz que los comandos sean obvios. El AGENTS.md debe decirle al agente cómo instalar, testear y hacer lint en tres líneas. No un tutorial. Tres líneas.
Elige L3 como objetivo, no L5. L5 es un objetivo razonable para un equipo de plataforma maduro con tooling dedicado. Para un equipo de tres a diez personas, L3 es donde se obtienen ganancias reales de productividad sin el overhead de la operación autónoma completa.
Relee AGENTS.md cada trimestre. No cada semana. Cada trimestre. Después de un refactor importante, inmediatamente. Las instrucciones obsoletas son peores que las que faltan, porque el agente las sigue con confianza.
Mide en PRs reales, no en existencia de ficheros. ¿Necesita el primer intento del agente menos correcciones este mes que el anterior? Esa es la única métrica que importa.
Conclusión
Un AGENTS.md conciso y actualizado vale más que una puntuación perfecta en cualquier herramienta de madurez. La prueba real detrás de "¿está mi repo listo para la IA?" es más antigua que todas estas herramientas: ¿puede un colaborador nuevo — humano o agente — ser productivo en un día? Si la respuesta es no, el problema no es qué modelo estás usando.
Empieza con una página. Mantenla honesta. Elimina lo que se pudre. El repositorio que más cuesta leer a un ingeniero nuevo es el que confundirá a todos los agentes que le lances.
Si quieres que tu base de código sea genuinamente legible para los agentes de IA — y para los humanos que trabajan junto a ellos — hablemos.