CLAUDE.md y AGENTS.md: instrucciones permanentes para agentes

CLAUDE.md y AGENTS.md son archivos del repositorio con instrucciones que un agente lee al empezar cada sesión. Qué poner, qué dejar fuera y cómo escribirlos.

info Definición Rápida

CLAUDE.md y AGENTS.md son archivos de Markdown dentro de un repositorio que contienen instrucciones permanentes para agentes de código: cómo construir el proyecto, qué convenciones seguir y qué no tocar. El agente los lee al empezar cada sesión, así que funcionan como un README pensado para máquinas.

¿Qué son y en qué se parecen?

AGENTS.md es un formato abierto, en Markdown plano y sin campos obligatorios, que hoy administra la Agentic AI Foundation, dentro de la Linux Foundation. Según su sitio, funciona como “un README para agentes”: reúne el contexto que ensuciaría un README para personas, como pasos de compilación, pruebas y convenciones. Se puede poner uno por subproyecto, los agentes leen el más cercano al código que se edita y lo que escribas en el chat prevalece sobre todos. Lo leen Codex, Cursor, Gemini CLI y GitHub Copilot, entre otros.

En Codex, el archivo global vive en ~/.codex (AGENTS.md, o AGENTS.override.md si existe). Desde la raíz del proyecto hasta la carpeta de trabajo toma un archivo por carpeta, y los más cercanos van después y prevalecen. Se detiene al acumular 32 KiB, el valor por defecto de project_doc_max_bytes.

CLAUDE.md es el equivalente de Claude Code, y puede estar en varios sitios:

Alcance	Ubicación	Se comparte con
Proyecto	`./CLAUDE.md` o `./.claude/CLAUDE.md`	El equipo, por git
Personal, todos los proyectos	`~/.claude/CLAUDE.md`	Solo tú
Personal, un proyecto	`./CLAUDE.local.md` (añádelo a `.gitignore`)	Solo tú
Organización (Linux)	`/etc/claude-code/CLAUDE.md`	Todo el personal

Con AGENTS.md hay una trampa. Por defecto, Claude Code lo lee solo si no existe ningún CLAUDE.md (ni CLAUDE.local.md) en la carpeta de trabajo ni por encima; si existen ambos, lee solo los CLAUDE.md. Para mantener un único archivo para todas las herramientas, crea un CLAUDE.md que empiece con la línea @AGENTS.md y añade debajo lo específico de Claude. La lectura directa de AGENTS.md requiere Claude Code 2.1.277 o posterior.

Además, Claude Code guarda una memoria automática: notas que el propio agente escribe a partir de tus correcciones, en ~/.claude/projects/<proyecto>/memory/. De su índice MEMORY.md se cargan las primeras 200 líneas o 25 KB. Ese límite es de la memoria automática, no de CLAUDE.md.

¿Por qué le importa a un diseñador?

Porque en un flujo de vibe coding o de diseño con agentes, este archivo es donde se traducen las decisiones de producto en reglas que el agente sigue:

Tokens y tono. Si el sistema de diseño usa ciertos tokens y no otros, dejarlo escrito evita que el agente invente colores.
Componentes existentes. “Usa el componente Button del sistema; no crees botones nuevos” evita duplicados.
Criterios de revisión. Qué significa “listo” para un cambio de interfaz: pruebas de accesibilidad, capturas, contraste.
Límites. Qué archivos o carpetas no se deben modificar sin revisión humana.

Es, en la práctica, una forma de documentar el criterio de diseño de forma que la IA lo use.

¿Qué poner y qué dejar fuera?

Incluye:

Comandos exactos para instalar, construir, probar y levantar el proyecto.
Convenciones que no son obvias para alguien nuevo.
Decisiones de arquitectura con su motivo breve.
Lo que el agente nunca debe hacer.

Deja fuera:

Historia del proyecto y anécdotas.
Listas de tareas pendientes, que cambian cada semana y pertenecen a un gestor de tareas.
Secretos y claves, que nunca deben estar en un archivo versionado.
Instrucciones largas que se contradicen con otras secciones.

Cómo escribirlo para que se cumpla

La documentación de Claude Code aclara que estos archivos son contexto, no configuración obligatoria. Para que el agente los siga:

Sé concreto. “Usa pnpm, no npm” se cumple mejor que “usa el gestor de paquetes adecuado”.
Sé breve. La documentación sugiere menos de 200 líneas por CLAUDE.md. Si crece, separa en reglas por tipo de archivo. El comando /init genera un primer borrador a partir del código.
Pon lo crítico arriba. Lo que nunca debe romperse va al principio.
Si algo debe bloquearse siempre, no confíes en el texto: usa un hook PreToolUse o una regla técnica que impida la acción.
Revísalo cada vez que el agente se equivoque. Un error repetido indica una instrucción que falta o que no se entiende.

Ejemplo

Ejemplo ilustrativo: un equipo de producto mantiene un CLAUDE.md de 400 líneas con historia del proyecto, tareas pendientes y reglas de estilo. El agente ignora la mitad, porque las reglas están enterradas. El equipo lo reduce a 60 líneas: comandos, tres reglas de sistema de diseño, una lista de carpetas protegidas y el criterio de “listo”. Las tareas pasan a Linear y la historia a la documentación del producto. El agente sigue las reglas con más consistencia y el archivo se revisa cuando aparece un error nuevo.

¿Cómo se organiza cuando el proyecto crece?

Un solo archivo funciona mientras el proyecto cabe en la cabeza de quien lo mantiene. Cuando crece, conviene separar. Claude Code permite poner reglas en .claude/rules/*.md, un archivo por tema. Si el archivo declara paths en su encabezado (por ejemplo src/api/**/*.ts), solo se carga cuando Claude trabaja con archivos que coinciden: las convenciones de componentes no ocupan contexto mientras cambias la API. Otra opción es un CLAUDE.md dentro de cada subproyecto: se carga cuando Claude lee, escribe o edita un archivo de esa carpeta.

Ojo: en Claude Code los archivos no se sobrescriben, se concatenan, y el más cercano al directorio de trabajo se lee al final. Si dos reglas se contradicen, Claude puede seguir cualquiera de las dos, así que cada regla debe vivir en un solo lugar. Los @imports ayudan a ordenar un archivo largo, pero no reducen su costo de contexto, porque se cargan junto con él. Esta organización también decide qué se gasta en cada sesión, así que se relaciona con la memoria en agentes y con el context engineering. Lo que es un procedimiento y no un hecho conviene pasarlo a una de las skills.

Qué puedes hacer mañana

Abre el archivo de instrucciones de un proyecto y cuenta cuántas líneas tiene. Después, marca las que son hechos que siempre aplican, las que son procedimientos y las que son historia o tareas pendientes. Saca la historia y las tareas del archivo, convierte uno de los procedimientos en una skill y deja los hechos en el archivo principal. Corre una tarea real con el agente y anota el primer error que cometa: esa línea nueva o corregida es la siguiente mejora.

Errores comunes

Convertir CLAUDE.md en un manual de 1.000 líneas que nadie lee.
Poner claves o credenciales en el archivo.
Dejar instrucciones contradictorias entre CLAUDE.md, AGENTS.md y reglas.
Creer que una instrucción escrita equivale a una prohibición técnica.
Olvidar actualizar el archivo cuando cambian los comandos o el sistema de diseño.

Fuentes

Preguntas frecuentes

¿Qué es un archivo CLAUDE.md?

Es un archivo de Markdown con instrucciones persistentes para Claude Code: convenciones, comandos, reglas y contexto que el agente lee al empezar cada sesión. Puede estar en el proyecto (./CLAUDE.md o ./.claude/CLAUDE.md), en tu carpeta personal (~/.claude/CLAUDE.md) o en una política de organización.

¿Qué es AGENTS.md?

Es un formato abierto, en Markdown plano, que da instrucciones a agentes de código desde el repositorio. Lo leen Codex, Cursor, Gemini CLI y muchas otras herramientas. Claude Code lo lee por defecto solo si no hay un CLAUDE.md; si hay ambos, se importa con @AGENTS.md.

¿Un agente siempre cumple lo que dice el CLAUDE.md?

No necesariamente. Es contexto, no una configuración obligatoria. Instrucciones concretas y cortas se siguen con más consistencia. Si algo debe impedirse siempre, hace falta un hook o un control técnico.

¿Qué debe llevar un buen CLAUDE.md?

Comandos para construir y probar, convenciones del proyecto, decisiones que no son obvias y lo que el agente nunca debe tocar. Lo que cambia cada semana debe quedar fuera.