El CLAUDE.md es el archivo con más apalancamiento de tu repositorio: Claude Code lo lee al inicio de cada sesión, antes de mirar una sola línea de tu código. Bien escrito, le ahorra al agente veinte minutos de redescubrir tus convenciones en cada tarea. Mal escrito, quema tokens, diluye la atención y puede dirigir al modelo en la dirección equivocada.
La mayoría de los CLAUDE.md están mal escritos, y de una forma muy concreta: documentan lo que el agente podría descubrir por su cuenta y omiten lo que jamás podría inferir. Esta guía cubre cómo se carga el archivo, la única regla que decide qué merece una línea, un ejemplo completo que puedes adaptar, qué dejar fuera (con la investigación detrás de cada recorte) y cómo mantenerlo honesto con el tiempo. Si quieres ir directo al resultado, nuestro generador gratuito de CLAUDE.md produce un borrador sólido en unos dos minutos, sin registrarte.
Qué es un CLAUDE.md y cómo lo carga Claude Code
CLAUDE.md es un archivo Markdown plano que Claude Code incorpora automáticamente al contexto cuando arranca una sesión. No hay esquema ni frontmatter: lo que escribas se convierte en instrucciones permanentes para el agente. Lo que lo hace potente es la jerarquía de carga:
- Memoria de proyecto (
./CLAUDE.mden la raíz del repo) es la principal: compartida con tu equipo, versionada en git. Claude Code también recorre el árbol de directorios hacia arriba, así que en un monorepo se cargan tanto el CLAUDE.md raíz como el del paquete, y los CLAUDE.md de subdirectorios se cargan bajo demanda cuando el agente trabaja con archivos ahí. - Memoria de usuario (
~/.claude/CLAUDE.md) aplica a todos los proyectos de tu máquina. Las preferencias personales van aquí (tu estilo de commits, tus reglas de "nunca mates mis procesos"), no en el archivo del repo, donde serían ruido para el resto del equipo. - Los imports permiten dividir un archivo grande: una línea como
@docs/deploy-checklist.mdinserta otro archivo al cargar (hasta cinco niveles de profundidad). Úsalos para contenido que solo algunas sesiones necesitan.
Dos detalles de flujo de trabajo que vale la pena conocer: presionar # en una sesión te deja agregar una memoria al archivo que elijas sin salir de tu tarea, y /init genera un CLAUDE.md inicial escaneando el repo. Trata la salida de /init como un primer borrador para podar sin piedad, no como un archivo terminado; abajo verás por qué.
La regla de oro: escribe solo lo que el agente no puede inferir
Este es el modelo mental que arregla el 90% de los CLAUDE.md malos: el agente puede leer tu código. Puede listar directorios, abrir package.json, buscar con grep y correr tu suite de tests. Todo lo que sea descubrible por esa vía es un desperdicio de tu presupuesto de contexto, porque estás pagando tokens para contarle al modelo algo que habría encontrado igual.
Lo que el agente no puede inferir, por bueno que sea, es todo lo que vive fuera del código:
- Los motivos. Por qué el acceso a la base de datos pasa por la capa de repositorios, no solo el hecho de que pasa. Un modelo que conoce la razón aplica la regla a casos que nunca escribiste.
- Las trampas. La suite de tests que falla solo fuera de UTC. La ruta que se rompe en silencio en el runtime edge. La migración que jamás debes regenerar desde una plantilla. Son cicatrices, y las cicatrices son exactamente lo que le falta a una sesión nueva.
- Convenciones que difieren de los defaults. El agente asume el comportamiento estándar de las herramientas. Si tu proyecto se desvía (solo exports con nombre, un helper de errores propio, un directorio no estándar que no debe recibir archivos nuevos), dilo, y di por qué.
- Comandos con flags no obvias. No
npm install, sino el hecho de que tus tests necesitanTZ=UTC, o quepnpm testcorre en modo watch y CI necesitapnpm vitest run.
Antes de cada línea que escribas, pregúntate: ¿podría Claude descubrir esto leyendo el repo? Si la respuesta es sí, borra la línea. Si es no, consérvala, y adjúntale la razón.
Un ejemplo completo
Este es un CLAUDE.md realista para un proyecto típico de Next.js + TypeScript + Prisma. Fíjate en que casi cada línea es un comando con su detalle, una desviación de los defaults o una trampa con su razón adjunta:
# CLAUDE.md
Guidance for Claude Code in this repository.
## Commands
- `pnpm dev`: dev server on :3000. Use this, not `next dev` directly,
because the script also runs env validation.
- `pnpm test`: Vitest in watch mode. For a one-shot run (CI, hooks)
use `pnpm vitest run`.
- `pnpm db:migrate`: applies Prisma migrations to the local Postgres.
Start it first with `docker compose up -d db`.
- `pnpm lint:fix` before committing; CI blocks on lint errors.
## Architecture notes
- App Router only. `pages/` still exists for two legacy webhook
endpoints; do not add new files there.
- All DB access goes through `src/server/repositories/`. Route
handlers never import Prisma directly, because the repository
functions carry the row-level tenancy filter.
- Feature flags come from `src/lib/flags.ts` and are cached for 30s,
so tests must stub `getFlag`, not the network call.
## Conventions that differ from defaults
- Named exports everywhere; default exports break `pnpm generate:api`.
- Use `invariant()` from `src/lib/invariant.ts` instead of throwing
raw errors: the global handler maps it to a 400 with a safe message.
- Dates are stored in UTC and formatted only in components via
`formatInTz`. Never format dates in server code; that caused the
double-booking bug in #482.
## Pitfalls
- `pnpm test` needs `TZ=UTC` (set in `.env.test`); without it the
booking specs fail only on machines outside UTC.
- The Stripe webhook route must stay on the Node runtime
(`export const runtime = "nodejs"`): the edge runtime cannot
verify webhook signatures.
Son unas 40 líneas, y una sesión que las carga arranca con todo lo que un compañero senior le contaría a alguien nuevo en su primer día, y nada más.
Qué dejar fuera, con la evidencia
Cada recorte de abajo se remonta a un estudio publicado o a una doc oficial; la lista completa está en nuestro artículo sobre las reglas del linter de archivos de contexto.
El boilerplate crudo de /init. El benchmark de AGENTS.md de ETH Zurich (138 tareas, cuatro agentes incluyendo Claude Code) halló que los archivos de contexto autogenerados redujeron el éxito del agente en torno a un 2-3% mientras subían el costo más de un 20%. Reafirman lo que el agente puede descubrir, así que pagas los tokens dos veces: una para cargarlos y otra para que el agente los verifique.
Árboles de directorios. En el mismo benchmark, los agentes ignoraron los volcados de estructura de carpetas mientras pagaban alrededor de un 14-22% más de tokens de razonamiento por ellos. El propio /doctor de Claude Code ahora recorta los layouts de directorios. El agente va a correr ls; déjalo.
Lenguaje impositivo. "IMPORTANT: You MUST ALWAYS…" se escribió para corregir la sub-activación en modelos de 2024. Los modelos actuales se sobre-activan con él: la propia guía de Anthropic ahora indica reescribir "CRITICAL: You MUST use this tool when…" como un simple "Use this tool when…". Un archivo con ocho o más marcadores en MAYÚSCULAS ya no tiene énfasis, porque todo está enfatizado.
Prosa vaga de calidad. "Write clean code", "follow best practices", "be helpful". El estudio de GitHub sobre más de 2.500 archivos de instrucciones para agentes halló que la vaguedad es el modo de fallo número uno: los agentes actúan sobre instrucciones específicas y verificables y se saltan la prosa con evasivas. Si una regla de estilo importa, ánclala a un comando (ruff check --select D), o bórrala.
Todo lo que pase de la línea 200. Las docs de memoria de Anthropic ahora dan un objetivo explícito: mantén el CLAUDE.md por debajo de unas 200 líneas, porque los archivos más largos reducen la adherencia de forma medible. También hay un límite estricto de 40.000 caracteres. Si te pasas del presupuesto, mueve el detalle a archivos importados con @ o borra las partes descubribles; no pelees por adherencia con más mayúsculas.
Mantenerlo vivo
Un CLAUDE.md es configuración viva, no documentación que escribes una vez. Tres hábitos lo mantienen útil:
- Actualízalo en el momento de la fricción. Cuando el agente haga algo mal que una frase habría prevenido, agrega la frase en ese instante (
#lo convierte en una operación de cinco segundos). Así es como la sección de trampas acumula cicatrices reales en lugar de hipótesis. - Revísalo con cada salto de modelo. Las instrucciones se afinan para una generación de modelos. El lenguaje impositivo que ayudaba a Claude 3 perjudica a los modelos actuales; un archivo que nadie relee desde 2024 probablemente esté dirigiendo mal al agente hoy. Pon una pasada al CLAUDE.md en tu checklist de cada actualización mayor de modelo.
- Poda con la misma agresividad con la que agregas. Las reglas se acumulan; los presupuestos de contexto no. Si una convención se volvió el default, o una trampa se arregló, elimina la línea.
Si tu equipo también usa Cursor, Copilot o Codex, no mantengas cuatro archivos divergentes a mano: escribe el modelo una vez y exporta una configuración para cada agente, CLAUDE.md incluido.
Valídalo antes de commitearlo
Casi todas las reglas de este artículo se pueden verificar mecánicamente. Pega tu archivo en el linter de CLAUDE.md gratuito, o córrelo offline:
npx promptarch lint CLAUDE.md
Califica el archivo de 0 a 100 contra ~30 reglas respaldadas por investigación: el presupuesto de 200 líneas, el lenguaje impositivo, el boilerplate generado, los volcados de árboles de directorios, las directivas contradictorias y verificaciones de seguridad (claves filtradas, inyección con Unicode invisible) que a la mayoría de los revisores nunca se les ocurre buscar. Corre totalmente offline y no necesita cuenta.
Empieza con un borrador, no con un archivo en blanco
Dos formas gratuitas de arrancar ahora mismo:
- Genera: el generador gratuito de CLAUDE.md te pregunta por tu stack, tus convenciones y tus restricciones, y produce un borrador estructurado. Sin registro para el primero.
- Valida: ¿ya tienes un CLAUDE.md? Pásalo por el linter y mira lo que un año de cambios de modelos le hizo a tus instrucciones. También gratis.
En cualquiera de los dos casos, los dos minutos que inviertas le ganan a cada sesión en la que el agente tiene que redescubrir tu proyecto desde cero.