Cómo escribir un archivo CLAUDE.md que guíe de verdad a Claude Code

Un archivo CLAUDE.md reúne las instrucciones que Claude Code lee al empezar cada sesión. Si lo escribes bien, Claude deja de adivinar el comando de build, las convenciones y la estructura del proyecto. Si lo inflas, Claude ignora en silencio justo las reglas que escribiste para controlarlo. Al final de esta guía tienes un CLAUDE.md ligero que Claude sigue a la primera, y un método para hacerlo crecer sin convertirlo en documentación que nadie lee.

Qué es CLAUDE.md de verdad, y qué no es

CLAUDE.md es un archivo Markdown que entra en la ventana de contexto de forma automática cuando arranca Claude Code. No es documentación ni es una wiki. Es un archivo de inyección de contexto: cada línea compite con la tarea que el modelo tiene delante por una parte de su atención.

Claude Code sube desde tu carpeta de trabajo hasta la raíz del repositorio y carga cada CLAUDE.md que encuentra, así que los archivos se suman por alcance. La documentación oficial de memoria fija el orden de precedencia: primero la política de empresa, luego la memoria de proyecto (./CLAUDE.md), luego la memoria de usuario (~/.claude/CLAUDE.md) y por último las excepciones locales (./CLAUDE.local.md). Los archivos en subcarpetas por debajo de tu carpeta de trabajo no se cargan al arrancar: entran en el contexto solo cuando Claude lee un archivo de esa subcarpeta durante la sesión.

Esto importa porque el contexto es finito. A medida que crecen las instrucciones, la calidad con la que Claude las sigue baja en todo el frente, no solo en las reglas nuevas. Un archivo que quiere decirlo todo acaba sin hacer cumplir nada.

Qué necesitas antes de empezar

• Claude Code instalado y un proyecto abierto en la terminal.
• Una lista corta de los comandos que más usas: build, test, lint, comprobación de tipos.
• Las tres o cuatro convenciones que un desarrollador nuevo se saltaría el primer día.
• Diez minutos. Un buen CLAUDE.md es corto a propósito.

Paso 1: genera una base con /init

No escribas el archivo desde cero. Ejecuta /init en la raíz del proyecto. Claude explora el código con un subagente, rellena los huecos con algunas preguntas y propone un CLAUDE.md que revisas antes de que escriba nada. Trata el resultado como un primer borrador. Incluye de más a propósito, y tu trabajo en el paso siguiente es recortar.

Paso 2: quita todo lo que Claude puede deducir

Lee cada línea generada y aplica una sola prueba: si la borro, ¿Claude se equivoca? Si la respuesta es no, bórrala. Claude lee por su cuenta tu package.json, los nombres de las carpetas y los imports. No necesita un párrafo que explique que usas React o que los componentes viven en src/components. Deja solo los hechos que cambian decisiones y no se deducen del código: el paso de build poco obvio, la convención que contradice el valor por defecto del framework, la carpeta que parece segura de editar pero está generada.

La longitud es el indicador indirecto. El CLAUDE.md raíz de HumanLayer, un equipo que trabaja mucho con Claude Code, se queda por debajo de sesenta líneas. Una regla práctica extendida mantiene un archivo de alta señal entre 80 y 120 líneas. Pasadas las 200 aproximadas, Claude no puede sostener cada instrucción mientras además hace el trabajo.

Paso 3: escribe reglas en positivo y universales

Dos reglas de redacción mueven la adherencia más que cualquier cambio de estructura. Primero: escribe qué hacer, no qué evitar. "Usa las utilidades del design system para los espaciados" gana a "no pongas los márgenes a mano": Claude sigue mejor las instrucciones en positivo que las negaciones. Segundo: mantén cada regla universal. CLAUDE.md entra en cada sesión, así que una regla sobre cómo construir una tabla concreta de la base de datos es ruido en las sesiones que tocan otra cosa. Lleva la guía situacional a los archivos a los que se aplica y deja en el archivo raíz solo las reglas que valen en todas partes.

Agrupa las reglas afines bajo encabezados Markdown y usa listas, no prosa. La jerarquía de encabezados no es decoración: los modelos la aprovechan para localizar el bloque adecuado, y los puntos en imperativo se leen mejor que los párrafos.

Paso 4: separa por alcance e importa el resto

Las costumbres personales y los estándares de equipo no van en el mismo archivo. Pon las preferencias de toda la máquina, como quieres que se escriban los mensajes de commit, en ~/.claude/CLAUDE.md, para que se carguen en cada proyecto. Pon los hechos específicos del proyecto y compartidos por el equipo en el ./CLAUDE.md versionado. Pon todo lo privado o experimental en ./CLAUDE.local.md, que se queda fuera del control de versiones.

Cuando el archivo de proyecto empiece a desbordarse, divídelo. CLAUDE.md admite la sintaxis de import @ruta/al/archivo, así un archivo raíz corto llama a @.claude/testing.md o @.claude/api-conventions.md y da a cada tema su responsable. Un aviso honesto: los archivos importados también se cargan al arrancar y pesan en la ventana de contexto, así que los imports compran legibilidad y orden, no un contexto más ligero. Mantén ligero el total, lo repartas como lo repartas.

Paso 5: mueve las comprobaciones fijas a los hooks, no a la prosa

Algunas reglas tienen que dispararse en un momento concreto: formatea tras cada edición, pasa el lint antes de cada commit, nunca escribas en una carpeta generada. Una línea de CLAUDE.md que lo pida acabará saltándose, porque el modelo decide en cada turno si la respeta. Los hooks no deciden. Se ejecutan como comandos de shell en eventos fijos del ciclo de vida, haga lo que haga Claude. Si una regla es mecánica e innegociable, va en un hook, no en la prosa. El modelo de eventos lo explicamos en la guía de hooks de Claude Code.

Paso 6: hazlo crecer por reacción, no por previsión

La forma más rápida de inflar un CLAUDE.md es cargarlo por adelantado con cada regla que imaginas que vas a necesitar. Haz lo contrario. Empieza mínimo y añade una regla solo después de que Claude cometa el mismo error dos veces. Una regla nacida de un error real vale su línea. Una regla añadida por previsión es un impuesto de contexto que pagas en cada sesión por un fallo que quizá nunca llegue. Las versiones recientes de Claude Code mantienen además una memoria automática: Claude escribe sus propias notas sobre comandos de build y correcciones mientras trabaja, y eso recorta lo que mantienes a mano.

Cómo sabes si tu CLAUDE.md funciona

Dos comprobaciones rápidas. Primera: abre una sesión nueva y pídele a Claude que resuma las reglas de proyecto que está siguiendo. Si se salta una regla que escribiste, o está enterrada o el archivo es demasiado largo. Segunda: fíjate en las correcciones que se repiten. Si acabas reexplicando lo mismo sesión tras sesión, ese hecho va en el archivo. Si en cambio corriges a Claude por aplicar una regla al pie de la letra en el contexto equivocado, esa regla no era universal y debe salir de la raíz.

Fallos frecuentes y arreglos

• Claude ignora reglas escritas con claridad. El archivo es demasiado largo. Recórtalo hacia las 120 líneas y las que sobreviven se cumplen.
• Una regla funciona en un proyecto y falla en otro. Está en ~/.claude/CLAUDE.md pero debería ser de proyecto, o al revés. Muévela al nivel correcto.
• Una regla de formato o de lint se salta siempre. La prosa no garantiza una acción en un punto fijo. Conviértela en un hook.
• El archivo creció a 400 líneas y nadie se fía. Divide por tema con imports, borra todo lo deducible y haz cumplir las partes duras con hooks.

Para ir más allá

Un CLAUDE.md es una pieza de un setup de Claude Code que funciona. Cuando el archivo ya es ligero, las siguientes palancas son los patrones de trabajo que usas a diario y saber cuándo una skill se gana su sitio y cuándo es solo peso. El archivo guía el comportamiento, los hooks lo hacen cumplir, las skills y los workflows lo escalan.