CLAUDE.md

CLAUDE.md es un archivo de texto en formato Markdown que Claude Code carga automáticamente al arrancar y añade al contexto de cada sesión. Funciona como la memoria persistente del agente sobre tu proyecto: todo lo que escribas ahí (convenciones de código, comandos habituales, decisiones de arquitectura, advertencias) viaja con cada petición sin que tengas que repetirlo. Es la forma oficial de darle a Claude Code el contexto que un desarrollador nuevo necesitaría leer antes de tocar el repositorio.

Cómo funciona

Cuando lanzas Claude Code en un directorio, busca archivos CLAUDE.md en varias ubicaciones y los concatena en orden jerárquico:

• CLAUDE.md en la raíz del proyecto: contexto compartido por todo el equipo. Se versiona en git.
• CLAUDE.md en subdirectorios: contexto específico que se carga cuando Claude trabaja con archivos de esa carpeta.
• CLAUDE.local.md o el archivo en ~/.claude/: instrucciones personales que no quieres subir al repositorio.

El contenido se inyecta como parte del prompt de sistema efectivo de la sesión, así que consume parte de la ventana de contexto. Por eso conviene que sea conciso y accionable, no un volcado de documentación. Puedes añadir contenido rápidamente durante una sesión con el atajo #, que escribe tu instrucción directamente en el CLAUDE.md apropiado.

Un ejemplo típico de contenido:

# Proyecto: API de pagos

## Comandos
- Tests: `npm test`
- Lint: `npm run lint` (ejecutar siempre antes de commit)

## Convenciones
- TypeScript estricto, nada de `any`
- Commits en formato Conventional Commits

## Avisos
- NO tocar `src/legacy/`, se migra en otro ticket

Por qué importa

Sin CLAUDE.md, cada sesión empieza en blanco y acabas repitiendo las mismas instrucciones ("usa pnpm, no npm", "los tests van aquí") una y otra vez. Con él, el agente conoce las reglas del proyecto desde el primer mensaje, lo que reduce correcciones, evita que reinvente convenciones y hace que su código encaje con el estilo del equipo. Al estar versionado, además, todo el equipo comparte la misma base de contexto: la calidad de las respuestas deja de depender de quién escribió el prompt.

Es la pieza que convierte a Claude Code de un asistente genérico en un colaborador que entiende tu código. Si quieres dominar este flujo y el resto del entorno, el curso de desarrollo con Claude Code orientado a developers cubre cómo estructurar la memoria del proyecto y automatizar tareas repetitivas.

Buenas prácticas

• Sé específico y breve: instrucciones imperativas y concretas pesan menos y se obedecen mejor que párrafos largos.
• Documenta lo no obvio: comandos del proyecto, scripts internos, dependencias con comportamientos raros.
• Itera: cuando Claude se equivoque de forma recurrente, añade una línea al CLAUDE.md para corregirlo de raíz.
• Separa lo compartido de lo personal: lo del equipo en CLAUDE.md versionado, tus preferencias en el archivo local.

Qué NO es

CLAUDE.md no es un system prompt que reemplaces en cada llamada de API: es específico de Claude Code y se gestiona por archivos. Tampoco es documentación exhaustiva del proyecto; si metes el README entero, malgastas ventana de contexto y diluyes las instrucciones importantes. Y no es un lugar para secretos: nunca pongas claves de API ni credenciales, porque el archivo se versiona y su contenido se envía al modelo. Para datos sensibles usa variables de entorno y archivos ignorados por git.