Cómo escribir un buen Claude.md

• Un LLM es una función sin estado, por lo que CLAUDE.md funciona como el documento clave para presentarle el codebase a Claude en cada sesión
• El archivo debe incluir de forma concisa el WHAT (estructura), WHY (propósito) y HOW (forma de funcionamiento) del proyecto; un exceso innecesario de comandos termina degradando el rendimiento
• Claude puede ignorar el contenido de CLAUDE.md si, según las instrucciones del mensaje de sistema, considera que tiene poca relevancia
• Un archivo efectivo solo incluye información breve y de aplicación general; las instrucciones detalladas deben separarse en documentos aparte y administrarse con un enfoque de Progressive Disclosure
• CLAUDE.md es el punto de mayor impacto en el agent harness, así que debe redactarse manualmente con cuidado en lugar de generarse automáticamente

---

La naturaleza sin estado de los LLM y el rol de CLAUDE.md

• Los LLM usan pesos fijos en el momento de la inferencia y no mantienen aprendizaje ni memoria entre sesiones
  • Por eso, si el modelo debe entender un codebase, toda la información tiene que proporcionarse mediante tokens de entrada
• Los agentes de programación como Claude Code necesitan gestionar la memoria de forma explícita, y CLAUDE.md es el único archivo que se incluye automáticamente en todas las conversaciones
• Como resultado, estas tres cosas son indispensables
  1. Al comenzar una sesión, Claude no sabe nada sobre el codebase
  2. En cada sesión hay que volver a proporcionarle la información necesaria
  3. El medio estándar para hacerlo es CLAUDE.md

Onboarding del codebase: WHAT, WHY, HOW

• CLAUDE.md cumple la función de documento de onboarding para ayudar a Claude a entender el proyecto
  • WHAT: ofrece un mapa del código, como stack tecnológico, estructura del proyecto y configuración del monorepo
  • WHY: explica el propósito y la función de cada componente
  • HOW: indica cómo realizar tareas reales como build, pruebas y typecheck
• Aun así, listar todos los comandos es ineficiente, por lo que solo debe incluirse la información mínima necesaria

Por qué Claude ignora CLAUDE.md

• Claude Code inserta en el mensaje del usuario un recordatorio del sistema como el siguiente

  IMPORTANT: this context may or may not be relevant...
  

  • Debido a esto, Claude ignora ese contexto si determina que no es relevante para la tarea actual
• Cuantas más instrucciones que no son de aplicación general haya en el archivo, mayor es la probabilidad de que se ignoren
• Se estima que Anthropic añadió esto porque, al ignorar instrucciones innecesarias, mejoró la calidad de los resultados

Principios para escribir un buen CLAUDE.md

Less (instructions) is more

• Un LLM puede seguir de forma estable alrededor de 150 a 200 instrucciones
  • Cuanto más pequeño es el modelo, más brusca es la caída de rendimiento, y resulta menos apto para tareas de varios pasos
• El prompt de sistema de Claude Code ya incluye unas 50 instrucciones
  • Por eso, en CLAUDE.md deben incluirse solo las instrucciones universales y esenciales, en la mínima cantidad posible
• A medida que aumenta el número de instrucciones, la calidad de ejecución de todas ellas se degrada de manera uniforme

Longitud del archivo y alcance de aplicación

• Los LLM funcionan mejor con contexto enfocado y altamente relevante
• Como CLAUDE.md se incluye en todas las sesiones, debe conservar solo información de aplicación general
• En general, se recomienda mantenerlo en menos de 300 líneas, y si es posible, aún más corto
  • El archivo de ejemplo de HumanLayer tiene menos de 60 líneas

Progressive Disclosure

• En proyectos grandes es difícil meter toda la información en un solo archivo, por lo que se recomienda el enfoque de Progressive Disclosure
  • Las instrucciones detalladas se separan en archivos Markdown dentro de la carpeta agent_docs/
  • Por ejemplo: building_the_project.md, running_tests.md, code_conventions.md, etc.
• En CLAUDE.md solo deben incluirse la lista y una breve descripción de esos archivos, junto con la instrucción para que Claude los lea cuando sea necesario
• En lugar de snippets de código, conviene usar referencias file:line para mantener la vigencia
• Esto es similar al concepto de Claude Skills, aunque está más enfocado en la gestión de instrucciones que en el uso de herramientas

Claude no es un linter

• Incluir lineamientos de estilo de código en CLAUDE.md es ineficiente
  • Los LLM son costosos y lentos, y además menos deterministas que un linter
• Las reglas de estilo se aprenden de forma natural a partir de los patrones del código existente, por lo que no hacen falta instrucciones separadas
• Para el formateo, conviene usar linters con autocorrección (como Biome) y pasarle a Claude solo el resultado de esa corrección
• Si hace falta, pueden usarse Stop Hook o Slash Command para automatizar formateo y validación

No a la generación automática

• No se recomienda usar el comando /init ni funciones de generación automática para crear CLAUDE.md
  • Esto se debe a que el archivo es un punto de alto apalancamiento que afecta todas las sesiones y todos los resultados
• Una sola línea de instrucción equivocada puede tener un efecto en cadena negativo sobre la calidad general del código
• Por eso, cada oración debe revisarse con cuidado y redactarse manualmente

Conclusión

• CLAUDE.md es un documento para hacer onboarding de Claude al codebase, y debe definir con claridad WHY, WHAT y HOW
• Las instrucciones deben minimizarse y solo debe incluirse contenido universal y conciso
• Mediante Progressive Disclosure, se debe proporcionar solo la información necesaria de forma gradual
• No uses Claude como linter; conviene combinar herramientas dedicadas y funciones de hooks/comandos
• En lugar de generarlo automáticamente, hay que redactarlo manualmente con cuidado para maximizar la calidad general del harness

[GN⁺]

Opiniones de Hacker News

• Claude a menudo tiende a ignorar las instrucciones de CLAUDE.md
  Cuanta más información no relacionada con la tarea específica haya en el archivo, menos probable es que Claude siga esas instrucciones
  Un amigo le pidió a Claude que lo llamara “Mr Tinkleberry”, y cuando Claude lo olvidaba, era evidente que estaba ignorando el archivo

• Yo he usado desde hace tiempo el enfoque de tabla de contenidos
  Separo las instrucciones por tarea en distintos archivos markdown, y en CLAUDE.md solo pongo la lista y una breve descripción
  Así, la ventana de contexto se mantiene limpia
  Mi archivo de ejemplo se puede ver aquí

  • Yo también probé ese método, pero los resultados fueron irregulares
    Claude casi nunca leía realmente los otros archivos de documentación

• Siento que si le doy demasiado contexto a Claude, la calidad más bien baja
  Por eso siempre mantengo dos versiones del código

  1. El código original sin comentarios ni espacios en blanco
  2. El código con comentarios
     Al LLM solo le doy la primera versión
     Creo que la clave es la proporción entre cómputo e información. La capacidad de cálculo es limitada
  • Yo tuve una experiencia parecida, pero meter el contenido repetitivo en el archivo de notas de Claude mejoró la eficiencia
    No hace falta ponerlo todo, pero incluir la información clave tuvo un ROI alto
    Claude funciona bien en proyectos comunes, pero con frameworks o herramientas nuevas se confunde con frecuencia
  • Dijiste que mantienes dos versiones del código; me da curiosidad cómo manejas esa consistencia
    Quisiera preguntar si usas un script que quite comentarios y espacios en blanco después de cada cambio
  • Creo que dentro de los archivos de documentación hay que mantener alta la densidad de información
  • Dijiste que no le das al LLM la versión con comentarios; me da curiosidad cómo implementas eso en la práctica
  • Al final, la atención es finita. Si metes demasiado contexto, el enfoque se dispersa

• En realidad, hay una forma de resolver esto sin una configuración tan compleja
  Es simplemente documentar el código con claridad
  Si escribes de forma concisa qué hace cada archivo, eso mismo funciona como prompt
  Basta con aprovechar activamente README.md
  Como los LLM ya fueron entrenados con información pública, no hace falta inventar nada nuevo

  • Pero al escribir documentación dirigida a la IA, hace falta un enfoque distinto al de la documentación para lectores humanos
    El consejo de simplemente “documenta bien el código” no encaja en este contexto
  • Yo también pienso que la comunidad de IA a veces reinventa la rueda innecesariamente
    README está bien, pero CLAUDE.md tiene un propósito distinto
    Por ejemplo, Claude/agents.md tiene una función que se inserta automáticamente en el contexto al acceder a cierto directorio
    En bases de código complejas, la gestión del contexto es mucho más importante
  • CLAUDE.md no es un simple documento, sino una forma de personalizar el prompt inicial del modelo
    Por eso, el consejo de “escribe bien el prompt” pasa por alto lo esencial
  • Por ejemplo, ¿dónde pondrías una regla como “las consultas a la base de datos siempre deben usar índices”?
    Si la pones en el README, al final termina cumpliendo el mismo papel que CLAUDE.md
    El propósito de CLAUDE.md es darle por adelantado la información clave para que Claude no tenga que releer todos los documentos cada vez
    Los humanos recuerdan, pero Claude olvida en cada tarea, así que hace falta una estructura que reduzca el re-onboarding

• Sinceramente, si hay que configurar tanta infraestructura de IA para esto, siento que mejor programo yo mismo

  • Pero la configuración relacionada con estilo se hace una sola vez y luego se puede reutilizar
    Yo separo las reglas comunes de las reglas específicas del proyecto
  • La configuración que menciona el artículo se hace en unas pocas horas
    No usar IA es simplemente una pérdida de productividad
  • De hecho, gran parte de la configuración inicial también se la puedes dejar al LLM
  • En realidad no requiere tanto esfuerzo. El problema es querer optimizar demasiado la herramienta
  • Lo importante es si el costo es recurrente o de una sola vez
    Si la configuración solo hace falta una vez, vale totalmente la pena invertir en ella
    Decir “qué flojera configurar eso” se parece a la excusa de quienes evitan configurar un depurador

• Yo simplemente copio el código necesario y lo pego en la ventana de conversación para usarlo como si estuviera charlando
  Hoy en día los modelos han mejorado mucho, así que incluso sin archivos .md dan resultados bastante decentes
  Puede que estos archivos den una ligera mejora, pero no creo que sean una magia de 100x en productividad

  • Pero ese es otro caso de uso
    Aquí se está hablando de cuando Claude hace por sí solo una implementación completa o corrige bugs
  • Mi experiencia es parecida. Una vez hice un CLAUDE.md, pero ya no lo uso
    Con darle el contexto necesario funciona bastante bien. Se siente un poco como bikeshedding
  • Aun así, si dejas organizada de antemano la lista de tablas o columnas de la base de datos, sí puedes reducir repeticiones

• Yo hago que Claude escriba CLAUDE.md por sí mismo
  Si le dices “README.md es para usuarios, CLAUDE.md es para ti”,
  también actualiza automáticamente instrucciones como “revisa siempre la documentación de la API”
  No hace falta conocer prompts mágicos si al final los resultados salen bien

  • Pero tengo dudas de si existe evidencia de que las instrucciones escritas por la propia IA sean mejores que las escritas por humanos
    No parece haber razón para que la IA sea la que mejor se haga prompt a sí misma