Un CLAUDE.md que Claude cumple de verdad en cada sesión

Si empiezas cada sesión de Claude pegando la misma nota sobre comandos, estilo de código y pruebas, estás haciendo a mano un trabajo que puede hacer un archivo. Un CLAUDE.md en tu proyecto guarda esas instrucciones recurrentes, y Claude las recoge en cada sesión nueva. A continuación verás cómo estructurarlo, qué debe incluir y qué conviene dejar fuera, con ejemplos que puedes adaptar.

Dónde va el archivo

Ponlo en la carpeta raíz del proyecto, justo al lado del README:

my-project/
 - CLAUDE.md
 - README.md
 - package.json
 - src/
 - tests/

Súbelo a Git para que tus compañeros reciban las mismas indicaciones. Otra ubicación válida es .claude/CLAUDE.md.

A medida que el proyecto crece, distintas zonas pueden necesitar reglas distintas. Para eso, coloca archivos CLAUDE.md adicionales en subdirectorios, por ejemplo uno para la carpeta del frontend y otro para la del backend:

my-project/
 - CLAUDE.md
 - src/
   - frontend/
     - CLAUDE.md
   - backend/
     - CLAUDE.md

Empieza con un único archivo en la raíz. Añade más solo cuando una parte del código necesite de verdad sus propias instrucciones.

Cambia las buenas intenciones por detalles concretos

Una instrucción que a ti te parece obvia puede resultar vaga para un agente. Líneas como estas suenan sensatas:

• Escribe código limpio
• Sigue las buenas prácticas
• Prueba a fondo
• Mantén la arquitectura coherente

Pero míralas desde el lado del agente. ¿Qué significa «a fondo» en este repositorio? ¿Qué buenas prácticas se aplican? Tú sabes lo que querías decir, pero el agente tiene que adivinarlo mientras no lo digas.

Así se lee la misma intención para una API en TypeScript:

• Los manejadores de rutas están en src/routes/.
• Las consultas a la base de datos van en src/repositories.
• Valida los cuerpos de las peticiones con los esquemas de Zod que ya existen.
• Envía los errores a través de src/lib/api-error.ts.
• Al corregir un bug, añade una prueba de regresión que reproduzca el fallo reportado.

Eso son decisiones, no deseos, y un agente puede seguirlas.

Enumera los comandos reales

Un proyecto puede tener pruebas unitarias, de integración y de navegador, y varias formas de arrancar la aplicación. «Ejecuta las pruebas después de cada cambio» no le dice al agente cuáles. Imagina un proyecto con pnpm y Vitest. Podrías escribir una sección de comandos indicando que se ejecutan desde la raíz del repositorio:

• Instala las dependencias con pnpm install.
• Arranca el servidor de desarrollo con pnpm dev.
• Comprueba los tipos con pnpm typecheck.
• Ejecuta las pruebas unitarias una sola vez con pnpm exec vitest run.
• Ejecuta un único archivo con pnpm exec vitest run <test-file>.

El directorio desde el que se ejecuta y los requisitos previos importan tanto como el propio comando. Ejecuta cada uno tú mismo antes de añadirlo. Un comando copiado que se queda en modo watch, o que necesita un servicio que nadie documentó, solo te trae un problema nuevo.

Y no hagas que cada cambio pequeño dispare todas las comprobaciones caras. Describe las que tienen sentido en el día a día y deja que la CI haga cumplir las obligatorias.

Anota las rarezas que parecen errores

Aquí es donde el archivo se gana su sitio. Supón que tu API guarda el dinero en céntimos enteros, de modo que 19,99 $ viaja por el sistema como 1999. Sin ese dato, un cambio de aspecto inocente puede introducir valores incoherentes. Una nota mejor recoge la regla y el punto de reutilización:

• Los importes en la API y en la base de datos son céntimos enteros.
• Solo la interfaz convierte a una moneda de visualización, y debe usar la función formatMoney() que ya existe en src/lib/money.ts.

O supón que un cliente móvil antiguo depende de un comportamiento raro. Una entrada de compatibilidad podría decir que POST /subscriptions devuelve HTTP 200 ante peticiones duplicadas, que los clientes móviles antiguos dependen de ello y que debe seguir así salvo que la tarea cambie explícitamente el contrato de la API. Esa última cláusula importa. Deja margen para cambios intencionados, de forma que una nota histórica no se convierta en una regla inexplicable que nadie puede revisar.

Una línea que explique por qué existe algo puede evitar un «arreglo» innecesario.

Convierte las correcciones repetidas en indicaciones

Imagina que Claude añade una nueva biblioteca de fechas aunque el proyecto ya tiene un formateador común. Podrías decir: «No añadas dependencias innecesarias». El problema es que la próxima vez discutiréis qué significa «innecesarias».

Una versión más sólida nombra la comprobación, señala el código y explica el camino para las excepciones:

• Antes de añadir una dependencia de ejecución, busca en package.json y en src/lib/ algo que ya haga ese trabajo.
• Para fechas, reutiliza src/lib/date.ts.
• Si de verdad hace falta un paquete nuevo, explica qué no pueden resolver las herramientas existentes.

Eso sí, sé selectivo. Una tarea rara no siempre justifica una regla permanente. Una buena prueba es preguntarse si la corrección seguirá importando dentro de un mes.

Deja fuera el trabajo de corta vida

Algunas notas caducan el mismo día en que se escriben:

Piensa en una nota como «hoy toca el bug del checkout, la cuenta rota es test-user-42, sube el timeout antes que nada».

Si eso se queda en CLAUDE.md cuando el bug ya no existe, confundirá a una sesión posterior. Guarda las instrucciones de cada tarea en archivos aparte. Claude Code también admite reglas acotadas por ruta dentro de .claude/rules/, algo adecuado para indicaciones que solo afectan a ciertas partes del árbol.

Una plantilla para empezar

Empieza por lo básico que un asistente necesita antes de tocar tu código: el propósito del proyecto, los comandos para ejecutarlo, las convenciones de la casa y una forma de verificar los resultados. Este esqueleto cubre todo eso, y los detalles los pones tú:

Project overview
 - Briefly explain what this project does and its main technologies.

Useful commands
 - Set up the project: [command]
 - Run locally: [command]
 - Run tests: [command]
 - Check formatting and linting: [command]

Mention where to run these commands and any required setup.

Where things live
 - Point to the main source code, tests, and important documentation.
 - Include locations that may be difficult to find or easy to confuse.

Project conventions
 - Describe the patterns to follow and existing helpers to reuse.
 - Focus on decisions that aren't obvious from reading the code.

Things to watch out for
 - Explain unusual behavior that must be preserved.
 - Identify generated files and how they should be updated.
 - Give a short reason for each restriction.

Checking changes
 - Explain how to choose and run the relevant checks.
 - Ask Claude to report what it checked and anything it couldn't verify.

No hace falta rellenar todas las secciones. Si una no tiene nada útil que decir, bórrala. Sustituye los marcadores por comandos y rutas reales antes de confiar en el archivo.

Si has encontrado otro hábito que hace funcionar mejor un CLAUDE.md, pruébalo y quédatelo solo si sobrevive a unas cuantas sesiones reales.