Cómo escribir un archivo CLAUDE.md en 2026: guía práctica

Un archivo CLAUDE.md es un simple archivo Markdown que Claude Code lee automáticamente al inicio de cada sesión, y que aporta al modelo instrucciones persistentes que no puede deducir de tu código: comandos de compilación, convenciones, arquitectura y esas reglas del tipo «haz siempre X» que estás cansado de repetir. Colócalo en la raíz del proyecto, mantenlo por debajo de unas 200 líneas y llénalo de instrucciones concretas y verificables en lugar de volcar una wiki entera. Esta guía cubre dónde vive el archivo, qué debe contener, cómo importar y reutilizar documentación existente, y cómo generarlo y recortarlo con los propios comandos de Claude Code.

Conviene ser preciso desde el principio, porque la mayoría de los artículos mezclan dos cosas que Claude Code mantiene separadas: el CLAUDE.md que tú escribes y la memoria automática que Claude escribe por su cuenta. Veremos ambas, y por qué el archivo que redactas a mano sigue siendo lo que más partido saca de toda la configuración.

¿Qué es un archivo CLAUDE.md?

Un archivo CLAUDE.md es la capa de instrucciones de Claude Code. Al inicio de la sesión, Claude Code lo carga en la ventana de contexto y lo entrega como un mensaje que Claude lee antes de tocar tu código. La documentación de Anthropic lo describe como el lugar donde «anotar lo que de otro modo tendrías que volver a explicar»: el stack tecnológico, cómo ejecutar las pruebas, las convenciones de nomenclatura y las decisiones de arquitectura que necesitaría un compañero recién llegado. Es Markdown, así que los encabezados y las listas con viñetas son toda la estructura que necesitas.

Un matiz que la documentación deja explícito: CLAUDE.md es contexto, no configuración impuesta. Claude lo lee e intenta seguirlo, pero no hay ninguna garantía firme, sobre todo con reglas vagas o contradictorias. Todo lo que debe ocurrir en un punto fijo —«ejecuta el linter antes de cada commit»— pertenece a un hook, no a una línea de prosa. Esa distinción condiciona todo lo que viene a continuación.

Dónde colocar tu archivo CLAUDE.md

CLAUDE.md puede vivir en varios sitios, y Claude Code los carga en orden, de lo más general a lo más específico, concatenándolos en lugar de sobrescribirlos. Una instrucción de proyecto llega al contexto después de una de usuario, de modo que el archivo más específico se lee en último lugar.

Ámbito	Ubicación	Propósito	Compartido con
Política gestionada	/etc/claude-code/CLAUDE.md (Linux/WSL); /Library/Application Support/ClaudeCode/CLAUDE.md (macOS); C:\Program Files\ClaudeCode\CLAUDE.md (Windows)	Estándares corporativos que despliega el departamento de TI	Todos los usuarios de la máquina
Usuario	~/.claude/CLAUDE.md	Tus preferencias personales en todos los proyectos	Solo tú
Proyecto	./CLAUDE.md o ./.claude/CLAUDE.md	Reglas del proyecto compartidas por el equipo	Tu equipo, vía git
Local	./CLAUDE.local.md	Notas privadas por proyecto (añádelo al gitignore)	Solo tú, en este proyecto

Claude Code lee CLAUDE.md desde tu directorio de trabajo y desde cada directorio situado por encima, de modo que en un monorepo se aplican tanto un archivo raíz como uno a nivel de paquete. Los archivos de los subdirectorios que quedan por debajo se cargan bajo demanda, solo cuando Claude lee archivos allí. Ejecuta /context en una sesión y revisa la lista de Memory files para confirmar qué se ha cargado realmente: es la forma más rápida de depurar el «Claude ignora mi CLAUDE.md», que casi siempre se debe a un archivo que no está en una ubicación que se cargue.

Qué poner en un archivo CLAUDE.md (y qué dejar fuera)

El mejor CLAUDE.md es una lista breve de hechos concretos y comprobables. Incluye los comandos de compilación y de pruebas, la estructura del proyecto, las convenciones que difieren de los valores por defecto de las herramientas y los errores que has tenido que corregir más de una vez. Escribe «Ejecuta npm test antes de hacer commit» y «Los handlers de la API viven en src/api/handlers/», no «prueba tus cambios» ni «mantén los archivos ordenados»: es la concreción lo que Claude puede realmente ejecutar.

Lo que se deja fuera importa igual de mucho. No obligues al modelo a hacer el trabajo de un linter; si tienes ESLint o Prettier, deja que ellos impongan el estilo y mantenlo fuera del archivo. Omite cualquier cosa que Claude pueda leer directamente del código base: los árboles de directorios, las listas de dependencias y los resúmenes de arquitectura son justamente lo que la revisión de /doctor de Claude Code propondrá recortar. Los procedimientos de varios pasos específicos de una tarea pertenecen a un skill de Claude Code que se carga bajo demanda, y todo lo específico de una ruta («todos los endpoints de la API necesitan validación de entrada») pertenece a un archivo .claude/rules/ acotado con un glob paths:, de modo que solo entre en el contexto cuando Claude toque archivos que coincidan. Una buena regla general: si una entrada no resulta útil en cada sesión, no debería estar en CLAUDE.md.

Que sea breve: CLAUDE.md es un presupuesto de tokens, no una wiki

Como CLAUDE.md se carga en cada turno, cada línea cuesta contexto. El objetivo declarado por Anthropic es menos de 200 líneas por archivo; los archivos más largos consumen más contexto y reducen de forma medible hasta qué punto Claude los sigue (un archivo de más de 4 MiB se omite por completo). El equipo de ingeniería de contexto de HumanLayer va más allá y mantiene su propio archivo por debajo de las 60 líneas, y cita el techo práctico de que los modelos de vanguardia solo siguen de forma fiable unas 150-200 instrucciones, y que el propio prompt de sistema de Claude Code ya gasta aproximadamente 50 de ellas antes de que hayas escrito una sola palabra.

El modelo mental que ayuda: trata CLAUDE.md como RAM, y los skills, las reglas y la documentación de referencia como disco. No cargas todo el disco duro al arrancar. Pon en CLAUDE.md las reglas que siempre son ciertas y apunta a todo lo circunstancial con un enlace o una importación. Si el archivo empieza a superar las 200 líneas, esa es la señal para dividirlo, no para seguir haciendo scroll.

Importa otros archivos y reutiliza tu AGENTS.md

CLAUDE.md puede incorporar otros archivos con la sintaxis @ruta/al/archivo. Las importaciones se expanden en el contexto al arrancar, las rutas pueden ser relativas o absolutas, y pueden anidarse hasta cuatro niveles de profundidad. Envuelve una ruta entre comillas invertidas cuando quieras mencionarla sin importarla.

El caso más útil es la interoperabilidad. Claude Code lee CLAUDE.md, no AGENTS.md, así que si tu repositorio ya usa el estándar multiherramienta AGENTS.md, no lo dupliques. Crea un CLAUDE.md que lo importe y añade debajo cualquier nota específica de Claude:

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

Un enlace simbólico (ln -s AGENTS.md CLAUDE.md) también funciona si no necesitas añadidos específicos de Claude. Una advertencia: una importación que se resuelve fuera de tu directorio de trabajo dispara un diálogo de aprobación puntual, una salvaguarda deliberada frente a archivos que otras personas suban a un repositorio compartido.

Genéralo y mantenlo con /init, /memory y /doctor

No tienes que empezar desde un archivo en blanco. Ejecuta /init y Claude analiza el código base y escribe un CLAUDE.md inicial con los comandos de compilación, los pasos de las pruebas y las convenciones que descubre; si ya existe uno, sugiere mejoras en lugar de sobrescribirlo. Incluso lee los archivos de reglas de Cursor y Copilot que ya tengas e incorpora las partes relevantes. Trata el resultado como un borrador: el verdadero valor está en el puñado de instrucciones que Claude no pudo deducir, que añades después.

A partir de ahí, /memory lista y abre todos los archivos de memoria en cada ámbito, y /doctor propone recortes para un CLAUDE.md versionado, eliminando el contenido derivable pero conservando las trampas y su razón de ser. Cuando le dices a Claude «añade esto a CLAUDE.md», edita el archivo directamente. Y como el archivo no es más que Markdown en el control de versiones, los cambios pasan por revisión de código igual que cualquier otra parte del repositorio, que es cómo el CLAUDE.md que impulsa nuestro propio pipeline de publicación aquí en TechRiseUps se mantiene honesto con el tiempo.

CLAUDE.md frente a la memoria automática

Las versiones recientes de Claude Code añadieron un segundo sistema de memoria, automático, y es fácil confundirlo con CLAUDE.md. La separación es clara: tú escribes CLAUDE.md (instrucciones y reglas); Claude escribe la memoria automática (cosas que observa sobre tus preferencias y correcciones). La memoria automática vive en ~/.claude/projects/<project>/memory/, con un índice MEMORY.md cuyas primeras 200 líneas (o 25 KB) se cargan en cada sesión, y con archivos temáticos que se cargan bajo demanda.

Manténlos en su carril. CLAUDE.md son tus requisitos; la memoria automática es lo que Claude ha aprendido sobre cómo trabajas. Claude deja pasar deliberadamente el guardado de cualquier cosa que tu CLAUDE.md ya indique, así que un CLAUDE.md ajustado también deja la memoria automática más limpia. Puedes explorar, editar o eliminar cualquier parte a través de /memory: todo es Markdown en texto plano.

Preguntas frecuentes

¿Qué debo poner en mi archivo CLAUDE.md? Los comandos de compilación y de pruebas, la estructura del proyecto, las convenciones que difieren de los valores por defecto y las correcciones que te descubres repitiendo. Haz que cada entrada sea específica y verificable. Deja fuera el estilo de código (usa un linter), los procedimientos específicos de una tarea (usa skills) y todo lo que Claude pueda leer del código.

¿Cómo escribo el CLAUDE.md perfecto? No existe uno perfecto, pero el patrón fiable es breve y específico: menos de 200 líneas, instrucciones concretas, agrupadas bajo encabezados de Markdown, con el detalle circunstancial trasladado a importaciones, reglas o skills. Empieza con /init, luego recorta con /doctor y refínalo a medida que Claude cometa errores.

¿Puede Claude crear el archivo CLAUDE.md por mí? Sí. Ejecutar /init genera un CLAUDE.md inicial a partir de tu código base, y puedes pedirle a Claude que añada o edite entradas en cualquier momento. Aun así, el archivo final es tuyo: redacta a mano las reglas que no pudo descubrir por sí solo.

¿En qué se diferencia CLAUDE.md de AGENTS.md? AGENTS.md es un estándar abierto multiherramienta; CLAUDE.md es el archivo que Claude Code carga realmente. Claude Code no lee AGENTS.md directamente, así que si mantienes uno, impórtalo en CLAUDE.md con @AGENTS.md o crea un enlace simbólico entre ambos en lugar de mantener archivos duplicados.

¿Por qué Claude ignora mi CLAUDE.md? Normalmente el archivo no está en una ubicación que se cargue: ejecuta /context y revisa Memory files. Si se cargó pero Claude aun así se desvía, haz la instrucción más específica, elimina las contradicciones y, para todo lo que deba ejecutarse siempre, muévelo a un hook en lugar de confiar en la prosa.

Sources

• Documentación de Claude Code — Cómo recuerda Claude tu proyecto: referencia oficial sobre las ubicaciones de CLAUDE.md, el orden de carga, las importaciones, los límites de tamaño, /init, /memory y la memoria automática.
• HumanLayer — Writing a good CLAUDE.md: orientación de ingeniería de contexto sobre la longitud, la divulgación progresiva y el techo de ~150-200 instrucciones.