Si ya has dado tus primeros pasos con Claude Code, habrás comprobado que la calidad de las respuestas no depende solo del prompt del momento. También influye, y mucho, la información de contexto que le das al asistente sobre tu proyecto. En ese terreno, CLAUDE.md es una de las piezas más valiosas del flujo de trabajo.
No se trata de escribir un manual interminable ni de volcar toda la documentación del repositorio. Un buen CLAUDE.md funciona como un mapa práctico: orienta a Claude Code sobre cómo trabajar en tu proyecto, qué prioridades seguir y qué convenciones respetar. Si todavía no tienes claro el papel de este archivo, te conviene repasar antes qué es CLAUDE.md y para qué sirve en Claude Code y, si quieres empezar desde cero, cómo crear un archivo CLAUDE.md para tu proyecto.
Qué debe aportar un buen claude.md
La regla de oro es simple: debe reducir ambigüedad. Claude Code ya entiende bastante bien el contexto técnico, pero no conoce las decisiones internas de tu equipo. Por eso, el archivo debe responder a preguntas como: ¿qué arquitectura usa el proyecto?, ¿cuáles son los comandos habituales?, ¿qué carpeta contiene la lógica principal?, ¿qué está prohibido tocar sin permiso?
Un buen CLAUDE.md no pretende explicar todo el código. Su misión es acelerar la comprensión del proyecto y evitar errores repetitivos. Piensa en él como una guía operativa para agentes de IA, no como una wiki general del repositorio.
El enfoque correcto: utilidad antes que exhaustividad
Es tentador añadir demasiada información: historia del producto, decisiones de negocio, todo el árbol de carpetas o incluso documentación duplicada. Eso suele empeorar la experiencia. Claude Code funciona mejor cuando encuentra instrucciones claras, cortas y accionables.
De hecho, este enfoque encaja muy bien con la lógica que ya viste al aprender cómo iniciar tu primer proyecto con Claude Code y con los flujos que se despliegan tras usar los comandos slash de Claude Code. El archivo no sustituye al prompt ni a los comandos: los complementa.
Estructura recomendada para claude.md
No existe una plantilla universal, pero sí una estructura que suele funcionar muy bien en proyectos reales. Lo importante es que el archivo sea escaneable, mantenga una jerarquía lógica y permita encontrar rápido cada tipo de instrucción.
# CLAUDE.md
## Descripción del proyecto
Breve resumen de qué hace la aplicación y cuál es su objetivo principal.
## Estructura del repositorio
- `src/`: código fuente principal
- `tests/`: pruebas automatizadas
- `docs/`: documentación de apoyo
## Comandos frecuentes
- Instalar dependencias: `npm install`
- Ejecutar en desarrollo: `npm run dev`
- Ejecutar tests: `npm test`
## Convenciones del código
- Usar nombres descriptivos en inglés
- Mantener funciones pequeñas y reutilizables
- No introducir dependencias nuevas sin justificarlo
## Reglas importantes
- No modificar archivos de configuración sin confirmarlo
- No tocar migraciones antiguas salvo que se indique
- Priorizar soluciones compatibles con la arquitectura actual
## Notas para Claude Code
- Si falta contexto, pedir aclaración antes de actuar
- Antes de editar, revisar los archivos relacionados
- Si hay varias opciones, proponer la más seguraEste es solo un ejemplo base. En proyectos React, backend, monorrepos o aplicaciones con CI/CD, la estructura puede variar. Si utilizas Claude Code desde la terminal en el día a día, te resultará útil recordar los hábitos aprendidos en cómo usar Claude Code desde la terminal.
Qué información merece estar dentro
Hay ciertos bloques de información que sí aportan valor de forma consistente. Uno de los más importantes es la arquitectura del proyecto: frameworks, capas principales, rutas críticas y cualquier patrón que el asistente deba respetar.
También conviene incluir los comandos canónicos del proyecto. No basta con decir “usa el gestor habitual”; Claude Code responde mejor si conoce el comando exacto para levantar la app, ejecutar tests o generar build. Eso reduce fricción y evita suposiciones innecesarias.
Convenciones de estilo y decisiones repetitivas
Si tu equipo sigue reglas específicas de formato, linting o estructura de módulos, anótalas. Por ejemplo: si todo el código debe seguir una nomenclatura concreta, si se prefieren hooks sobre clases o si ciertos directorios son inmutables, inclúyelo.
Estas instrucciones son especialmente valiosas cuando trabajas con editor integrado. En ese caso, el contexto del archivo se complementa muy bien con flujos como los de cómo usar Claude Code con VS Code, donde el asistente puede interactuar mejor con el entorno de desarrollo.
Qué no deberías poner en claude.md
Tan importante como saber qué incluir es saber qué evitar. El error más común es convertir el archivo en un contenedor de información irrelevante o demasiado cambiante. Si algo cambia cada semana, probablemente no sea buena idea dejarlo aquí salvo que sea crítico para el trabajo de la IA.
Evita también incluir secretos, tokens, credenciales, claves API o cualquier dato sensible. CLAUDE.md no es un almacén seguro; es un archivo de contexto dentro del repositorio. Aunque esté ignorado en parte del flujo, no debes tratarlo como bóveda de secretos.
Reduce redundancia y evita contradicciones
Otro problema habitual es repetir documentos ya existentes. Si tu proyecto tiene README, CONTRIBUTING o guías internas, el CLAUDE.md debe sintetizar, no duplicar. Si copias contenido sin filtrar, aumentas el riesgo de contradicciones entre versiones.
También conviene evitar instrucciones demasiado rígidas. Frases como “haz siempre X” pueden bloquear soluciones válidas. Es mejor usar formulaciones orientadas a la preferencia, por ejemplo: “prioriza X salvo que el cambio justifique otra cosa”.
cómo escribir instrucciones que Claude Code entienda mejor
La claridad gana a la sofisticación. Es preferible escribir instrucciones breves, directas y verificables que párrafos largos llenos de matices. Un buen patrón es usar verbos de acción y reglas concretas: “revisar”, “confirmar”, “no modificar”, “priorizar”, “preguntar si falta contexto”.
## Notas operativas
- Revisar primero los archivos relacionados antes de editar.
- Si una tarea afecta a varias capas, explicar el impacto antes de cambiar nada.
- No asumir nombres de funciones o rutas si no aparecen en el proyecto.
- Cuando haya varias soluciones posibles, elegir la menos invasiva.Este tipo de redacción ayuda a Claude Code a comportarse de forma coherente entre sesiones. Además, mejora la colaboración humana porque deja claras las reglas del juego para cualquier miembro del equipo que use el archivo.
Cómo mantenerlo útil con el tiempo
Un CLAUDE.md bueno no es el más largo, sino el más actualizado. Debes revisarlo cuando cambie la arquitectura, se añadan comandos nuevos o aparezcan normas importantes de desarrollo. Si no lo actualizas, el archivo pierde valor muy rápido.
Una buena práctica es revisarlo junto con los cambios relevantes del proyecto, igual que actualizarías la documentación técnica o los scripts de automatización. Si estás organizando mejor tu flujo de trabajo con AI coding assistants, puede resultarte útil complementar este artículo con cómo programar con Claude Code paso a paso.
Versión corta, fácil de mantener
En proyectos pequeños, un CLAUDE.md de una o dos pantallas suele ser suficiente. En sistemas más grandes, puedes dividirlo por secciones funcionales, pero siempre con una lógica de lectura rápida. Si se vuelve demasiado extenso, perderá la cualidad más importante: servir como referencia inmediata.
Recuerda que Claude Code aprovecha mejor un contexto nítido que un archivo saturado. En términos prácticos, un documento breve y preciso suele generar mejores resultados que uno largo y difuso.
Ejemplo de enfoque equilibrado
Imagina un proyecto web con frontend en React, API en Node y varios scripts de mantenimiento. Un buen CLAUDE.md podría señalar cuál es la carpeta principal de cada módulo, cómo arrancar el entorno local, qué comandos usar para pruebas y qué áreas no deben tocarse sin revisión humana.
Con eso ya le das a la IA suficiente contexto para actuar con seguridad. No necesita conocer toda la historia del equipo ni cada detalle del roadmap. Le basta con entender el terreno en el que se mueve y las reglas que debe respetar.
Conclusión
Escribir un buen CLAUDE.md para Claude Code consiste en equilibrar tres cosas: claridad, relevancia y mantenimiento. Si el archivo explica cómo funciona el proyecto, qué se espera del asistente y qué límites no debe cruzar, verás mejoras reales en calidad y consistencia.
Piensa en él como una guía de comportamiento para la IA dentro de tu repositorio. Cuanto más preciso y útil sea, menos tiempo perderás corrigiendo supuestos y más rápido avanzarás en desarrollo asistido.
Fuentes y lecturas recomendadas
Documentación oficial de Anthropic
MDN Web Docs para buenas prácticas técnicas de documentación
Deja una respuesta