Hay una diferencia enorme entre la gente que dice que Claude Code es increíble y la que dice que se equivoca todo el tiempo. Casi siempre es el mismo archivo.
El CLAUDE.md se carga al inicio de cada sesión y es todo lo que Claude sabe de tu proyecto antes de leer una sola línea de código. Está mal configurado en la mayoría de los repositorios que he abierto, y está mal en las dos direcciones: o no existe, o tiene setecientas líneas donde la instrucción que importa se perdió entre cuarenta que no.
Esta guía es cómo se arma bien: dónde va, qué entra, qué no, y por qué la regla de las 200 líneas no es un capricho.
Qué es exactamente, y qué no es
Un detalle técnico que explica casi todo el comportamiento que la gente encuentra raro: el contenido del CLAUDE.md no se inyecta como prompt de sistema. Llega como un mensaje de usuario justo después del prompt de sistema.
La consecuencia: es contexto, no configuración obligatoria. Claude lo lee y trata de seguirlo, pero no hay garantía de cumplimiento estricto, sobre todo si las instrucciones son vagas o se contradicen entre sí.
Por eso, si necesitas que algo pase siempre —correr el linter después de cada edición, bloquear escrituras a una carpeta— eso no va en el archivo. Va en un hook, que se ejecuta como comando de shell en un punto fijo del ciclo de vida y no depende de lo que el modelo decida.
Los cuatro lugares donde puede vivir
Se cargan de lo más general a lo más específico, y no se pisan entre sí: se concatenan. Lo que está más cerca de donde arrancaste la sesión se lee al final.
- Política administrada — para toda una organización, desplegado por el área de sistemas. En macOS vive en
/Library/Application Support/ClaudeCode/CLAUDE.md. No lo puede excluir nadie. - Tus preferencias —
~/.claude/CLAUDE.md. Aplica a todos tus proyectos. Aquí van tus manías, no las reglas del equipo. - El proyecto —
./CLAUDE.mdo./.claude/CLAUDE.md. Este es el que se sube al repositorio y comparte el equipo. Es el que importa. - Tus cosas de este proyecto —
./CLAUDE.local.md, que va al.gitignore. Tus URLs de pruebas, tus datos de ejemplo.
Además, Claude Code va subiendo por el árbol de directorios desde donde arrancaste, recogiendo cada CLAUDE.md que encuentre en el camino. En un monorepo eso significa que puedes acabar cargando el archivo de otro equipo sin darte cuenta.
Las cinco reglas
1. La prueba del borrado
Para cada línea que quieras meter, hazte una sola pregunta: si borro esto, ¿Claude se equivoca? Si la respuesta es no, va fuera.
Suena obvio y elimina el 60% de lo que la gente escribe. Fuera se van: los mapas de directorios, las listas de dependencias, las descripciones archivo por archivo, las explicaciones de arquitectura que se deducen leyendo el código, y todo lo que sea "escribe código limpio".
Se quedan: los comandos que no puede adivinar, las reglas de estilo que difieren del estándar del lenguaje, cómo se corren las pruebas, las convenciones de ramas y de pull request, las decisiones de arquitectura propias del proyecto, las variables de entorno que hacen falta, y las trampas conocidas.
La versión corta: escribe lo que le explicarías a alguien que llega el lunes y no puede preguntarle a nadie.
2. Específico y verificable, nunca adjetivos
"Formatea bien el código" no significa nada. "Usa indentación de 2 espacios" sí. La diferencia no es de estilo: una instrucción verificable se cumple o no se cumple, y una vaga se interpreta distinto cada sesión.
El mismo principio aplica a rutas y comandos. En vez de "mantén los archivos organizados", escribe dónde viven las cosas. En vez de "prueba tus cambios", escribe el comando exacto que hay que correr.
Si una instrucción es crítica, se vale subirle el volumen. Marcarla con "IMPORTANTE" o "SIEMPRE" mejora la adherencia. Pero si todo está marcado como importante, nada lo está.
Prueba rápida: si dos personas de tu equipo pueden leer la misma línea y hacer cosas distintas, está mal escrita.
3. Menos de 200 líneas
Es la recomendación oficial y tiene una razón mecánica: el archivo se carga entero en cada sesión, consume contexto junto con tu conversación, y los archivos largos bajan la adherencia. No es que Claude se canse; es que tu instrucción importante compite con otras ciento cincuenta.
La señal de que rompiste el límite no es contar líneas. Es esta: Claude sigue haciendo algo que tienes prohibido por escrito. Cuando eso pasa, el reflejo de casi todos es agregar la regla otra vez, más grande. Es exactamente lo contrario de lo que hay que hacer.
Verifícalo: /doctor revisa el archivo del repositorio y propone recortes, quitando lo que Claude puede deducir del código y conservando las trampas y las convenciones que difieren de lo estándar.
4. Sin contradicciones, en toda la jerarquía
Si dos reglas se contradicen, Claude puede tomar cualquiera de las dos. Y las contradicciones casi nunca están dentro del mismo archivo: están entre tu archivo personal y el del proyecto, o entre el del proyecto y uno anidado en una subcarpeta.
Revisa los tres niveles de vez en cuando y borra lo que ya no aplica. En un monorepo donde se cuelan archivos de otros equipos, existe la opción de excluirlos por patrón desde los ajustes locales.
Para diagnosticar: /context te dice qué archivos de memoria se cargaron de verdad en esta sesión. Si el tuyo no aparece ahí, Claude no lo está viendo y no hay nada que redactar mejor.
5. Trátalo como código
Revísalo cuando algo salga mal. Pódalo cada tanto. Súbelo al repositorio para que el equipo lo mejore. Y cuando cambies una instrucción, comprueba que el comportamiento cambió de verdad, en vez de asumir que sí.
Este archivo es de las pocas cosas en un proyecto que se vuelven más valiosas con el tiempo, porque cada tropiezo que documentas es un tropiezo que no se repite. También es de las que más rápido se pudren si nadie las mantiene.
El hábito: cuando corrijas a Claude por segunda vez sobre lo mismo, esa corrección se escribe en el archivo. No la tercera. La segunda.
Un arranque que puedes copiar hoy
La forma más rápida de tener uno es correr /init, que analiza el proyecto y genera un archivo inicial con los comandos y convenciones que encuentra. Si ya existe uno, propone mejoras en vez de sobrescribirlo. Después lo refinas con lo que Claude no puede descubrir solo.
Si prefieres arrancar a mano, esta estructura cubre lo que de verdad hace falta:
# Nombre del proyecto
Una línea: qué es esto y para quién.
## Comandos
- Instalar: [comando]
- Correr en local: [comando]
- Pruebas: [comando exacto, y cómo correr una sola prueba]
- Lint y tipos: [comando]
## Dónde vive qué
Solo lo que no es obvio navegando el repo. 3 o 4 líneas, no un árbol completo.
## Convenciones que difieren de lo estándar
- [regla concreta y verificable]
- [regla concreta y verificable]
## Trampas conocidas
- [cosa que rompe y no es evidente]
- [variable de entorno obligatoria y qué pasa sin ella]
## Flujo de trabajo
- Antes de terminar una serie de cambios: [comando de verificación]
- Ramas: [convención]
- Commits y PR: [convención]
## No tocar
- [archivos, carpetas o procesos que Claude no debe modificar]La última sección es la que más devuelve y la que casi nunca aparece. Un "no tocar" explícito ahorra más problemas que diez reglas de estilo.
El paso que todo mundo se salta: confirmar que el archivo se cargó. Corre /context y búscalo en la lista de archivos de memoria. He visto a gente pasar una hora reescribiendo instrucciones que Claude nunca leyó, porque el archivo estaba en una carpeta que no se recorre. Antes de mejorar la redacción, comprueba que existe en el contexto.
Cuando ya no cabe en 200 líneas
Hay tres salidas, y solo dos sirven.
La que no sirve del todo: partirlo en varios archivos con importaciones @ruta/al/archivo. Ordena la lectura para humanos, pero los archivos importados se cargan igual al arrancar, así que no ahorras nada de contexto. Sirve para organizar, no para adelgazar.
La primera que sí: las reglas por ruta. En .claude/rules/ pones archivos de markdown por tema, y con un campo paths en el encabezado los amarras a patrones de archivo. Esas reglas solo entran al contexto cuando Claude trabaja con archivos que coinciden. Es la forma correcta de tener reglas de API que no molestan cuando estás tocando el frontend.
La segunda que sí: las skills. Si lo que creció es un procedimiento de varios pasos y no un hecho, eso no es memoria: es una skill, y las skills se cargan solo cuando se usan. Un procedimiento de doscientas líneas cuesta casi nada mientras no lo invoques.
La regla para decidir entre las tres: hechos que aplican siempre van al CLAUDE.md; hechos que aplican a una parte del código van a reglas con ruta; procedimientos van a skills. Dónde encaja cada mecanismo está en las 7 formas de controlar Claude Code.
Cómo saber si está funcionando
Dos señales, y las dos son de comportamiento, no de contenido.
La primera: Claude deja de preguntarte cosas que están en el archivo. Si te sigue preguntando algo que escribiste, la redacción es ambigua o el archivo está tan largo que se perdió.
La segunda: puedes pedirle algo en una frase sin contexto y sale bien. Si antes de cada petición tienes que escribir dos párrafos de explicación, esos dos párrafos son justo lo que le falta al archivo.
Y si el archivo sobrevive un /compact y aun así se pierde alguna instrucción: el del proyecto se vuelve a inyectar tras compactar, pero los anidados en subcarpetas y las reglas por ruta no. Se recargan la próxima vez que Claude toque un archivo de esa zona.