Qué escribir en CLAUDE.md

Si le explica una y otra vez a Claude Code las mismas reglas del proyecto, escríbalas en CLAUDE.md. Es un archivo de texto normal en formato Markdown. Claude Code lo lee al inicio de la sesión y recibe sus acuerdos junto con el resto del contexto.

Para empezar bastan unas cuantas líneas comprobadas: dónde trabajar, cómo verificar el resultado y qué hay que conservar al hacer cambios.

Un ejemplo de CLAUDE.md

Tomemos una página sencilla con tarjetas. El marcado, los estilos y el JavaScript están en un solo index.html, y la página se puede abrir directamente en el navegador. Para un proyecto así, el archivo de instrucciones podría tener este aspecto:

# CLAUDE.md

## Proyecto
- La página, los estilos y el JavaScript están en `index.html`.

## Verificación
- Abrir `index.html` en el navegador.
- Revisar la página en una pantalla ancha y en una estrecha.

## Reglas
- Mantener los colores actuales y el estilo de las tarjetas.
- No eliminar bloques terminados sin confirmación.
- Al terminar, enumerar los cambios y las comprobaciones.

Aquí hay tres grupos: cómo está organizado el proyecto, cómo se verifica el resultado y qué se ha acordado. Ahora, al pedir "añade una tarjeta más", ya no hace falta volver a enumerar todas las reglas. Eso sí, la página puede comprobarla usted mismo: tener la instrucción no le da al agente acceso al navegador si no dispone de esa herramienta.

Es un ejemplo para un solo archivo, no una plantilla universal. Su proyecto puede tener carpetas separadas y sus propios comandos de ejecución. Escriba justo esos; si no hay tests, no añada un comando inventado solo para que la lista quede completa.

Qué vale la pena anotar

El filtro principal: ¿necesitará esta nota en las próximas tareas? Son útiles los comandos comprobados, las rutas importantes y los acuerdos que el agente no puede deducir de forma fiable a partir del código. Sobre todo los que ya ha tenido que repetir.

Formule cada regla de modo que quede claro qué acción se espera del agente:

"revísalo todo" → "después de cambiar las tarjetas, revisa la página en una pantalla ancha y en una estrecha";
"no toques lo importante" → "no elimines bloques terminados sin confirmación: su contenido ya está aprobado".

En el primer caso se nombra la comprobación; en el segundo, el alcance de la restricción y el motivo. Eso sirve más que una larga lista de deseos del tipo "trabaja con cuidado".

README.md le explica a una persona de qué trata el proyecto y cómo empezar a trabajar. CLAUDE.md reúne las instrucciones para el agente. No hace falta resumir todo el README. Y una hipótesis como "parece que el texto se descoloca por el ancho de la tarjeta" déjela en una nota de la tarea actual, por ejemplo PROJECT_NOTE.md. Es un archivo normal con el nombre que usted elija; cuando retome la tarea, pídale al agente que lo lea.

No anote una suposición como si fuera un hecho comprobado y no guarde aquí contraseñas ni claves de acceso. El CLAUDE.md común se suele añadir a Git para que los compañeros reciban las mismas instrucciones junto con el proyecto.

Cómo crear y comprobar el archivo

Empiece por las reglas que ya conoce. No hace falta esperar a que se acumule una larga lista de errores ni describir de antemano todas las situaciones posibles.

Mire si el proyecto ya tiene un CLAUDE.md. Si lo tiene, léalo y amplíelo. Para un archivo nuevo, elija la raíz del proyecto; también se admite la ubicación .claude/CLAUDE.md, pero no tiene sentido crear las dos copias.
Escriba unas cuantas líneas a mano o introduzca /init en Claude Code, abierto en la carpeta del proyecto. El comando analizará el proyecto y preparará un borrador; si el archivo ya existe, propondrá mejoras.
Lea el resultado. Contraste los comandos y las rutas con el proyecto y elimine las conjeturas. Por ejemplo, si el agente ha escrito un comando de tests que usted no tiene, bórrelo. Las restricciones que solo conoce usted, añádalas usted mismo.
Guarde el archivo y abra una sesión nueva en la carpeta del proyecto. Introduzca /context: en la sección Memory files debería aparecer la ruta a su CLAUDE.md.

Después pruebe un cambio pequeño: por ejemplo, pida que se añada una tarjeta y fíjese en si se han mantenido los colores y si ha aparecido el informe de comprobaciones. Si el archivo no aparece en la lista, revise primero su nombre y la carpeta desde la que se inició la sesión. Si aparece, pero el resultado no coincide con la regla, revise la redacción y las posibles contradicciones.

Cargado no significa cumplido

Que el archivo aparezca en la lista confirma que se ha cargado, pero no garantiza que se cumplan las reglas. Una respuesta correcta del agente tampoco demuestra por sí sola que se haya cargado: la información podría venir de otros archivos. Una instrucción orienta el trabajo, pero no crea un bloqueo técnico sobre ninguna acción.

Dónde anotar lo demás

Para un primer proyecto basta con un CLAUDE.md. Cuando aparecen indicaciones personales o muchas reglas comunes, el esquema le ayudará a elegir dónde anotar cada cosa:

Primero defina para qué sirve la nota y después elija el archivo.

Una regla común puede afectar a una sola carpeta y aun así ser necesaria para todo el equipo. .claude/rules/ ayuda a repartir ese tipo de instrucciones por temas; limitarlas a rutas concretas se configura aparte. Para un par de reglas no hace falta complicar la estructura.

CLAUDE.local.md sirve para las indicaciones personales en este proyecto, por ejemplo la preferencia por respuestas breves. Añádalo a .gitignore para no incluirlo en los commits. El agente lee igualmente el archivo local, así que tampoco es sitio para secretos.

La memoria automática (auto memory) es un conjunto de notas aparte que Claude guarda mientras trabaja, si el mecanismo está activado. No deje una regla importante solo a criterio de Claude: pídale directamente que la añada a CLAUDE.md. Una hipótesis provisional sobre un bug se queda en la nota de la tarea.

Si el proyecto ya tiene un AGENTS.md, no copie su contenido en un segundo archivo. En CLAUDE.md puede incluir el archivo vecino con la línea @AGENTS.md. Esto resulta especialmente útil al añadir un CLAUDE.local.md: el archivo personal puede influir en la lectura directa de AGENTS.md. Hay otras opciones descritas en la documentación.

Cuándo actualizar las reglas

Edite el archivo a la par que el proyecto. ¿Ha sacado los estilos de index.html a un archivo aparte? Corrija la línea sobre la estructura. ¿Ha cambiado la forma de verificar? Sustituya la instrucción antigua. No añada una regla nueva encima de una antigua que la contradice.

Una corrección que se repite puede encargársela al agente: "Añade a CLAUDE.md que antes de eliminar un bloque terminado hace falta mi confirmación". Después lea el cambio: debe reflejar su acuerdo sin restricciones nuevas añadidas por el agente. A menudo basta con una línea.

Si se incumple una regla, averigüe primero la causa en lugar de repetirla tres veces más. Elimine las notas obsoletas y conserve solo lo que ayuda en la siguiente tarea.