CLAUDE.md: qué es y cómo escribirlo para que Claude Code te haga caso

Documentación oficial de Claude Code sobre cómo Claude recuerda tu proyecto con CLAUDE.md — Captura de pantalla: code.claude.com.

Qué es CLAUDE.md

Cada sesión de Claude Code empieza con la memoria en blanco. CLAUDE.md es un archivo de texto normal en el que escribes lo que Claude debe saber siempre: cómo se prueba tu proyecto, qué convenciones sigues, dónde está cada cosa. Claude lo lee al empezar cada sesión, así no tienes que repetirlo. La documentación oficial lo resume así: escribe ahí lo que, si no, tendrías que explicar de nuevo.

DIAGRAMA // DÓNDE VIVE CADA CLAUDE.md

Se cargan de lo general a lo específico: lo del proyecto llega después de lo tuyo personal.

Además existe la memoria automática: notas que Claude escribe él solo a partir de tus correcciones. CLAUDE.md lo escribes tú; la memoria automática la escribe Claude. Las dos se cargan en cada conversación.

Dónde guardarlo

~/.claude/CLAUDE.mdTus preferencias personales para todos los proyectos.

./CLAUDE.mdInstrucciones del proyecto; se comparten con tu equipo por control de versiones (también vale ./.claude/CLAUDE.md).

./CLAUDE.local.mdPreferencias tuyas solo para este proyecto; añádelo a .gitignore.

El archivo de organización (para empresas) lo gestiona el equipo de IT. Para empezar, te bastan los tres de arriba: el personal, el del proyecto y el local.

Lo más rápido

Créalo con /init

Abre Claude Code en la carpeta de tu proyecto y escribe este comando. Claude analiza tu código y genera un CLAUDE.md inicial con los comandos de compilación, de pruebas y las convenciones que descubra. Si ya existe uno, te propone mejoras en vez de sobrescribirlo.

/init

Después retócalo a mano añadiendo lo que Claude no puede adivinar por sí mismo. ¿No tienes Claude Code todavía? Mira cómo instalarlo.

Cómo escribirlo para que Claude le haga caso

Claude trata CLAUDE.md como contexto, no como una orden obligatoria: cuanto más concreto y corto, más lo cumple. Tres reglas de la documentación oficial:

Concreto y comprobable. «Usa 2 espacios de indentación» mejor que «formatea bien el código». «Ejecuta npm test antes de hacer commit» mejor que «prueba tus cambios».
Corto. Apunta a menos de 200 líneas por archivo. Los archivos largos gastan más contexto y se obedecen peor.
Sin contradicciones. Si dos instrucciones chocan, Claude puede elegir una al azar. Revisa de vez en cuando y borra lo viejo.

Un ejemplo mínimo que puedes copiar y adaptar:

# Proyecto
- Instala con `npm install` y prueba con `npm test`.
- Usa 2 espacios de indentación.
- Los manejadores de la API viven en `src/api/handlers/`.
- Antes de hacer commit, ejecuta `npm test`.

Cuándo añadir algo

Claude comete el mismo error por segunda vez.
Escribes en el chat la misma aclaración que la sesión anterior.
Un compañero nuevo necesitaría ese mismo dato para trabajar.

Si algo es un procedimiento de varios pasos o solo importa en una parte del código, la documentación recomienda sacarlo de CLAUDE.md y ponerlo en una skill o en una regla por carpeta.

Comandos útiles

/initGenera un CLAUDE.md inicial.

/memoryRevisa y edita tu memoria.

/doctor prompt-auditClaude revisa tus archivos de instrucciones: contradicciones, referencias a archivos que ya no existen. No cambia nada hasta que se lo pidas (versión 2.1.283 o posterior).

Más en comandos de Claude Code.

Lo honesto

Lo que no hace

CLAUDE.md no obliga: es una guía que Claude suele seguir, no una barrera. Si necesitas bloquear una acción pase lo que pase (por ejemplo, que nunca toque ciertos archivos), la documentación oficial indica usar un hook y no una instrucción escrita. Para eso, mira permisos de un agente de IA.

Preguntas frecuentes

¿Qué es CLAUDE.md?

Un archivo de texto con instrucciones que Claude Code lee al empezar cada sesión: comandos del proyecto, convenciones y reglas que no quieres repetir.

¿Cómo creo un CLAUDE.md?

Abre Claude Code en tu proyecto y escribe /init. Claude analiza el código y genera un archivo inicial que luego puedes retocar.

¿Dónde se guarda CLAUDE.md?

En ./CLAUDE.md o ./.claude/CLAUDE.md para el proyecto, en ~/.claude/CLAUDE.md para tus preferencias en todos los proyectos y en ./CLAUDE.local.md para lo tuyo solo en este proyecto.

¿Qué longitud debe tener?

La documentación oficial recomienda menos de 200 líneas por archivo. Los muy largos consumen más contexto y se siguen peor.

¿Claude siempre obedece CLAUDE.md?

No siempre. Lo trata como contexto, no como una norma obligatoria. Para bloquear una acción con seguridad hay que usar un hook.