Escribiendo un buen CLAUDE.md
En este post vamos a explicar como escribir un buen archivo CLAUDE.md (o AGENTS.md) para agentes de código como Claude Code, OpenCode, Zed o Cursor, con el objetivo de “onboardear” al modelo a tu código base en cada sesión. Los LLMs son esencialmente funciones sin estado que no recuerdan nada de tu repositorio salvo lo que les envías en el contexto de cada conversación, entonces este archivo les da el "contexto" necesario para cada consulta o pregunta que hagas.
Rol de CLAUDE.md
CLAUDE.md es el archivo que siempre se incluye en todas las conversaciones con el agente, por lo que sirve para explicar el QUÉ (tecnologías, stack, estructura del proyecto), el POR QUÉ (propósito del proyecto y de cada parte) y el CÓMO (forma de trabajar, comandos de build, tests, etc.). No conviene meter todos los comandos posibles ni demasiados detalles, porque eso empeora los resultados. "Menos es mas".
Por qué a veces se ignora
Claude a veces ignora parte de CLAUDE.md, porque el harness introduce un recordatorio de sistema diciendo que solo debe usar ese contexto si es realmente relevante para la tarea. Cuanta más información no universalmente aplicable metas en CLAUDE.md, más probable es que el modelo ignore todo el bloque, entonces por eso es importante ser conciso.
Principio “menos instrucciones es más”
Los LLMs solo pueden seguir de forma confiable un número limitado de instrucciones, y a medida que ese número crece, la calidad de lo que devuelve baja de forma bastante uniforme. Como el prompt de sistema de Claude Code ya incluye muchas instrucciones,** es mejor que CLAUDE.md tenga pocas reglas y solo las que sean realmente universales para tu flujo de trabajo.**
Longitud y relevancia del archivo
El modelo rinde mejor cuando el contexto está lleno de información relevante (ejemplos, archivos relacionados, resultados de herramientas) en lugar de ruido o reglas genéricas. Es mejor que CLAUDE.md sea relativamente corto (por ejemplo, menos de unas 300 líneas, idealmente bastante menos) y centrado en lo que siempre aplica.
Divulgación progresiva
Para proyectos grandes, es mejor usar “Divulgación Progresiva”: mantener instrucciones específicas de tareas en otros archivos markdown descriptivos (por ejemplo building_the_project.md, running_tests.md, etc.) y solo linkearlos desde CLAUDE.md. En vez de copiar código o instrucciones extensas, se aconseja apuntar con referencias file:line a las fuentes autorizadas dentro del repo.
No traten al modelo como linter
NO USEN CLAUDE.md para meter guías de estilo, solo estan usando un LLM como un linter caro y lento. Usen linters y formateadores y, si quieren, hooks que ejecuten el linter y despues le pasen al modelo los errores para que los arregle.
Evitar /init y generación automática
No conviene usar comandos de autogeneración de CLAUDE.md, porque este archivo afecta todas las fases del flujo de trabajo y todos los artefactos que se producen. Tomense un rato y armenlo a mano, con mucho cuidado, para definir bien el WHY/WHAT/HOW del proyecto, mantenerlo conciso, usar divulgación progresiva y apoyarse en linters y otras herramientas externas.
Links:
Comentarios Recientes
No hay comentarios, porque no dejás alguno?
Deja un comentario