¿Qué debe ir en AGENTS.md y CLAUDE.md?
Qué poner en AGENTS.md y CLAUDE.md según los benchmarks de agentes: comandos útiles, restricciones operativas, trampas costosas y qué conviene omitir.
Un archivo de instrucciones del repositorio puede acabar fácilmente siendo un README comprimido, un ensayo de arquitectura y una lista de admirables principios de ingeniería. El agente recibe entonces todo ese material en cada tarea, aunque la mayor parte no venga al caso.
Los resultados recientes de benchmarks apuntan a una función más acotada para
estos archivos. Usa AGENTS.md y CLAUDE.md como manuales de operación
breves: comandos exactos, operaciones costosas, pasos de verificación, límites
y hechos difíciles de deducir del código. No esperes que una descripción más
larga del proyecto aporte el criterio de ingeniería que el modelo no tenga ya.
Respuesta rápida
Pon un hecho en el archivo de instrucciones raíz cuando se cumplan estas tres condiciones:
- Se aplica a la mayor parte del trabajo en ese ámbito.
- El agente no puede descubrirlo de forma rápida y fiable a partir del repositorio.
- Seguirlo cambia una acción o una comprobación observable.
Algunos buenos ejemplos:
pnpm test --filter apies el comando de tests rápido para los cambios en la API.- La suite de integración completa tarda 25 minutos y debe ejecutarse una vez, después de que pasen los tests específicos.
- Los archivos de
generated/deben modificarse mediantepnpm generate. - Añadir una dependencia de producción o cambiar una migración de base de datos requiere confirmación.
- Un cambio no está terminado hasta que pasan la comprobación de tipos y el test específico correspondiente.
Deja fuera afirmaciones genéricas como «escribe código limpio», listas de paquetes copiadas y descripciones que el agente puede obtener leyendo el manifiesto y el árbol de código fuente. Usa el prompt de la tarea para los requisitos puntuales, una skill para un procedimiento bajo demanda, y tests, hooks o CI para las reglas que deben imponerse de forma mecánica.
AGENTS.md y CLAUDE.md se parecen, pero no son idénticos
Ambos archivos aportan instrucciones persistentes para el repositorio, pero sus reglas de descubrimiento y de ámbito dependen del agente que los lee.
AGENTS.md de Codex |
CLAUDE.md de Claude Code |
|
|---|---|---|
| Archivo raíz del proyecto | AGENTS.md |
CLAUDE.md o .claude/CLAUDE.md |
| Valores personales por defecto | ~/.codex/AGENTS.md |
~/.claude/CLAUDE.md |
| Indicaciones más específicas | AGENTS.md anidados o AGENTS.override.md |
CLAUDE.md anidados o reglas por ruta en .claude/rules/ |
| Cómo se combinan los archivos | Cadena desde la raíz hasta el directorio de trabajo; los archivos más cercanos se aplican después | Los archivos de los directorios superiores se cargan al arrancar; los anidados, cuando Claude trabaja en ese subárbol |
| Tamaño recomendado actualmente | Límite combinado de descubrimiento de 32 KiB por defecto | Anthropic recomienda menos de 200 líneas por archivo |
Codex construye su cadena de instrucciones una vez por ejecución o por sesión de TUI iniciada. Revisa las indicaciones globales y después recorre el camino desde la raíz del proyecto hasta el directorio de trabajo actual. Un archivo más cercano aparece más tarde en el prompt combinado y, por tanto, prevalece sobre las indicaciones más generales. El orden exacto de descubrimiento y las reglas de prevalencia están en la documentación de AGENTS.md de Codex.
Claude Code trata CLAUDE.md como contexto, no como una configuración de
obligado cumplimiento. Su documentación recomienda instrucciones específicas y
concisas, y explica que los archivos grandes o contradictorios hacen que Claude
siga peor las instrucciones. Consulta
cómo recuerda Claude tu proyecto.
Si un equipo usa ambos agentes, mantén las instrucciones compartidas en
AGENTS.md e impórtalas desde un CLAUDE.md pequeño:
@AGENTS.md
## Claude Code only
- Use the path-scoped rule in `.claude/rules/frontend.md` for UI changes.
Anthropic documenta este patrón de importación de forma explícita. Un enlace simbólico también puede funcionar, pero la importación deja sitio para algunas indicaciones específicas de Claude y es más portable en Windows.
Qué evaluó el último estudio con dos agentes
El preprint de julio de 2026 Do Context Files Help Coding Agents? convirtió pull requests fusionadas de tres repositorios de Python (PDM, firebase-admin-python y opshin) en 17 tareas de programación. La descripción de la PR servía de prompt, mientras que los tests introducidos por la PR real permanecían ocultos y juzgaban la implementación del agente.
Claude Code y Codex trabajaron cada uno en tres condiciones:
- sin contexto: ningún archivo de contexto del repositorio;
- siempre activo: el
AGENTS.mdcompleto se insertaba en cada turno; - selectivo: el agente recibía una pista y podía leer, cuando lo necesitaba, archivos de una wiki organizada por temas.
Tras tres repeticiones, 288 ejecuciones tenían resultados de corrección válidos:
| Estrategia | Claude Code | Codex |
|---|---|---|
| Sin contexto | 53,3 % | 58,8 % |
| Siempre activo | 55,6 % | 56,9 % |
| Selectivo | 55,6 % | 52,9 % |
Las diferencias no fueron estadísticamente significativas. En la revisión
manual de los autores, los intentos que se quedaron cerca fallaron por el
diseño de la funcionalidad, la elección del patrón o un cableado incorrecto, no
por la falta de un hecho del repositorio que sí recogiera el AGENTS.md real.
Añadir o reorganizar ese contexto no convirtió esos fallos en aciertos.
Ese resultado no demuestra que los archivos de instrucciones nunca mejoren la corrección. La muestra contiene solo tres repositorios de Python y entre 15 y 17 tareas por agente. El análisis de potencia del artículo estima que detectar un efecto de 10 puntos porcentuales requeriría entre 120 y 200 tareas, aproximadamente. Además, se probó una inyección más fuerte y artificial en lugar de limitarse a dejar un archivo en su ubicación natural dentro del espacio de trabajo: Claude recibía el contenido añadido al final de su prompt de sistema, mientras que a Codex se le anteponía el texto al prompt del usuario.
La condición selectiva tiene otra limitación. Su wiki solo coincidía con el
AGENTS.md original en opshin; los otros dos repositorios recibieron wikis
generadas más amplias, unas 10 y 18 veces más largas. Por tanto, la
recuperación selectiva no es una comparación limpia del mismo contenido
entregado de otra forma.
El resultado útil fue operativo
El AGENTS.md de opshin indica que la suite completa de tests tarda más de 20
minutos. Sin esa advertencia, Claude ejecutó la suite entera una media de 3,67
veces por celda. Con el contexto siempre activo la ejecutó 2,44 veces; con el
contexto selectivo, 1,67. El tiempo medio de ejecución bajó de 2689 segundos a
2066 y 2032 segundos (una reducción de alrededor del 24 %) sin una mejora
equivalente en la corrección.
Es una buena prueba a favor de un tipo concreto de instrucción: decirle al agente lo que cuesta una acción y darle una vía correcta más barata. No es una prueba general de que la ejecución vaya más rápida. El análisis fue exploratorio, se limitó a Claude en un solo repositorio y, con cinco tareas, tenía una potencia estadística insuficiente. La duración de Codex no varió, y otro repositorio se movió ligeramente en la dirección contraria.
La conclusión prudente es:
Un archivo de instrucciones del repositorio puede mejorar cómo trabaja un agente aunque no mejore lo que el agente es capaz de resolver.
Las pruebas más amplias son dispares
Dos estudios anteriores de 2026 llegaron a resultados distintos en cuanto a eficiencia:
- On the Impact of AGENTS.md Files
estudió 10 repositorios y 124 pull requests. La presencia de
AGENTS.mdse asoció con una mediana del tiempo de ejecución un 28,64 % menor y un 16,58 % menos de tokens de salida, con un comportamiento de finalización comparable. - Evaluating AGENTS.md probó archivos generados y escritos por desarrolladores con distintos agentes y modelos. No encontró una mejora general en el éxito de las tareas y sí un coste de inferencia más de un 20 % superior de media, aunque los agentes sí seguían las instrucciones no estándar.
El nuevo artículo con dos agentes sugiere que la diferente mecánica de inyección y la dificultad de las tareas propia de cada agente podrían explicar la contradicción. Es una hipótesis, no una conciliación definitiva. Teniendo en cuenta los tres artículos, la práctica más defendible es medir un archivo por el comportamiento que cambia en lugar de dar por hecho que más contexto es mejor.
Qué debe contener un archivo de contexto útil
Comandos exactos y la vía rápida
Da comandos listos para ejecutar, con el directorio de trabajo correcto y las opciones útiles. Distingue la comprobación específica de la suite final, que es costosa:
## Verification
- API change: run `pnpm test --filter api` first.
- Type check: run `pnpm typecheck` after changing TypeScript.
- Full suite: `pnpm test`; takes about 18 minutes, so run it once after focused tests pass.
«Ejecuta los tests» aporta poco. Indicar el comando correcto, su coste y el orden elimina las conjeturas.
Límites con un motivo o una alternativa segura
Deja constancia de las zonas no evidentes que el agente no debe modificar directamente:
## Boundaries
- Do not edit `src/generated/`; change the schema and run `pnpm generate`.
- Ask before adding a production dependency.
- Do not rewrite an existing migration; add a new migration instead.
Una vía segura es más útil que una simple prohibición.
Invariantes específicas del repositorio
Incluye las convenciones que sean importantes, sorprendentes y que no se impongan de forma mecánica. Por ejemplo, una regla inusual de mapeo de errores, un requisito de compatibilidad que los tests no cubren o el único servicio que debe usar un comando distinto.
Pon los hechos específicos de un servicio en un archivo de instrucciones anidado o en una regla por ruta. Cargar detalles del frontend en cada tarea del backend gasta contexto y aumenta la probabilidad de conflictos.
Errores recurrentes, no hipotéticos
Añade una regla cuando un agente repita el mismo error costoso o cuando una revisión detecte un hecho que no podía deducir razonablemente. Elimina la regla cuando el repositorio o las herramientas la dejen obsoleta. Así el archivo se basa en fallos observados en lugar de acumular consejos especulativos.
Qué dejar fuera
- Roles genéricos: estos estudios no evaluaron directamente «Eres un ingeniero sénior», pero esa frase no aporta una acción verificable ni un hecho del repositorio.
- Ideales vagos: «Sigue SOLID» o «escribe código limpio» dejan que el agente deduzca la misma decisión de diseño que ya iba a tomar.
- Un segundo README: describe solo la estructura que resulte sorprendente o que influya en dónde debe ir un cambio.
- Inventarios completos de dependencias: el manifiesto está más actualizado y al agente le resulta más fácil consultarlo.
- Requisitos puntuales de una tarea: déjalos en el prompt de la tarea para que no influyan en sesiones que no tienen nada que ver.
- Reglas que las herramientas pueden imponer: los formateadores, las comprobaciones de tipos, los tests, los hooks y la CI son más sólidos que la prosa para los requisitos deterministas.
- Secretos o credenciales personales: un archivo de instrucciones es contexto normal del proyecto, no un almacén de secretos.
Una plantilla inicial compacta
# Repository instructions
## Fast path
- Install: `pnpm install --frozen-lockfile`
- Focused tests: `pnpm test --filter <changed-package>`
- Full suite: `pnpm test` (about 20 minutes; run after focused tests pass)
## Verification
- Run `pnpm typecheck` after TypeScript changes.
- Add or update a focused test when behavior changes.
## Boundaries
- Do not edit `generated/`; run `pnpm generate` from the schema.
- Ask before adding production dependencies or changing migrations.
## Known traps
- Tests under `integration/` require the local database started with `pnpm db:up`.
- Package-specific instructions live in that package's nested `AGENTS.md`.
Sustituye cada ejemplo por un hecho del repositorio real. Un archivo preciso de diez líneas es mejor que una plantilla exhaustiva llena de valores genéricos.
Elige el mecanismo duradero más pequeño
| Información | Mejor ubicación |
|---|---|
| Se aplica a la mayoría de las tareas del repositorio | AGENTS.md o CLAUDE.md raíz |
| Se aplica solo a un subárbol | Archivo de instrucciones anidado o regla por ruta |
| Preferencia personal para todos los repositorios | Archivo de instrucciones a nivel de usuario |
| Procedimiento de varios pasos necesario para ciertas tareas | Una skill bajo demanda |
| Requisito solo para esta tarea | El prompt de la tarea |
| Regla que debe ejecutarse siempre | Test, formateador, hook, política o CI |
Para instalar y mantener procedimientos bajo demanda en varios agentes, consulta la guía práctica de skills.sh. Un archivo de instrucciones no debería sustituir a todas las demás superficies de control.
Evalúa el archivo en tu propio repositorio
Los promedios de la investigación no pueden decirte si una instrucción ayuda en tu código. Elige una tarea repetible en la que la instrucción debería cambiar el comportamiento y haz varias pruebas con y sin ella usando el mismo agente y la misma versión del modelo. Registra:
- los resultados de tests ocultos o escritos de forma independiente;
- las ejecuciones de tests específicos y de la suite completa;
- el tiempo transcurrido y el uso de tokens;
- los cambios de archivos innecesarios y las solicitudes de permiso;
- si el agente siguió la regla concreta.
Conserva una instrucción cuando mejore un resultado o evite un desperdicio medible. Reescríbela o elimínala cuando se ignore, esté duplicada, se haya quedado obsoleta o simplemente alargue el prompt. El objetivo no es el archivo de contexto perfecto, sino un pequeño conjunto de hechos del repositorio que cambie el trabajo para mejor de forma fiable.
Preguntas frecuentes
¿AGENTS.md y CLAUDE.md hacen más precisos a los agentes de programación?
No de forma fiable, según la investigación actual. Los estudios recientes encuentran efectos dispares en la eficiencia y poca o ninguna mejora general en la corrección de las tareas. Aun así, unas instrucciones operativas concretas pueden reducir los comandos, el tiempo y los tokens desperdiciados.
¿Puede Claude Code usar un archivo AGENTS.md existente?
¿Qué longitud debe tener un archivo AGENTS.md o CLAUDE.md?
Mantén el archivo raíz tan corto como lo permita el repositorio. Anthropic recomienda actualmente menos de 200 líneas por CLAUDE.md. Codex tiene un límite por defecto de 32 KiB para toda su cadena de instrucciones combinada, pero es un techo, no un objetivo de redacción.