---
title: "¿Qué debe ir en AGENTS.md y CLAUDE.md?"
seoTitle: "AGENTS.md y CLAUDE.md: lo que de verdad ayuda a los agentes"
navTitle: "AGENTS.md y CLAUDE.md"
description: "Qué poner en AGENTS.md y CLAUDE.md según los benchmarks de agentes: comandos útiles, restricciones operativas, trampas costosas y qué conviene omitir."
slug: agents-md-claude-md-best-practices
lang: es
date: 2026-08-06
updated: 2026-08-06
author: "Chatcode"
category: guide
faq:
  - q: "¿AGENTS.md y CLAUDE.md hacen más precisos a los agentes de programación?"
    a: "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."
  - q: "¿Puede Claude Code usar un archivo AGENTS.md existente?"
    a: "Por defecto, Claude Code no carga AGENTS.md directamente. Pon `@AGENTS.md` en un CLAUDE.md pequeño para importar las instrucciones compartidas y añade debajo solo las indicaciones que sean realmente específicas de Claude."
  - q: "¿Qué longitud debe tener un archivo AGENTS.md o CLAUDE.md?"
    a: "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."
---

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:

1. Se aplica a la mayor parte del trabajo en ese ámbito.
2. El agente no puede descubrirlo de forma rápida y fiable a partir del
   repositorio.
3. Seguirlo cambia una acción o una comprobación observable.

Algunos buenos ejemplos:

- `pnpm test --filter api` es 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 mediante `pnpm 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](https://learn.chatgpt.com/docs/agent-configuration/agents-md).

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](https://code.claude.com/docs/en/memory).

Si un equipo usa ambos agentes, mantén las instrucciones compartidas en
`AGENTS.md` e impórtalas desde un `CLAUDE.md` pequeño:

```md
@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?](https://arxiv.org/abs/2607.27250)
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.md` completo 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](https://arxiv.org/abs/2601.20404)
  estudió 10 repositorios y 124 pull requests. La presencia de `AGENTS.md` se
  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](https://arxiv.org/abs/2602.11988) 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:

```md
## 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:

```md
## 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

```md
# 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](/articles/skills-sh-install-skills-ai-coding-agents).
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.
