📄 Qué es CLAUDE.md
¿Eres nuevo aquí? O CLAUDE.md es un archivo de
texto simple (extensión .md, de «markdown», un formato de texto sin formato con pocos símbolos de
formato), colocado en la raíz del proyecto, que el agente lee automáticamente cada vez que abre la carpeta.
Es tu nota permanente para él.
💡 Concepto principal
- •Lectura automática: no necesitas pegar las reglas en cada conversación.
- •Reglas persistentes: siguen vigentes en cualquier sesión nueva.
¿Eres nuevo aquí? "La raíz del proyecto" es la carpeta principal, la que está por encima de todas
las demás, la que abriste cuando escribiste claude en el terminal (el programa de línea de
comandos donde escribes instrucciones en vez de hacer clic en botones). Si tu proyecto es una carpeta llamada
meu-site con subcarpetas imagens/ e textos/ dentro, el CLAUDE.md queda
suelto dentro de meu-site/, al mismo nivel que imagens/ e textos/ — nunca
dentro de una subcarpeta.
imagens/ o textos/.🔍 Ver por dentro
El CLAUDE.md es un archivo de texto común, igual que una foto o un documento; queda guardado en tu computadora, dentro de la carpeta del proyecto. Nada de lo que contiene "se va a internet" por sí solo: solo sale de tu máquina si publicas el proyecto en algún lugar (p. ej., git push) o pegar el contenido en algún sitio.
No cuesta nada mantenerlo: es solo un archivo de texto. El único «costo» es indirecto: cuantas más líneas tiene, más texto procesa el agente en cada sesión, lo que puede hacer que las respuestas sean más lentas y costosas (tema del próximo tópico).
✓ Dónde crear el archivo
- ✓Directamente en la raíz del proyecto, al mismo nivel que las demás carpetas
- ✓Nombre exacto:
CLAUDE.md, en mayúsculas y con la extensión.md
✗ Errores comunes
- ✗Guardar dentro de una subcarpeta: el agente no la encontrará por sí solo
- ✗Nombre incorrecto, por ejemplo,
claude.mdminúsculo oClaude.MD— en algunos sistemas esto impide la lectura automática
🔁 Por qué se lee en cada sesión
¿Eres nuevo aquí? Una "sesión" es una ventana de conversación con el agente —
comienza cuando abres el terminal y escribes claude, y termina cuando cierras esa ventana o
ese proceso. Cada nueva sesión de conversación «olvida» lo que se dijo en la sesión anterior: el agente empieza
desde cero, sin recordar nada de lo que acordaron antes. CLAUDE.md es la forma de darle una continuidad mínima:
toda sesión nueva ya empieza conociendo lo esencial del proyecto.
💡 Consejo práctico
Pegar las reglas en el chat cada vez funciona, pero cansa y un día se te olvida. CLAUDE.md lo resuelve de una vez: escríbelas una sola vez y, a partir de ahí, cada sesión nueva —incluso dentro de 3 meses— ya empieza conociendo las reglas del proyecto.
Cierras la terminal
Se pierde la conversación de esa sesión.
Ejecutas claude de nuevo, días después
Nueva sesión, sin memoria de la conversación anterior.
El CLAUDE.md se vuelve a leer automáticamente
Las reglas fijas siguen vigentes, aunque no repitas nada.
⚠️ Error común: edité el archivo y "no funcionó"
Si editas el CLAUDE.md en medio de una sesión que ya está abierta, es normal que el cambio no se aplique de inmediato: el agente ya leyó el archivo al comienzo de esa sesión y no vuelve a revisarlo con cada mensaje. Solución sencilla: guarda el archivo y empieza una sesión nueva (cierra y ejecuta claude de nuevo, o escribe /clear si el comando existe en tu versión). En la nueva sesión, lee la versión actualizada.
✂️ Por qué lo conciso supera a lo gigante
Este es el principio clave del módulo: un CLAUDE.md de 20 líneas bien escritas orienta mejor que uno de 500 líneas genéricas. El agente lee el archivo completo en cada sesión: demasiada información diluye lo que realmente importa, y las reglas demasiado específicas compiten por la atención con las reglas esenciales.
Piénsalo así: si alguien te entregara un manual de 40 páginas antes de cada tarea de 5 minutos, no podrías recordarlo todo — las instrucciones más importantes se perderían entre detalles poco comunes. Con el agente pasa algo parecido: lee todo el CLAUDE.md, pero cuanto más texto contiene, más difícil le resulta «ponderar» todas las reglas por igual. Un archivo corto mantiene destacadas las 3-5 reglas que realmente importan, en lugar de esconderlas entre excepciones poco comunes.
Señales de que tu CLAUDE.md creció demasiado: tú mismo no recuerdas qué escribiste ahí; hay secciones que nunca volviste a leer desde que las creaste; o el agente empieza a ignorar una regla que estaba clara — señal de que «desapareció» entre demasiado texto. En esos casos, recorta lo que uses poco y conserva solo lo que cambia el comportamiento en casi todas las tareas.
✓ CLAUDE.md conciso
- ✓20-40 líneas, directo al grano
- ✓Reglas que realmente cambian el comportamiento
- ✓Remite a otros archivos cuando se necesitan más detalles
✗ CLAUDE.md gigante
- ✗Cientos de líneas, intenta documentarlo todo
- ✗Reglas poco frecuentes mezcladas con las esenciales
- ✗El agente "pierde" la regla importante en medio del texto
💡 Consejo práctico
Este mismo principio reaparece en la Trilha 3 (Skills): una buena documentación señala el camino en vez de inflarse.
📋 Ejemplo real de CLAUDE.md, listo para copiar
Copia el modelo de abajo, ajusta los fragmentos marcados y guárdalo como CLAUDE.md en la raíz de tu proyecto.
Objetivo: tener un CLAUDE.md funcional en tu primer proyecto. Cómo verificar: abre Claude Code en la carpeta y pregunta "¿cuáles son las reglas de este proyecto?"; la respuesta debe mencionar lo que escribiste.
🔍 Cada sección del modelo, explicada
- Objetivo: una frase que resume el proyecto; ayuda al agente a entender el contexto general antes de cualquier tarea específica.
- Reglas: el corazón del archivo: comportamientos que siempre deben cumplirse, como «nunca publiques sin aprobación» o «responde en portugués».
- Comandos útiles: atajos que usas con frecuencia (p. ej.: cómo ejecutar las pruebas, cómo iniciar el servidor) — le ahorran al agente tener que "adivinar" el comando correcto.
- Qué nunca hacer: la lista de líneas rojas — carpetas que no se pueden borrar, acciones que exigen confirmación explícita antes de ejecutarse.
✓ Al escribir el tuyo
- ✓Guárdalo con el nombre exacto
CLAUDE.md, sin espacios - ✓Usa frases cortas y directas, una regla por línea
✗ Errores comunes
- ✗Dejar los textos de ejemplo (
<...>) sin reemplazarlo; el agente lo tomará al pie de la letra - ✗Escribir reglas demasiado vagas, como "sé cuidadoso"; es mejor preferir algo específico y comprobable
🧩 Cuando el proyecto crezca: señala, no lo sobrecargues
Si el proyecto incorpora procesos más complejos, los detalles adicionales van en archivos separados (dentro de
.claude/ o una carpeta doc/) que el CLAUDE.md señala con una línea, no dentro
de él. Así el archivo principal se mantiene siempre conciso, aunque el proyecto crezca.
🔍 Por dentro
Este principio de «apuntar en vez de inflar» es el mismo que sustenta las skills — procesos reutilizables que el agente carga solo cuando los necesita, tema de la Ruta 3.
✓ Cuando el proyecto crezca
- ✓Crea un archivo separado por tema (p. ej.,
doc/deploy.md) - ✓En el CLAUDE.md, deja solo una línea que apunte a él
✗ Lo que debes evitar
- ✗Pegar todo el contenido del archivo de detalle dentro de CLAUDE.md
- ✗Dejar información desactualizada duplicada en dos lugares
🧪 Probar CLAUDE.md: pide un resumen
La prueba de que el archivo funciona es sencilla: pídele al agente que resuma su propio proyecto justo después de escribir el archivo. Si la respuesta coincide con lo que escribiste, funcionó.
Objetivo: confirmar que CLAUDE.md realmente se está leyendo. Cómo verificar: la respuesta debe citar el objetivo y las reglas exactamente como los escribiste — este es el ejercicio final de la ruta, retomado en el módulo 0.6.
⚠️ ¿Falló? Lista de verificación rápida
- •¿La respuesta fue genérica y no mencionó tus reglas? Comprueba que el archivo esté en la raíz del proyecto (Tema 1) y que hayas abierto la terminal dentro de esta carpeta antes de ejecutar
claude. - •¿Editaste el archivo ahora y la respuesta no cambió? Cierra la sesión y abre una nueva (Tema 2): los cambios realizados durante la sesión no se vuelven a leer automáticamente.
- •Guardado como
.txtpor error en vez de.md? Cambia el nombre del archivo: la extensión incorrecta impide la lectura automática.