He leído muchos archivos CLAUDE.md malos. La mayoría tienen el mismo problema: son una lista de deseos, no un briefing. Página tras página de "por favor escribe código limpio" y "sigue las mejores prácticas" — instrucciones tan genéricas que no cambian nada. Si tu CLAUDE.md podría pertenecer a cualquier proyecto en la tierra, es peso muerto.
Un archivo CLAUDE.md es la nota que Claude Code lee al inicio de cada sesión en tu repositorio. Se carga automáticamente. Es contexto persistente. Y aquí está lo que la gente pasa por alto: cada palabra en él cuesta tokens en cada solicitud. Así que la pregunta no es "¿qué podría decirle a Claude?" Es "¿qué hace Claude mal sin esto, que estoy cansado de corregir?"
Ese reencuadre lo cambia todo. Déjame mostrarte qué poner en tu archivo CLAUDE.md.
Empieza con lo que Claude no puede adivinar
Claude puede leer tu código. No puede leer tu mente. Las líneas más valiosas en cualquier CLAUDE.md son los hechos que no son visibles en los propios archivos.
## Proyecto
Esta es una app Next.js 14 que usa el App Router. Desplegamos en Cloudflare Pages.
El gestor de paquetes es pnpm — nunca npm ni yarn.
## Comandos
- `pnpm dev` — servidor local en :3000
- `pnpm test` — ejecuta Vitest, debe pasar antes de cualquier commit
- `pnpm typecheck` — ejecutar esto después de editar cualquier archivo .ts
Solo ese bloque de comandos te ahorra una docena de correcciones a la semana. Sin él, Claude ejecutará alegremente npm test y verá cómo falla, u omitirá el typecheck que siempre ejecutas. Con él, el agente hace lo correcto sin indicación.
Fíjate en que dije "nunca npm ni yarn." Los específicos ganan a los vibes. "Usa pnpm" es una sugerencia. "Nunca npm ni yarn" es una regla, y Claude la trata como una.
Codifica las convenciones que sigues re-explicando
Piensa en tu última semana de sesiones. ¿Qué corregiste más de una vez? Esas correcciones son tu CLAUDE.md.
## Convenciones
- Los components van en src/components, una carpeta por component.
- Usamos Tailwind. Sin CSS modules, sin styled-components.
- Las rutas API devuelven { data } o { error }, nunca valores desnudos.
- Las fechas siempre se almacenan como strings UTC ISO.
Cada una de esas es una decisión real que tu codebase ya tomó. Escribirla una vez significa que dejas de escribirla en cada sesión. Ese es el juego completo — mover la corrección recurrente de tu cabeza al archivo.
Una nota sobre las instrucciones de tono
Puedes dar forma a cómo trabaja Claude, no solo a lo que sabe:
## Estilo de trabajo
- Haz solo el cambio solicitado. No refactorices código adyacente a menos que se pida.
- Para decisiones pequeñas (nombres de variables, ubicación de archivos), simplemente elige uno y anótalo.
No te detengas a preguntar.
- Después de editar, ejecuta typecheck y tests antes de decirme que has terminado.
Esa línea del medio es oro si estás en un modelo Claude reciente. Los modelos más nuevos son más deliberados por defecto — pausarán y preguntarán sobre pequeñas decisiones mucho. Una breve instrucción "simplemente elige uno" recupera ese tiempo sin hacer al agente imprudente en lo que importa.
Qué omitir
Ahora las eliminaciones, que importan igual.
Corta cualquier cosa genérica. "Escribe código seguro y mantenible" no hace nada. Claude ya lo intenta. Gastas tokens para reafirmar el comportamiento por defecto.
Corta lo que está en el código. No pegues tu package.json completo ni listes cada dependencia. Claude puede abrir el archivo. Describe lo que no es obvio leyendo — como por qué elegiste una biblioteca, o cuál preferir cuando dos podrían funcionar.
Corta la novela. He visto archivos CLAUDE.md de 600 líneas. Para la línea 200, la relación señal-ruido es tan mala que las reglas importantes quedan enterradas. Un archivo ajustado de 40 líneas que Claude realmente sigue supera a uno extenso que medio ignora. Sé despiadado. Si una línea no ha ganado su lugar evitando un error real, bórrala.
Dónde va el archivo
Pon CLAUDE.md en la raíz de tu repositorio y Claude Code lo encuentra automáticamente. También puedes anidar uno en un subdirectorio — digamos frontend/CLAUDE.md — y Claude lo superpone cuando trabajas en esa carpeta. Útil para monorepos donde el backend y el frontend tienen reglas genuinamente diferentes.
También hay uno global en tu directorio de configuración personal que aplica a todos los proyectos. Mantengo el mío casi vacío: solo un par de preferencias personales que se mantienen en todos lados. El conocimiento específico del proyecto pertenece al proyecto, no a tu archivo global.
Una plantilla que puedes robar
# CLAUDE.md
## Proyecto
[Una o dos frases: qué es esto, el stack, dónde despliega.]
## Comandos
- [comando de desarrollo]
- [comando de pruebas — anota si debe pasar antes de los commits]
- [cualquier verificación que siempre ejecutas]
## Convenciones
- [una decisión que no es obvia por el código]
- [una preferencia de biblioteca]
- [un patrón que impones]
## Estilo de trabajo
- [qué tan exhaustivo/conservador ser]
- [cuándo preguntar vs. cuándo decidir]
Rellena eso, luego vive con ello una semana. Cuando te sorprendas corrigiendo a Claude en algo por tercera vez, esa es una línea que falta — añádela. Cuando notes una línea que nunca importó realmente, bórrala.
Un archivo CLAUDE.md no es un documento que escribes una vez. Es algo que afinas. Los buenos son cortos, específicos, y ganados de a una corrección. Empieza pequeño. Déjalo crecer solo donde tiene que crecer.