La plantilla de CLAUDE.md que se mejora sola

Hay un impuesto que casi nadie contabiliza: el tiempo que pasas volviéndole a explicar a Claude cosas que ya le habías explicado. Que las pruebas se corren con un comando y no con otro. Que ese servicio está deprecado. Que en este repo los handlers viven en tal carpeta.

Cada sesión arranca con la memoria en blanco. Tú no. Entonces tú cargas con la diferencia, todos los días, y ni siquiera lo notas porque son treinta segundos cada vez.

El archivo CLAUDE.md es donde se paga ese impuesto una sola vez. Y hay una forma de escribirlo que la documentación oficial recomienda de frente: no lo redactes de golpe, déjalo crecer cada vez que Claude se equivoca. Aquí está el mecanismo, la plantilla completa para arrancar, y el ritual de dos semanas que lo deja afilado.

Qué es y dónde vive

CLAUDE.md es un archivo de texto con instrucciones que Claude lee al principio de cada sesión. Nada más. Su poder no está en la tecnología, está en que es el único lugar donde el conocimiento de tu proyecto no se evapora.

Puede vivir en varias capas, y todas se cargan juntas:

• Tuyo, para todos los proyectos: ~/.claude/CLAUDE.md. Tus manías, tu forma de trabajar.
• Del proyecto, compartido con el equipo: ./CLAUDE.md o ./.claude/CLAUDE.md. Esto se sube a control de versiones y es lo que hace que tu compañero nuevo arranque con contexto.
• Tuyo, solo en ese proyecto: ./CLAUDE.local.md. Tus URLs de pruebas, tus datos de sandbox. Va al .gitignore.

El comando /memory te abre esos archivos desde la sesión, y /context te confirma cuáles cargaron de verdad. Ese segundo paso es el que salta la gente que jura que "Claude no le hace caso a mi CLAUDE.md": muchas veces el archivo ni siquiera se está cargando.

El truco: que Claude escriba sus propias correcciones

La regla que recomienda la documentación es simple. Cuando Claude comete el mismo error por segunda vez, no lo corriges: le pides que actualice el archivo.

La diferencia es que corregir en el chat dura lo que dura la sesión. Corregir en el archivo dura para siempre y le sirve a todo el equipo. Este es el mensaje que uso, tal cual:

Acabas de cometer un error que ya habías cometido antes en este repo.

Antes de seguir, haz esto:

1. Nombra en una frase qué asumiste mal.
2. Escribe la regla que te habría evitado el error. Concreta y verificable:
   "corre `pnpm test:unit` antes de cada commit", no "prueba tus cambios".
3. Revisa el CLAUDE.md del proyecto. Si ya hay una instrucción sobre ese
   tema, corrígela en vez de agregar una nueva. No quiero reglas duplicadas
   ni contradictorias.
4. Agrega o edita la línea en la sección que le corresponda.
5. Muéstrame el diff del CLAUDE.md antes de guardarlo.

Si la regla solo aplica a una parte del repo, dímelo y la movemos a
.claude/rules/ en vez de meterla al archivo principal.

Ese paso 3 es el que hace que funcione a largo plazo. Sin él, a los dos meses tienes un archivo con cuatro reglas sobre lo mismo, dos de ellas contradiciéndose, y Claude escoge una al azar.

La plantilla de arranque

Puedes correr /init y Claude genera un primer CLAUDE.md leyendo tu código. Sirve, pero sale genérico: describe lo que ya se puede deducir del repo. El valor está en lo que no se deduce.

Esta es la estructura con la que arranco. Cópiala, bórrale lo que no aplique y llénala con lo que solo sabe alguien que ya trabajó ahí.

# Contexto del proyecto

Qué es esto y para quién, en dos frases. Nada de marketing.

## Comandos

- Instalar: `...`
- Correr en local: `...`
- Pruebas: `...`
- Linter y formato: `...`
- Build de producción: `...`

## Dónde vive cada cosa

- `src/...` — ...
- `tests/...` — ...
- Las migraciones se generan con `...`, nunca a mano.

## Convenciones que no son obvias

- Indentación de 2 espacios.
- Los nombres de archivo van en kebab-case.
- Los errores se devuelven con el formato estándar de `src/errors.ts`.

## Reglas duras

- Nunca hacer commit directo a `main`.
- Nunca tocar los archivos de `vendor/`.
- Antes de cambiar el esquema de base de datos, propón el plan y espera OK.

## Trampas conocidas

- Las pruebas de integración necesitan Redis corriendo en local.
- El servicio de correo está apagado en desarrollo: no intentes probarlo.
- El módulo de facturación se ve muerto pero lo usa el cierre mensual.

## Decisiones ya tomadas (no volver a discutirlas)

- Usamos X y no Y porque Z. Si crees que hay que cambiarlo, dilo, no lo cambies.

## Aprendizajes
<!-- Aquí se acumula lo que sale del bucle de corrección. Una línea cada uno. -->

La sección de trampas conocidas es la que más rinde y la que nadie escribe. Un modelo puede leer tu código y deducir la arquitectura. Lo que no puede deducir es que ese módulo que parece muerto lo usa finanzas el último día del mes.

El ritual de dos semanas

Un CLAUDE.md escrito de un jalón y nunca revisado se pudre. Este es el ciclo que sí aguanta:

1. Día 1. Corre /init, quédate con lo útil y llena a mano las secciones de trampas y decisiones. No pases de una página.
2. Días 2 al 13. Cada vez que corrijas a Claude por segunda vez, pega el prompt de arriba. No lo hagas a la primera: la primera puede ser mala suerte, la segunda es un patrón.
3. Día 14. Abre el archivo y léelo completo. Borra lo que ya no aplica, junta las reglas que dicen lo mismo, y mueve a .claude/rules/ todo lo que solo importe en una parte del repo.
4. Repite. A la tercera vuelta el archivo deja de crecer y empieza a mejorar. Ese es el punto al que quieres llegar.

Sobre el largo: la recomendación oficial es quedarse por debajo de 200 líneas. No es un límite técnico, es que los archivos largos consumen contexto y bajan la adherencia. Si tu archivo se desborda, no lo compactes escribiendo más corto: separa por ruta. Un archivo en .claude/rules/ con un campo paths en el frontmatter solo se carga cuando Claude toca archivos que hacen match.

El error que veo en las empresas

El patrón más común no es descuidar el archivo. Es lo contrario: convertirlo en un manual de operaciones de 600 líneas donde alguien volcó toda la wiki interna.

Eso no funciona por dos razones. Consume contexto que le hace falta al trabajo real, y entierra las cinco reglas que sí importan entre doscientas que no. Un archivo de veinte líneas bien escogidas le gana a uno de seiscientas, todos los días.

La prueba para decidir si una línea se queda: ¿esto le hace falta a Claude en cada sesión, o solo cuando toca un tema específico? Si es lo segundo, eso es una skill o una regla por ruta, no una instrucción global. La diferencia entre esas tres cosas la desarrollo en skill, workflow o agente, y el resto de las palancas de la sesión están en los comandos que uso todos los días.