Buenas prácticas de CLAUDE.md (y AGENTS.md, GEMINI.md)

El mejor CLAUDE.md es corto (muy por debajo de las 200 líneas), concreto y verificable: los comandos para compilar y probar, las convenciones que el agente no puede adivinar a partir del código y los errores que ya ha cometido una vez. Todo lo demás, como un recorrido por el árbol de carpetas, procedimientos largos o consejos generales del tipo «escribe código limpio», o bien va en otro sitio o no debe ir en ninguno.

Esta guía explica qué son CLAUDE.md, AGENTS.md y GEMINI.md, dónde los busca cada agente, qué escribir y qué dejar fuera, cómo funcionan las importaciones y cómo mantener un único archivo que lean todos los agentes del proyecto.

Qué son estos archivos

Los agentes de programación empiezan cada sesión sin memoria de tu proyecto. Un archivo de instrucciones es la nota que les dejas: un archivo Markdown simple que el CLI lee al arrancar y añade a la ventana de contexto del modelo antes de tu primer mensaje.

AGENTS.md nació de una colaboración entre OpenAI Codex, Amp, Google Jules, Cursor y Factory, y hoy lo gestiona la Agentic AI Foundation, dentro de la Linux Foundation. Es lo más parecido a un estándar compartido. Claude Code mantuvo su propio nombre, pero las versiones recientes (v2.1.277 y posteriores) leen AGENTS.md de forma nativa cuando no hay CLAUDE.md ni CLAUDE.local.md en el directorio de trabajo ni por encima de él.

Dónde viven los archivos

Los tres agentes usan la misma idea: un archivo global para ti, un archivo de proyecto para el equipo y archivos opcionales más abajo en el árbol para una parte del código.

Claude Code

Los archivos del directorio de trabajo y de los directorios superiores se cargan al arrancar y se concatenan, no se sobrescriben. Los archivos anidados en subdirectorios se cargan bajo demanda, la primera vez que Claude toca archivos de esa carpeta. Ejecuta /context para ver qué archivos de memoria están realmente cargados, y /memory para abrir uno y editarlo.

Codex

Codex lee un ~/.codex/AGENTS.md global (o AGENTS.override.md), y luego recorre desde la raíz de git hasta el directorio actual y toma un archivo por carpeta: AGENTS.override.md si existe, y si no AGENTS.md. Los archivos más profundos quedan más tarde en el texto combinado, así que prevalecen cuando dos reglas entran en conflicto. El total está limitado por project_doc_max_bytes, 32 KiB por defecto, y la cadena se construye una vez por sesión. Más sobre el CLI en la página de Codex.

Gemini CLI

Gemini CLI carga ~/.gemini/GEMINI.md, después los archivos de los directorios de tu espacio de trabajo y de sus padres, y recoge más archivos a medida que sus herramientas visitan otras carpetas. Todo se concatena y se envía con cada prompt. /memory show imprime el texto combinado y /memory reload lo vuelve a leer después de editar.

Qué incluir

Escribe para un compañero nuevo y capaz que nunca ha visto el repositorio y no hará preguntas. Cada línea debe ser algo sobre lo que el agente pueda actuar y tú puedas comprobar.

• Comandos. Cómo instalar, compilar, ejecutar un test, ejecutar todos los tests, pasar el linter y comprobar tipos. Es la sección más útil con diferencia; sin ella, el agente adivina.
• Convenciones que el código no muestra. «Usa pnpm, no npm». «Las rutas nuevas de la API pasan por withAuth()». «Las fechas se guardan en UTC».
• Límites. «No edites nunca archivos de generated/». «No toques la carpeta de migraciones sin preguntar».
• Cómo terminar una tarea. «Ejecuta pnpm test y pnpm typecheck antes de decir que has terminado». «Los mensajes de commit siguen Conventional Commits».
• Trampas conocidas. El error que el agente cometió dos veces la semana pasada, expresado como regla.

Una buena regla es concreta. «Usa sangría de 2 espacios» funciona; «formatea bien el código» no. «Ejecuta npm test antes de hacer commit» funciona; «asegúrate de que todo funcione» no.

Un ejemplo compacto

# Project notes

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 5173)
- One test: `pnpm vitest run path/to/file.test.ts`
- Before finishing: `pnpm lint && pnpm typecheck && pnpm test`

## Conventions
- TypeScript strict; no `any` in new code.
- Server code lives in `src/server`, UI in `src/ui`; never import server code from UI.
- Database access only through `src/server/db.ts`.

## Don’t
- Don’t edit `src/generated/` (run `pnpm codegen` instead).
- Don’t add dependencies without saying why in the summary.

## Learned the hard way
- The payments tests need `STRIPE_KEY=test`; they fail silently without it.

Son unas 20 líneas, y cubren casi todo lo que un agente necesita el primer día.

Qué dejar fuera

Mantenlo corto

Cada línea de CLAUDE.md se envía al inicio de cada sesión y permanece en el contexto durante toda la conversación. La propia documentación de Anthropic sugiere quedarse por debajo de las 200 líneas por archivo, y señala que los archivos más largos reducen la fiabilidad con la que Claude los sigue. El patrón es conocido: cuantas más reglas hay, más se diluye cada una.

Algunos hábitos ayudan:

• Añade una regla solo cuando la necesites. El agente cometió el mismo error dos veces, una revisión detectó algo, o sigues escribiendo la misma corrección. Esa es la señal.
• Poda cuando añadas. Si una regla no ha importado en un mes, quítala.
• Prefiere punteros a copiar y pegar. «El proceso de release está en docs/release.md» cuesta una línea; pegar el proceso cuesta cincuenta.
• Usa comentarios HTML para notas para humanos. Claude Code elimina los comentarios <!-- --> de nivel de bloque antes de enviar el archivo.

Si te preocupa el coste en tokens, la guía de uso de tokens de Claude Code explica qué más llena el contexto.

Importaciones y reglas limitadas por ruta

Claude Code permite que un CLAUDE.md incorpore otros archivos con @path:

See @README.md for the overview.
Coding rules: @docs/conventions.md
@~/.claude/my-preferences.md

Las rutas son relativas al archivo que contiene la importación, las importaciones pueden anidarse hasta cuatro saltos, y se ignora @ dentro de spans de código o bloques de código. La primera vez que un proyecto importa archivos de fuera del repositorio, Claude Code te pide que los apruebes.

Un inconveniente: las importaciones organizan el texto, pero no ahorran tokens. Un archivo importado se carga entero al arrancar, igual que el archivo padre. Para reglas que solo importan en una parte del árbol, usa .claude/rules/*.md con un glob paths: en el frontmatter, de modo que se carguen solo cuando Claude trabaja en los archivos que coinciden:

---
paths: ["src/api/**/*.ts"]
---
- Every handler validates input with zod before touching the database.

Gemini CLI admite la misma sintaxis de importación @file.md en GEMINI.md.

Un solo archivo para todos los agentes

Si tu equipo usa más de un CLI, mantener tres archivos con las mismas reglas es la forma de que se desincronicen. La configuración habitual:

1. Pon las reglas compartidas en AGENTS.md. Codex, Cursor, Copilot, opencode y la mayoría de los demás lo leen directamente.

2. Crea un CLAUDE.md que lo importe y añada lo que sea específico de Claude:

   @AGENTS.md
   
   ## Claude Code only
   - Use the project's /review skill before opening a PR.

3. En Gemini CLI, añade AGENTS.md a los nombres de archivo que busca, en .gemini/settings.json:

   { "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }

Un enlace simbólico (ln -s AGENTS.md CLAUDE.md) también funciona en macOS y Linux, pero el enfoque de importación es más claro y no depende de cómo gestione Windows los enlaces. Claude Code también tiene un ajuste «Project instructions» en /config si quieres que lea juntos CLAUDE.md y AGENTS.md.

Escribir la primera versión

No tienes que empezar con la página en blanco. En Claude Code, /init lee el repositorio y redacta un CLAUDE.md. Trata ese borrador como materia prima: conserva los comandos, borra el recorrido por carpetas y recorta todo lo que no le dirías a un compañero nuevo en su primera mañana.

Después deja que el archivo crezca con el trabajo real. Cada vez que corrijas al agente, pregúntate si la corrección valdría también la semana que viene. Si es así, es una regla candidata.

Hacerlo con AgentVera

AgentVera ejecuta Claude Code, Codex, Gemini CLI y otros CLI en paralelo en terminales reales. Cada agente sigue leyendo su propio CLAUDE.md, AGENTS.md o GEMINI.md exactamente como se ha descrito; AgentVera no sustituye esos archivos. Varias funciones trabajan a su lado:

• Sugerencias de reglas a partir de tus correcciones. Cuando devuelves el trabajo de un agente desde la bandeja de revisión con una nota, o Verify encuentra un criterio fallido, un modelo Claude pequeño convierte la corrección en una regla corta. Aparece en Rule suggestions; Add to instructions la añade al CLAUDE.md y al AGENTS.md del proyecto (el que exista), y las reglas que ya están en los archivos se omiten. Si no existe ninguno de los dos, crea AGENTS.md y un CLAUDE.md que lo importa con @AGENTS.md.
• Roles por agente en lugar de un archivo compartido inflado. El campo “Role and instructions” del diálogo del agente se entrega solo a ese agente (Claude lo recibe añadido a su prompt del sistema; Codex, como instrucciones de desarrollador). Los roles específicos de un agente quedan fuera del archivo compartido. Cursor, Gemini CLI y Amp no usan este campo y se apoyan en el AGENTS.md del proyecto o en archivos de reglas.
• Un mapa del código, para saltarte el recorrido por carpetas. El mapa del proyecto se construye en local y se ofrece a los agentes como herramientas MCP (map_related, map_outline, map_usages y otras), y los agentes nuevos reciben un resumen breve de módulos, puntos de entrada y comando de test. Es la parte que la gente suele pegar a mano en CLAUDE.md.
• Memoria del proyecto. AgentVera Brain lee tus documentos rastreados por Git, incluidos CLAUDE.md y AGENTS.md, junto con commits, PRs y conversaciones pasadas, y registra qué decisiones están vigentes u obsoletas. Un paquete de contexto opcional (desactivado por defecto) puede añadirse a las instrucciones de los agentes nuevos.
• Procedimientos como skills. La galería de skills gestiona carpetas SKILL.md para Claude Code y Codex, que es donde encajan los procedimientos largos.
• Reglas que siempre deben cumplirse. CLAUDE.md es un consejo; para las comprobaciones que deben ocurrir siempre, usa los hooks de Claude Code, y pasa las tareas secundarias acotadas a subagentes.

Lista de comprobación

• Menos de 200 líneas; idealmente menos de 100.
• Los comandos de build, test, lint y comprobación de tipos están listados y son correctos.
• Cada regla es lo bastante concreta como para comprobarla.
• Sin recorrido por carpetas, sin secretos, sin consejos genéricos.
• Las reglas específicas de una carpeta están en archivos anidados o en reglas limitadas por ruta.
• Los procedimientos largos están en skills o documentos, enlazados con una línea.
• Los límites estrictos se imponen con hooks o permisos, no con prosa.
• Las reglas compartidas viven en AGENTS.md; CLAUDE.md lo importa.
• Las preferencias personales están en ~/.claude/CLAUDE.md o en CLAUDE.local.md.

Conclusión

Un archivo de instrucciones es la forma más barata de hacer que un agente se comporte como si ya hubiera trabajado en tu proyecto. Mantenlo corto, mantenlo concreto y deja que crezca solo a partir de errores que hayas visto de verdad. Pon las reglas compartidas en AGENTS.md para que todos los CLI lean lo mismo, pasa los procedimientos a skills e impón con hooks, y no con frases, lo que de verdad importa.