Escribir un buen CLAUDE.md para tu proyecto

Cada sesión de Claude Code empieza sin recordar la anterior. El archivo CLAUDE.md es cómo le dejas por escrito lo que no quieres volver a explicar: comandos, convenciones, trampas del proyecto. En 10 minutos vas a tener uno bueno, corto y útil, y sabrás qué no meter para que no estorbe.

Antes de empezar

Claude Code instalado y funcionando (si no, empieza por la guía de instalación).
Un proyecto en git: lo que va en CLAUDE.md se comparte con el equipo a través del repositorio.
Diez minutos para pensar qué le corriges a Claude una y otra vez. Eso es exactamente lo que va aquí.

1. Genera un primer borrador con /init

Dentro de tu proyecto, abre Claude Code y escribe /init. Claude analiza el código y crea un CLAUDE.md con los comandos de build y test, la estructura y las convenciones que descubre. Si ya tenías uno, /init propone mejoras en lugar de sobrescribirlo.

Tómalo como punto de partida, no como resultado. /init solo puede apuntar lo que se ve en el código; lo valioso es lo que no se ve: por qué no se toca tal carpeta, qué comando es el bueno, qué error comete Claude siempre.

2. Qué poner y qué no

La regla de la documentación oficial es sencilla: por cada línea, pregúntate si quitarla haría que Claude se equivocara. Si no, fuera.

Frente a frenteEl filtro de cada línea

Sí va en CLAUDE.md

lo que Claude no puede adivinar

Comandos de build, test y lint que no son los obvios
Reglas de estilo que se salen de lo habitual
Decisiones de arquitectura propias del proyecto
Convenciones del repositorio: ramas, commits, PR
Trampas y comportamientos no evidentes
Variables de entorno o requisitos del entorno local

No va en CLAUDE.md

ruido que diluye lo importante

Lo que Claude deduce leyendo el código
Convenciones estándar del lenguaje
Documentación larga de APIs (enlaza, no copies)
Datos que cambian a menudo
Tutoriales y explicaciones extensas
Obviedades como «escribe código limpio»

Objetivo: menos de 200 líneas por archivo. Un CLAUDE.md largo consume contexto y hace que Claude siga peor las reglas.

Tres consejos de redacción que marcan la diferencia:

Concreto y comprobable: «Indentación de 2 espacios» en vez de «formatea bien»; «Ejecuta npm test antes de cada commit» en vez de «prueba tus cambios».
Con estructura: encabezados y viñetas. Claude lo escanea igual que una persona.
Sin contradicciones: si dos reglas chocan, Claude elegirá una al azar. Revisa el archivo de vez en cuando.

Si un procedimiento tiene muchos pasos o solo aplica a una parte del código, no lo metas aquí: conviértelo en una Skill (tienes la guía «Crear tu primera Skill») o en una regla por rutas, que vemos abajo.

3. Dónde vive cada archivo

No hay un único CLAUDE.md. Claude Code carga varios y los concatena, del más general al más concreto:

Ámbito	Ubicación	Para qué
Organización	ruta gestionada por IT (p. ej. `/etc/claude-code/CLAUDE.md` en Linux)	Normas de toda la empresa
Personal	`~/.claude/CLAUDE.md`	Tus preferencias en todos los proyectos
Proyecto	`./CLAUDE.md` o `./.claude/CLAUDE.md`	Lo que comparte el equipo, en git
Local	`./CLAUDE.local.md`	Tus notas de este proyecto; añádelo a `.gitignore`

Además:

Los CLAUDE.md de subcarpetas se cargan solo cuando Claude trabaja con archivos de esa carpeta. Útil en monorepos.
Puedes importar otros archivos con @ruta/al/archivo (por ejemplo @docs/convenciones.md). Se cargan al arrancar, así que no ahorran contexto: solo ordenan.
Para reglas que solo aplican a ciertos archivos, usa .claude/rules/ con un campo paths en la cabecera. Solo entran en contexto cuando Claude toca archivos que encajan.
Si tu repositorio ya usa AGENTS.md y no hay ningún CLAUDE.md, Claude Code lo lee igualmente.

4. Ejemplo: un proyecto ABAP con abapGit

Un caso muy SAP: un repositorio con código ABAP serializado por abapGit. La gran trampa es que Claude no puede compilar ni activar nada ahí; el repositorio es una copia y la verdad está en el sistema. Eso, precisamente, es lo que hay que decirle:

# Z_FACTURACION · ABAP con abapGit

## Contexto
Extensión de facturación para S/4HANA. Este repo es la copia serializada
por abapGit: el código se activa y se prueba en el sistema DEV, no aquí.

## Estructura
- `src/`: un archivo por objeto (`zcl_fact_calculo.clas.abap` + `.clas.xml`)
- Tests ABAP Unit en `*.clas.testclasses.abap`
- `.abapgit.xml`: configuración de abapGit. No lo edites.

## Reglas de código
- ABAP Cloud: solo APIs liberadas. Nada de SELECT a tablas estándar no liberadas.
- Prefijos: clases `ZCL_FACT_`, interfaces `ZIF_FACT_`.
- Sintaxis moderna (inline, VALUE, NEW). Nada de FORM/PERFORM.
- Textos al usuario en clase de mensajes, nunca como literales.

## Al cambiar objetos
- Edita el `.abap`; toca el `.xml` solo si cambian propiedades del objeto.
- No renombres archivos: el nombre lo fija abapGit.
- Objeto nuevo = su `.xml` copiando uno del mismo tipo + su clase de test.

## Verificación
- Aquí no se compila. Al terminar, lista qué objetos activar y qué tests
  ABAP Unit ejecutar en ADT.
- Si no estás seguro de que una tabla, BAPI o API exista, pregunta. No inventes.

Son menos de 30 líneas y cada una evita un error real. Si además trabajas con CAP en el mismo equipo, ese proyecto llevaría su propio CLAUDE.md con sus comandos (cds watch, npm test) y sus carpetas (db/, srv/, app/). Para más contexto sobre este flujo de trabajo, mira la lección Claude + ABAP.

Si algo falla

Claude ignora una regla: lo más habitual es que el archivo sea demasiado largo y la regla se pierda. Recorta. Si una sola instrucción se sigue saltando, marca esa línea con «IMPORTANTE» (solo esa).
No sabes si se ha cargado: ejecuta /context en la sesión y busca tu archivo en la lista Memory files. También puedes abrirlo y editarlo con /memory.
Tu AGENTS.md no se lee: si existe cualquier CLAUDE.md o CLAUDE.local.md en la carpeta o por encima, Claude Code usa esos y no el AGENTS.md. Impórtalo desde el CLAUDE.md con @AGENTS.md.
Las instrucciones parecen perderse tras /compact: lo que está en CLAUDE.md se vuelve a cargar; lo que solo dijiste en el chat, no. Si es importante, pásalo al archivo.

Para recordar

0 de 5 claros

Marca lo que ya tienes claro.