CLAUDE.md es un archivo de texto que se guarda en la carpeta de un proyecto y que Claude Code lee automáticamente antes de hacer nada. Sirve para no repetir en cada conversación cómo funciona ese proyecto — y es la diferencia entre una herramienta que hay que corregir siempre y una que ya sabe cómo trabajáis.
Qué problema resuelve
Claude Code trabaja sobre los archivos de un proyecto. Pero cada conversación empieza en blanco: no sabe cómo se levanta el entorno, qué convenciones seguís, qué está prohibido tocar ni por qué esa carpeta se llama así.
Sin ese contexto, la primera media hora de cada sesión se va en explicarlo. Y si un día se te olvida un detalle, el resultado se desvía sin que sepas por qué.
Es el manual que le darías a alguien que entra hoy al equipo, escrito una vez y leído siempre.
Qué se pone dentro
Lo que un compañero nuevo necesitaría saber antes de tocar nada:
| Qué | Ejemplo |
|---|---|
| Qué es el proyecto | Para qué sirve y quién lo usa |
| Cómo se arranca | Los comandos exactos, no una descripción |
| Convenciones | Cómo se nombran las cosas, en qué idioma se comenta |
| Cómo se trabaja | Si se toca la rama principal, cómo se despliega |
| Lo que nunca se hace | Qué ficheros no se tocan y por qué |
| Dónde está cada cosa | Los cuatro sitios que hay que conocer, no el árbol entero |
El apartado de lo que nunca se hace es el que más disgustos evita y el que casi nadie escribe. «No despliegues desde una rama» o «este fichero lo genera un script, no lo edites a mano» ahorran más tiempo que diez páginas de descripción.
Los errores habituales
- Escribir una enciclopedia. Un CLAUDE.md de veinte páginas se lee entero en cada conversación y diluye lo importante. Media página bien elegida rinde más.
- Documentar lo que ya se ve. La estructura de carpetas se descubre mirando. Lo que hay que escribir es lo que no se deduce: por qué las cosas son como son.
- Poner lo que cambia cada semana. El estado de una tarea en curso no va aquí. Aquí va lo estable.
- Escribirlo y olvidarlo. Cuando notes que corriges siempre lo mismo, esa corrección pertenece al archivo.
Cómo saber si el tuyo sirve
Prueba directa: pídele algo típico del proyecto en una conversación nueva, sin explicarle nada. Si tiene que preguntarte cosas que están en el archivo, es que no están claras. Si hace algo que vuestras convenciones prohíben, falta esa regla.
Y la regla de mantenimiento: cada corrección que repites dos veces es una línea que falta.
Si no programas
CLAUDE.md es específico de Claude Code, que es la herramienta para trabajar sobre archivos de un proyecto. Si tu uso es escribir, resumir y preparar documentos en el navegador, el equivalente son los proyectos: mismo concepto —contexto permanente que no hay que repetir— con otra forma.
Y la idea de fondo es la misma que la de un system prompt: separar lo que se repite siempre de lo que se pide cada vez.
Por qué importa más de lo que parece
Un CLAUDE.md bien escrito es conocimiento de la empresa puesto por escrito. Sirve igual para quien entre mañana, y obliga a explicitar decisiones que hasta entonces estaban solo en la cabeza de alguien.
Esa es la parte que sorprende: escribirlo mejora el proyecto aunque nadie use la IA después.
Se monta con un proyecto real en Skills y Plugins de Claude, y la base de cómo dar contexto está en Claude para principiantes.
Preguntas frecuentes
¿Qué es el archivo CLAUDE.md?
Un archivo de texto que se guarda en la carpeta de un proyecto y donde se escribe cómo funciona ese proyecto: cómo se arranca, qué convenciones hay, qué no se toca. Claude Code lo lee antes de cada tarea, así que no hay que repetir esas instrucciones cada vez.
¿Qué conviene escribir en un CLAUDE.md?
Lo que le dirías a alguien que entra nuevo y no vas a poder repetir: comandos habituales, decisiones ya tomadas, lo que está prohibido tocar. Lo que no aporta es describir lo que ya se ve leyendo los archivos.
¿Cuánto debe medir?
Lo más corto que siga siendo completo. Ocupa espacio en cada conversación, así que un archivo enorme resta sitio para el trabajo de verdad. Si algo sólo hace falta de vez en cuando, mejor decirlo en el momento.
¿Sirve CLAUDE.md fuera de programación?
Sí. Cualquier trabajo con reglas propias que se repiten —criterios de redacción, formatos de entrega, cosas que nunca se hacen— se beneficia de tenerlas escritas en un sitio que se lea solo.