Qué poner, y qué no, en tu AGENTS.md

1El problema

Un fichero de instrucciones del repositorio no se consulta cuando hace falta: se carga entero, en cada petición, en todas las sesiones. La tabla de coste en contexto de la documentación de Claude Code lo pone en una tabla: CLAUDE.md va completo en cada petición, mientras que las skills solo aportan su descripción hasta que se activan, MCP solo los nombres de las herramientas y los hooks cuestan cero salvo que devuelvan salida. V

De ahí sale el problema práctico: cada línea que añades la paga también la sesión que no tiene nada que ver con ella. Y como añadir es fácil y borrar da miedo, el fichero crece. Acaba siendo un documento de arquitectura que nadie relee, con comandos que ya no existen y avisos sobre errores corregidos hace meses. La documentación de Claude Code recomienda mantenerlo por debajo de 200 líneas. V

Conviene además no confundir lo que es. El propio formato establece que el prompt del usuario prevalece sobre el fichero. V Lo que escribas ahí orienta; no obliga.

Anotado el 7 de octubre de 2026. Un hook sigue siendo el sitio donde poner lo que no puede fallar, pero no es inviolable: un mod que instales y que atienda la comprobación de permisos puede aprobar después lo que el hook bloqueó, salvo que el hook esté en la configuración gestionada. V Lo cuenta entero la guía de hooks.

2Qué es

AGENTS.md se define a sí mismo como un formato sencillo y abierto para guiar a los agentes que programan: un Markdown en la raíz del repositorio con lo que un agente necesita saber para trabajar en él. Nació de un esfuerzo conjunto del ecosistema —OpenAI Codex, Amp, Jules de Google, Cursor y Factory—, lo usan más de 60 000 proyectos y hoy lo custodia la Agentic AI Foundation, dentro de la Linux Foundation. V OpenAI lo donó a esa fundación el 9 de diciembre de 2025 como proyecto fundacional; la nota de la Linux Foundation cita su adopción por GitHub Copilot, Cursor y Devin. V

Dos reglas del formato importan al escribirlo: en un monorepo, el fichero más cercano en el árbol tiene precedencia; y el prompt del usuario prevalece sobre todo lo que diga. V

CLAUDE.md es el equivalente de Anthropic y añade jerarquía: nivel de política, de usuario, de proyecto y local, con importaciones @ruta de hasta cuatro saltos y reglas por ruta en .claude/rules/ con un campo paths:, para que una norma solo se cargue en las carpetas donde aplica. V

Corregido el 24 de septiembre de 2026. Hasta la versión 2.1.277 de Claude Code, esta guía decía que no leía AGENTS.md por su cuenta y que había que importarlo. Ya no es así, y así estaba publicado aquí hasta hoy.

Claude Code lee el AGENTS.md del repositorio directamente, sin importarlo, sin enlace simbólico y sin tocar ningún ajuste. Cuál de los dos ficheros acaba leyendo depende de lo que haya en tu proyecto:

• Si hay un AGENTS.md y ningún CLAUDE.md ni CLAUDE.local.md en tu carpeta de trabajo ni por encima de ella, lee el AGENTS.md.
• Si hay los dos, lee solo el CLAUDE.md. El AGENTS.md se queda fuera.
• Si tu CLAUDE.md ya importa el AGENTS.md, sigue funcionando como siempre, y no lo carga dos veces.

Para cambiarlo está el ajuste Project instructions, que se toca con /config: claude-md-and-agents-md carga los dos, claude-md ignora el AGENTS.md, y managed-only deja solo las instrucciones de tu organización. V

Hay una trampa que conviene conocer, porque muerde: un CLAUDE.local.md con tus notas sin subir cuenta a estos efectos, así que añadirlo a un proyecto que se apoya en AGENTS.md hace que Claude deje de leer el AGENTS.md. Si quieres las dos cosas, hay que poner el ajuste en claude-md-and-agents-md. V

Anotado el 7 de octubre de 2026. Hasta la versión 2.1.288, del 2 de octubre, las normas acotadas por ruta de .claude/rules y los CLAUDE.md anidados solo se cargaban al leer un fichero de su ámbito. Si el agente creaba o editaba uno, no se cargaban. V O sea que la norma que habías escrito para una carpeta no estaba puesta justo en el momento en que más falta hacía. Si trabajas con normas por carpeta, actualiza y vuelve a probarlas.

3Qué poner

Cuatro cosas, y en este orden.

• Un índice, no un manual. El equipo de Codex de OpenAI describe un AGENTS.md de unas 100 líneas que funciona como mapa hacia docs/: diseño, arquitectura y planes de ejecución viven allí; el fichero solo dice dónde mirar. S
• Los comandos que se ejecutan de verdad. El comando exacto de tests, de build y de formato, pegado tal cual y probado en la terminal. Es la parte que sí funciona según el estudio de ETH Zúrich: las instrucciones se siguen; lo que no aporta son los resúmenes del repositorio. V
• Las convenciones que el agente no puede deducir del código. A qué carpeta va cada cosa cuando hay dos candidatas, qué rama se usa, qué dependencias están vetadas, qué patrón se abandonó y sigue vivo en la mitad de los ficheros. Si se lee en el código, sobra escribirlo.
• Una línea por fallo real. Es el criterio de Mitchell Hashimoto, creador de Ghostty y de Terraform: cada línea de ese fichero está ahí porque un agente se portó mal antes, y dice que con eso los resolvió casi todos. No es documentación, es una lista de cicatrices. V Nada entra por si acaso: entra porque el agente ya lo hizo mal una vez, y la línea es la que lo habría evitado.

4Qué no poner

• El tour del repositorio. Es justo lo que el estudio de ETH Zúrich midió como inútil: los resúmenes del repositorio no mejoran la tasa de éxito. V El agente sabe leer el código; lo que no sabe es lo que no está escrito en ninguna parte.
• Documentación duplicada. Si ya está en docs/, se apunta hacia allí. Copiada se paga en cada petición y se desactualiza sin que nadie lo note, con el agravante de que entonces el agente lee dos versiones distintas de lo mismo.
• Las normas que no pueden fallar. La documentación de Claude Code no deja margen a la interpretación: escribir «no toques nunca el fichero .env» en las normas del proyecto es una petición, no una garantía; lo que garantiza es el código que bloquea esa edición antes de que ocurra. V Un hook se ejecuta fuera del modelo y bloquea la acción; una línea del fichero es una petición que se cumple casi siempre, y «casi siempre» no es una política de seguridad. Está desarrollado en la guía «Cómo impedir que un agente haga algo: hooks en Claude Code».
• El estilo obvio. Comillas, indentación, punto y coma: si hay un formateador configurado, basta con dar su comando. Lo que el linter ya impone no necesita convencer al modelo.

5Cuánto ahorra o cuesta

Hay dos estudios de 2026 y no dicen lo mismo.

• Gloaguen, Mündler, Müller, Raychev y Vechev (ETH Zúrich / SRI Lab), arXiv 2602.11988, febrero de 2026: dar al agente ficheros de contexto no suele mejorar la tasa de acierto, y en cambio encarece cada consulta más de un 20 % de media. Con un matiz importante: las instrucciones sí se siguen; lo que no aporta son los resúmenes del repositorio. V
• Lulla, Mohsenimofidi, Galster, Zhang, Baltes y Treude, arXiv 2601.20404, enero de 2026: sobre 10 repositorios y 124 pull requests, con AGENTS.md el tiempo de ejecución baja un 28,64 % en mediana y los tokens de salida un 16,58 %, con una tasa de finalización comparable. V

La contradicción es real y no la voy a disolver. Miden cosas distintas —coste total de inferencia frente a tokens de salida y tiempo de ejecución— sobre montajes distintos, y no he comparado sus metodologías, así que aquí no hay un número neto que dar. Lo que sí comparten, y es el dato que cambia una decisión: ninguno de los dos encuentra que el fichero haga acertar más al agente. La tasa de éxito o de finalización se queda igual en ambos; lo que está en discusión es solo el precio.

De ahí la única recomendación que sobrevive a la contradicción: que el fichero sea corto. Por debajo de 200 líneas según la documentación de Claude Code V, en torno a 100 en el AGENTS.md que describe el equipo de Codex S. Con un fichero de ese tamaño, la diferencia entre los dos estudios importa poco; con uno de 800 líneas, importa en cada sesión.

6Cómo mantenerlo

• Se edita después de un fallo, no antes por si acaso. Cuando el agente hace algo mal, la pregunta útil es qué línea lo habría evitado. Si no hay ninguna, el problema no era del fichero.
• Se borra tan a menudo como se escribe. El comando que cambió de nombre, la carpeta que ya no existe, el aviso sobre un error corregido. Una línea caducada es peor que ninguna, porque el agente la cumple.
• Se comprueban los comandos. Pégalos en la terminal de vez en cuando. Un comando roto en el fichero se convierte en un intento fallido en cada sesión.
• Se coloca en el nivel que le toca. Lo que vale para todos tus proyectos va al nivel de usuario; lo que solo afecta a una carpeta, a una regla por ruta con paths: o a un fichero de ese subdirectorio, que tiene precedencia por cercanía. V
• Si una norma se ha saltado dos veces, no es un problema de redacción. Es un hook.

7Pruébalo

8Llévatelo a tu caso

9Fuentes

1. Claude Code — How Claude remembers your project · consultado 24-sep-2026
2. agents.md — AGENTS.md, formato abierto para guiar agentes de código · consultado 18-sep-2026
3. Claude Code Docs — Memory (CLAUDE.md y AGENTS.md) · consultado 18-sep-2026
4. Claude Code Docs — Extend Claude Code (coste en contexto de cada mecanismo) · consultado 18-sep-2026
5. Claude Code Docs — Hooks · consultado 18-sep-2026
6. Gloaguen, Mündler, Müller, Raychev y Vechev (ETH Zúrich / SRI Lab) — Evaluating AGENTS.md · arXiv 2602.11988, feb-2026
7. Lulla, Mohsenimofidi, Galster, Zhang, Baltes y Treude — On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents · arXiv 2601.20404, ene-2026
8. Mitchell Hashimoto — My AI Adoption Journey · 5-feb-2026
9. Leela Kumili (InfoQ) — OpenAI on harness engineering with Codex · 21-feb-2026
10. Linux Foundation — Formación de la Agentic AI Foundation (AGENTS.md como proyecto fundacional) · 9-dic-2025