Hay un archivo de texto que escribí hace meses y que, desde entonces, trabaja silenciosamente en cada sesión de Claude Code que abro. No es código. No es una base de datos. Es un archivo Markdown de unos 200 líneas que funciona como el cerebro de mis agentes de IA.
Se llama CLAUDE.md.
Resumen rápido: CLAUDE.md es el archivo de instrucciones que Claude Code lee automáticamente al inicio de cada sesión. Le dice al agente quién eres, qué proyecto tiene delante, qué reglas debe seguir y cómo debe comportarse. Sin él, tienes que explicar el contexto de cero cada vez. Con él, el agente arranca sabiendo exactamente dónde está.
Si usas Claude Code y no tienes un CLAUDE.md bien trabajado, estás perdiendo el 40% del valor de la herramienta.
Qué es CLAUDE.md y por qué existe
Claude Code no tiene memoria persistente entre sesiones. Cada vez que abres una nueva conversación, el agente no sabe qué proyecto tienes, cómo te llamas, qué convenciones usas ni qué errores cometió ayer.
CLAUDE.md resuelve exactamente ese problema.
Es un archivo de texto en formato Markdown que Claude Code busca y lee automáticamente antes de hacer cualquier cosa. No tienes que pedírselo. No tienes que copiarlo en el prompt. Simplemente existe en tu proyecto y el agente lo consume como parte de su contexto de arranque.
La analogía más clara: es como el manual de incorporación que le das a un empleado el primer día. Solo que este empleado lo olvida todo al final de la jornada, así que el manual hay que tenerlo siempre accesible.
Hay dos ubicaciones posibles:
~/.claude/CLAUDE.md— Instrucciones globales. Se aplican a todos tus proyectos./raíz-del-proyecto/CLAUDE.md— Instrucciones del proyecto. Se aplican solo a ese proyecto.
Claude Code carga ambos y los combina, dando prioridad al del proyecto cuando hay conflicto.
Cómo lo uso yo (con ejemplos reales)
Tengo un CLAUDE.md global que contiene información sobre mí que aplica a todos mis proyectos: quién soy, cuál es mi estilo de comunicación, las restricciones generales que quiero en todo mi trabajo.
Y luego tengo un CLAUDE.md específico en cada proyecto. El de mi blog pabloypunto.com es diferente al del dashboard de agentes, que es diferente al de Ariel.
Déjame mostrarte la estructura real del que uso en este blog.
La sección de contexto: quién es Pablo y qué hace este proyecto
# Contexto
Soy Pablo, solopreneur y fundador de Buildt Academy.
Cofundé GuruWalk (marketplace de free tours, 300K viajeros/año).
Tengo un equipo de agentes de IA que gestiona mi marketing.
Este proyecto es mi blog personal en pabloypunto.com,
construido con Next.js 15 + Markdown.
Esta sección parece obvia, pero marca la diferencia. Cuando el agente tiene este contexto, sus sugerencias de contenido, código y estructura están alineadas con mi realidad, no con una realidad inventada.
Las reglas de comportamiento
# Reglas de comportamiento
- NUNCA digas que "vendí GuruWalk". Di "fundé GuruWalk" o "cofundador de GuruWalk".
- Pablo solo usa Claude Code. NO uses Cursor, Copilot, Replit ni Devin.
- No uses emojis en el código ni en respuestas técnicas.
- Antes de hacer cambios grandes, resume el plan y pide confirmación.
- Si encuentras un bug que no pedí que arreglaras, menciónalo pero no lo arregles sin permiso.
Las reglas negativas son las más valiosas. No "haz X", sino "nunca hagas Y". Le das al agente los límites dentro de los cuales moverse.
El flujo de trabajo para tareas habituales
# Workflow: publicar un post de blog
1. Leer content/KEYWORD-RESEARCH-BLOG.md para elegir keyword
2. Ver posts existentes en content/blog/ para no repetir
3. Crear content/blog/[slug].md con frontmatter completo
4. Crear SVGs en public/blog/img/
5. Build: node scripts/build-blog.js
6. Deploy: npm run build && npx vercel --prod
7. Indexar: node scripts/request-indexing.js [URL]
Este bloque por sí solo me ahorra 10 minutos de instrucciones por sesión. El agente sabe exactamente qué pasos dar cuando le digo "publica un post".
La estructura de un CLAUDE.md bien hecho
¿Quieres montar tu propio equipo de agentes de IA?
Cada semana comparto lo que funciona (y lo que no) montando agentes reales para mi negocio. Sin teoría, sin humo.
🎁 Al suscribirte recibes mi guía: cómo llegué a 500 subs en <1 mes con agentes IA.
Después de iterar durante meses, he llegado a una estructura que funciona para casi cualquier proyecto:
Sección 1: Contexto del proyecto
Responde a tres preguntas:
- ¿Qué es este proyecto? (una línea)
- ¿Para quién es? (quién lo usa o lo lee)
- ¿Qué tecnologías usa? (stack, dependencias clave)
Sin este contexto, el agente tiene que inferir el tipo de proyecto por el código que ve. A veces acierta. A veces propone una solución de Django para un proyecto Express.
Sección 2: Reglas de comportamiento
Las reglas más útiles son las que evitan errores recurrentes. Si el agente cometió el mismo error tres veces, escribe una regla. Las categorías habituales:
- Estilo de código: convenciones de nombres, formateo, comentarios
- Restricciones de actuación: qué puede cambiar sin permiso, qué debe consultar antes
- Datos sensibles: variables de entorno, credenciales, información que no debe incluir en respuestas
- Tono de comunicación: si quieres respuestas cortas, sin floreos, en español
Sección 3: Arquitectura y estructura de archivos
# Estructura del proyecto
/content/blog/ → Posts en Markdown
/public/blog/img/ → Imágenes de los posts
/scripts/ → Scripts de build, indexación, deploy
/src/app/ → App Next.js
/src/components/ → Componentes React
Este mapa le evita al agente tener que explorar el filesystem cada vez que quiere entender dónde están las cosas.
Sección 4: Flujos de trabajo habituales
Documenta los 3-5 flujos que repites más. Cada uno como una lista numerada. El agente los ejecuta como si siguiera un procedimiento operativo estándar.
Sección 5: Lo que NO debe hacer nunca
La sección más importante y la que más se olvida. Cosas como:
- No hacer deploy a producción sin confirmación explícita
- No borrar archivos aunque parezcan innecesarios
- No instalar dependencias sin decírtelo primero
- No asumir que una tarea está terminada sin verificar
CLAUDE.md para cada uno de mis agentes
Cada uno de mis agentes vive en su propio entorno con su propio CLAUDE.md:
| Agente | Proyecto | CLAUDE.md define |
|---|---|---|
| Ariel | Newsletter pabloypunto | Tono, estructura de emails, reglas de SendFox API |
| Lentejo | Automatizaciones | Flujos de trabajo, integraciones, manejo de errores |
| Remy | Investigación | Fuentes permitidas, formato de informes, citas |
| Rafiki | Blog SEO | Keywords, estructura de posts, flujo de publicación |
El CLAUDE.md de Ariel, por ejemplo, incluye el template exacto de mis newsletters, el tono que uso (directo, sin buzzwords, primera persona), las restricciones (nunca mencionar precios sin confirmación) y el flujo completo para enviar una campaña con la API de SendFox.
El resultado: Ariel no necesita que le explique nada al arrancar cada sesión. Ya lo sabe todo.
Los errores más comunes que veo en CLAUDE.md
Llevo tiempo hablando con otros solopreneurs que usan Claude Code y hay patrones claros de errores:
Error 1: Escribirlo una vez y no actualizarlo nunca
CLAUDE.md es un documento vivo. Cuando el agente comete un error nuevo, es una señal de que falta una regla. Cuando cambias de stack o de estructura, el CLAUDE.md debe reflejarlo.
Yo reviso el mío cada dos semanas aproximadamente. No es mucho trabajo: 10-15 minutos para añadir lo que aprendí.
Error 2: Ser demasiado genérico
"Sé profesional y útil" no ayuda a nadie. Las instrucciones útiles son específicas y accionables: "Cuando generes código TypeScript, usa tipos explícitos siempre — nunca any. Cuando crees componentes React, usa arrow functions, no declaraciones de función."
Error 3: No documentar el contexto de negocio
Los agentes técnicos funcionan mejor cuando entienden para qué sirve el proyecto desde una perspectiva de negocio. No es lo mismo "esta es una web" que "esta web es el canal principal de adquisición de leads para mi academia — cada post debe tener CTA a la newsletter".
Error 4: Olvidarse de las restricciones de producción
El error más caro. Si no defines explícitamente "nunca hagas push a main sin mi confirmación" o "nunca borres datos de producción", el agente puede tomar decisiones destructivas de buena fe.
Error 5: Un CLAUDE.md demasiado largo
Hay un punto de rendimientos decrecientes. Si tu CLAUDE.md tiene 2.000 líneas, el agente va a tener dificultades para priorizar. Lo importante es que sea denso en valor, no en extensión. El mío tiene entre 150 y 300 líneas según el proyecto.
Cómo empezar tu primer CLAUDE.md desde cero
Si nunca has escrito uno, este es el proceso que recomiendo:
Paso 1: Describe el proyecto en 5 frases
Empieza simple. Qué es, para quién, con qué tecnología, cuál es el objetivo principal, cuáles son las restricciones más importantes.
Paso 2: Registra los errores que ya tuviste
Piensa en las últimas 5 veces que el agente hizo algo que no querías. Escribe una regla para cada una. Si nunca has tenido sesiones largas, empieza con las restricciones obvias: no hacer deploys sin confirmación, no borrar archivos, no cambiar código que no se ha pedido cambiar.
Paso 3: Documenta tu primer flujo de trabajo habitual
¿Cuál es la tarea que más repites con el agente? Escríbela como lista numerada. Incluye cada paso, cada comando, cada archivo que se toca.
Paso 4: Define el tono y el estilo
¿Quieres respuestas largas o cortas? ¿Con emojis o sin ellos? ¿En español o inglés? ¿Con justificaciones o directo al grano? Parece baladí pero define la experiencia de trabajo día a día.
Paso 5: Iterar
Empieza con 50 líneas. Después de una semana de trabajo, tendrás material suficiente para doblar eso. El mejor CLAUDE.md es el que se escribe en colaboración con el uso real.
El impacto real: cuánto cambia trabajar con un buen CLAUDE.md
Antes de tener CLAUDE.md bien trabajados, cada sesión con Claude Code empezaba igual: 10-15 minutos explicando el contexto, el proyecto, las convenciones, qué hacer y qué no hacer.
Ahora esos 10-15 minutos no existen. El agente arranca sabiendo todo lo que necesita saber.
Sobre un mes de trabajo con 4-5 sesiones diarias, eso suma entre 20 y 30 horas recuperadas. Solo por tener un archivo de texto bien escrito.
El otro cambio es la calidad de los resultados. Cuando el agente tiene contexto rico, sus propuestas son más relevantes, sus errores son menos frecuentes y sus soluciones encajan mejor con la arquitectura del proyecto. No porque el modelo sea más inteligente, sino porque tiene más información con la que razonar.
CLAUDE.md y el futuro de los agentes de IA
A medida que los agentes de IA se vuelven más autónomos, la capacidad de instruirlos de forma precisa y persistente se vuelve más valiosa, no menos.
CLAUDE.md es hoy un archivo de texto. En el futuro, los sistemas de instrucciones para agentes serán más sofisticados — bases de conocimiento estructuradas, grafos de reglas, memoria semántica persistente. Pero el principio es el mismo: los agentes rinden mejor cuando tienen instrucciones claras, contexto rico y restricciones bien definidas.
Aprender a escribir buenos CLAUDE.md es aprender a comunicarte con agentes de IA de forma efectiva. Y esa habilidad va a ser cada vez más valiosa.
Preguntas frecuentes sobre CLAUDE.md
¿Qué es el archivo CLAUDE.md?
CLAUDE.md es un archivo de texto en formato Markdown que Claude Code lee automáticamente al inicio de cada sesión. Funciona como un manual de instrucciones persistente: defines reglas, contexto, tono, restricciones y flujos de trabajo que el agente debe seguir siempre, sin que tengas que repetirlos cada vez.
¿Dónde se coloca el archivo CLAUDE.md?
Puedes tener un CLAUDE.md global en ~/.claude/CLAUDE.md (aplica a todos los proyectos) y uno por proyecto en la raíz del repositorio (aplica solo a ese proyecto). Claude Code los combina automáticamente, dando prioridad al del proyecto cuando hay conflicto.
¿Qué debo escribir en CLAUDE.md?
Lo más valioso es: el contexto del proyecto, las reglas de comportamiento del agente, el tono y estilo si genera contenido, restricciones técnicas, y flujos de trabajo habituales. Empieza simple y añade a medida que trabajas.
¿CLAUDE.md funciona sin Claude Code?
No. CLAUDE.md es específico de Claude Code (la CLI de Anthropic). Si usas la API directa o Claude.ai web, este archivo no tiene efecto. Es una funcionalidad exclusiva de Claude Code.
¿Cuánto afecta CLAUDE.md al rendimiento del agente?
De forma significativa. Un buen CLAUDE.md puede reducir a la mitad el tiempo que tardas en que el agente haga una tarea bien a la primera. Sin él, dedicas las primeras instrucciones de cada sesión a re-explicar el contexto.
¿Se puede tener un CLAUDE.md por agente?
Sí. Si tienes varios proyectos o agentes, cada uno tiene su propio CLAUDE.md con su contexto, reglas y personalidad. Así no se mezclan las instrucciones entre proyectos.
Conclusión: el archivo más importante de tu stack de IA
Si hay un solo cambio que recomendaría a cualquier solopreneur que empieza con Claude Code, es este: escribe un CLAUDE.md desde el día uno y mantenlo actualizado.
No es el cambio más espectacular. No es la herramienta más sofisticada. Pero tiene uno de los mejores retornos sobre el tiempo invertido de todo lo que he probado.
Un agente con un buen CLAUDE.md es un colaborador que sabe lo que hay que hacer. Un agente sin él es un asistente nuevo al que tienes que explicar todo de cero cada mañana.
¿Ya tienes el tuyo? Si estás empezando, los pasos que te he dado arriba son suficientes para tener una primera versión útil en menos de una hora.
Si quieres ver cómo uso Claude Code con mis agentes en el día a día, me paso por mi newsletter todos los jueves contando exactamente eso: qué construí, qué funcionó y qué cambié.