CLAUDE.md y AGENTS.md: qué son, qué escribir en ellos y por qué el agente ignora las reglas

Qué son CLAUDE.md y AGENTS.md

Son archivos Markdown normales situados en la raíz del repositorio, que el agente carga automáticamente en su contexto al inicio de cada sesión. Con ellos le comunica lo que no puede deducir del código: cómo preparar el entorno, con qué comandos verificar el trabajo, qué reglas del proyecto no se discuten y dónde está la documentación detallada.

CLAUDE.md es el archivo que lee Claude Code. AGENTS.md es un formato abierto con la misma idea, compatible con muchos agentes de programación. Si en el equipo se usan agentes distintos, conviene mantener el contenido principal en AGENTS.md y referenciarlo desde CLAUDE.md. Claude Code permite importar otro archivo con una línea que empieza por @:

# CLAUDE.md
@AGENTS.md

Así las reglas viven en un solo lugar y no se desincronizan entre dos archivos.

Cómo lee el agente estos archivos

El contenido del archivo de instrucciones entra en la ventana de contexto del modelo junto con el prompt del sistema, y permanece allí durante toda la sesión. De ello se derivan tres consecuencias importantes.

• Cada línea ocupa espacio en el contexto. El archivo se lee completo en cada arranque, aunque la tarea actual necesite solo una décima parte.
• No son reglas ejecutables, sino texto. El modelo las tiene en cuenta junto con el resto del contexto, y nada garantiza un cumplimiento del 100 %. Las prohibiciones estrictas deben respaldarse con mecanismos: comprobaciones, hooks, permisos de acceso.
• Los archivos se pueden anidar. Claude Code carga CLAUDE.md desde la raíz del proyecto y desde la carpeta de usuario ~/.claude/, y los archivos de los subdirectorios se cargan cuando el agente trabaja con archivos de esas carpetas. Así puede mantener las reglas de un módulo junto al propio módulo.

Qué escribir en CLAUDE.md y AGENTS.md

Un buen archivo de instrucciones es un mapa, no un manual. Responde a las preguntas que un agente haría a un compañero experimentado el primer día.

1. Cómo compilar y comprobar el proyecto

Es la sección más valiosa. Comandos concretos que el agente debe ejecutar antes de decir «listo»: pruebas, linter, comprobación de tipos, arranque del entorno. Sin ellos, el agente verifica su trabajo «a ojo».

2. Restricciones estrictas

Una lista corta de lo que nunca debe romperse: invariantes de seguridad y de datos. Formúlelas como invariantes, no como instrucciones de implementación: «todas las consultas SQL están parametrizadas», y no «usa esta función en este archivo».

3. Un mapa del proyecto

Dónde está cada cosa: unas líneas sobre la estructura de carpetas y dónde buscar los detalles. Para cada tema grande, un enlace a un documento aparte que el agente abre solo cuando trabaja en ese tema.

4. Dónde se guarda el estado del trabajo

Dónde mirar para continuar donde se quedó la sesión anterior: archivo de plan, registro de progreso, backlog. Esto cura la «amnesia» del agente entre sesiones.

Qué no escribir

• Lo que el agente aprende del código. La lista de dependencias está en package.json o pyproject.toml; la estructura de clases, en el propio código.
• Consejos generales. «Escribe código limpio» o «sé atento» no cambian el comportamiento y solo ocupan sitio.
• La historia del proyecto y notas puntuales. «En marzo migramos desde MySQL 5.7» no ayuda a la tarea actual.
• Instrucciones detalladas para tareas poco frecuentes. Un procedimiento de despliegue o de migración de datos se necesita una vez por semana: llévelo a un documento aparte o a un skill.
• Secretos. El archivo está en el repositorio y pasa entero al modelo. Tokens y contraseñas solo deben estar en variables de entorno.

Por qué el agente ignora una regla escrita en el archivo

Una historia típica: el agente cometió un error y se añadió una regla al archivo. Cometió otro, y se añadió otra regla. Meses después, el archivo tiene cientos de líneas y la regla de seguridad crítica se incumple como si no existiera. Suele haber cuatro causas, que actúan a la vez.

Un archivo inflado

Un archivo de 600 líneas equivale a unos 10 000–20 000 tokens. La ventana de contexto parece enorme, pero se reparte entre el código, las salidas de los comandos y el historial de la conversación. Cuanto más espacio ocupan las instrucciones, menos atención recibe cada regla y más espacio se quita a la propia tarea.

La regla está en medio

Los modelos de lenguaje aprovechan bastante peor la información del medio de un texto largo que la del principio o el final. Una regla en la línea trescientos de seiscientas cae en el punto más débil.

Sin prioridades

Una prohibición innegociable y una observación pasajera sobre el estilo están escritas de la misma forma: una línea en una lista. El agente no tiene manera de saber qué pesa más. Y si el archivo contiene tres reglas de estilo contradictorias, el comportamiento se vuelve aleatorio de una ejecución a otra.

Deterioro

Añadir una regla no cuesta nada, pero borrarla da miedo: «¿y si algo depende de ella?». Así el archivo crece sin parar mientras baja la proporción de líneas útiles. Conviene medirlo como una relación señal/ruido: cuántas líneas necesita realmente una tarea típica y cuántas no.

Cómo arreglarlo: un enrutador en lugar de un muro de texto

Corregir una sola causa no sirve de mucho: si acorta el archivo pero lo deja sin estructura, las reglas seguirán mezcladas. Funciona un conjunto de medidas.

1. Convierta el archivo de entrada en un enrutador. 50–150 líneas: comandos de verificación, restricciones estrictas, mapa del proyecto y enlaces a los documentos temáticos.
2. Saque los temas a archivos separados. Por ejemplo, docs/agents/deploy.md o docs/agents/database.md. El agente los abre cuando hace falta. En Claude Code, los skills son útiles para los procedimientos repetitivos, porque solo se cargan cuando se necesitan.
3. Suba lo crítico arriba. Las restricciones estrictas van al principio del archivo, en un bloque corto con la marca MUST.
4. Elimine las contradicciones. Una regla por tema. Si hay una excepción, escríbala junto a la regla.
5. Respalde la regla con un mecanismo. Si la infracción es inaceptable, el texto no basta. Hace falta una comprobación que la detecte: linter, prueba, hook de pre-commit o hook del agente, o una restricción a nivel de permisos.
6. Revise con regularidad. Fije un límite de líneas y, en cada adición, pregúntese qué se puede quitar o sacar fuera.

¿Regla o comprobación?

Ejemplo de AGENTS.md compacto

# AGENTS.md — backend de pagos (FastAPI, PostgreSQL)

## MUST — no incumplir
- Los importes son int en céntimos, nunca float
- SQL solo parametrizado, sin f-strings
- No modificar migraciones aplicadas, solo añadir nuevas
- Secretos solo desde variables de entorno

## Comprobación antes de escribir «listo»
docker compose up -d     # entorno
make lint                # ruff + mypy
make test                # pytest
make e2e                 # escenario de compra
Las pruebas unitarias en verde sin E2E no equivalen a «listo».

## Mapa
- app/payments/   — cálculo de importes, descuentos, webhooks del proveedor
- app/api/        — manejadores HTTP
- tests/e2e/      — escenarios de usuario
Detalles: docs/agents/architecture.md, docs/agents/database.md

## Estado del trabajo
- PLAN.md      — objetivo actual, criterios de aceptación, siguiente paso
- PROGRESS.md  — qué se hizo y cómo se comprobó, callejones sin salida
- BACKLOG.md   — lo que se ve «de paso»: anotarlo aquí, no arreglarlo ahora

Al final de la sesión, actualice PROGRESS.md y el siguiente paso en PLAN.md.

Fíjese en lo que falta: no hay lista de bibliotecas, ni consejos de estilo, ni historia del proyecto. Todo eso o se ve en el código, o lo garantizan las comprobaciones, o está en documentos temáticos.

La amnesia entre sesiones: un archivo de instrucciones y un archivo de plan

El archivo de instrucciones describe cómo trabajar en el proyecto, pero no lo que está ocurriendo ahora. Para eso hace falta un archivo de estado aparte, que el agente lee al principio y actualiza al final de la sesión. Contiene el objetivo, lo hecho con la indicación de cómo se comprobó, las decisiones tomadas con sus motivos, las opciones descartadas y una formulación del siguiente paso. Una prueba sencilla de calidad: abra una sesión nueva, escriba «continúa» y vea si el agente empieza a trabajar de forma útil sin hacer preguntas.

No confunda los dos archivos. Las instrucciones cambian poco y afectan a todas las tareas. El plan cambia en cada sesión y afecta a la tarea actual. Si los mezcla, el archivo de instrucciones se llena pronto de notas obsoletas.

Cómo comprobar que el archivo funciona

El archivo de instrucciones también necesita pruebas. Tome unas cuantas tareas típicas —una corrección de error, una funcionalidad pequeña, una refactorización— y observe qué hace el agente sin indicaciones: si ejecuta los comandos correctos, si abre el documento temático adecuado, si respeta las restricciones estrictas. Si se incumple una regla, pregúntese primero si es visible, si contradice a otra y si se puede sustituir por una comprobación automática. Añadir una línea nueva es el último recurso.

Resumen

CLAUDE.md y AGENTS.md son la puerta de entrada del agente al proyecto. Funcionan cuando siguen siendo un mapa corto: comandos de verificación, restricciones estrictas arriba, enlaces a los detalles y al archivo de plan. Si una regla se ignora, la causa casi siempre es un archivo inflado y sin estructura, y las reglas realmente críticas deben respaldarse con comprobaciones y hooks. El diseño de las instrucciones y del estado del agente se trabaja en la práctica en el curso de harness engineering.