Si ya has dado tus primeros pasos con Claude Code, seguramente habrás notado que el siguiente reto no es “hacer que funcione”, sino hacer que funcione como tú quieres. Ahí es donde entra CLAUDE.md: un archivo de contexto pensado para centralizar instrucciones, decisiones técnicas y reglas de trabajo dentro de tu repositorio.
En artículos anteriores ya vimos qué es CLAUDE.md y para qué sirve en Claude Code, así que aquí vamos un paso más allá: cómo crearlo bien, qué incluir y cómo evitar que se convierta en un documento caótico e inútil.
Por qué merece la pena crear este archivo
Un archivo CLAUDE.md bien estructurado reduce fricción. En la práctica, ayuda a que la herramienta entienda mejor el proyecto, respete tus convenciones y no te haga perder tiempo repitiendo instrucciones en cada sesión.
Piensa en él como una combinación de guía de estilo, memoria operativa y manual de arranque rápido. No sustituye a la documentación formal del proyecto, pero sí complementa cosas como el README, los issues o la documentación interna.
Además, cuando trabajas en equipo, este archivo aporta consistencia. Todos parten del mismo contexto y es más fácil mantener criterios homogéneos en nombres de módulos, estructura del repositorio, flujo de pruebas o convenciones de commits.
Qué debe contener un buen CLAUDE.md
No existe una única plantilla universal. La clave está en incluir solo la información que realmente ayuda al asistente a tomar mejores decisiones dentro de tu proyecto. Si ya has leído cómo iniciar tu primer proyecto con Claude Code, esta parte encaja especialmente bien con la fase de configuración inicial.
1. Descripción breve del proyecto
Empieza con unas líneas que expliquen qué hace la aplicación, el stack principal y el objetivo del repositorio. No hace falta redactar un README completo; basta con dar contexto suficiente para entender si se trata de una API, una SPA, una librería o una app full stack.
2. Estructura del repositorio
Indica dónde viven los componentes importantes: código fuente, tests, configuración, assets o scripts. Esto es útil para orientar a Claude cuando tenga que localizar una funcionalidad concreta o respetar una carpeta determinada.
3. Convenciones de código
Aquí puedes documentar reglas como estilo de indentación, nomenclatura de variables, patrón de componentes, organización por dominio o preferencias de linting. Cuanto más claro sea este apartado, menos “suposiciones” hará la herramienta.
4. Comandos importantes del proyecto
Incluye los comandos más usados para instalar dependencias, ejecutar tests, lanzar el entorno de desarrollo o generar builds. Si trabajas con sistemas modernos de frontend o backend, este bloque ahorra mucho tiempo y reduce errores por ejecutar tareas equivocadas.
5. Restricciones y buenas prácticas
Si hay carpetas sensibles, módulos que no deben tocarse o decisiones arquitectónicas que deban respetarse, déjalo por escrito. Por ejemplo: no modificar migraciones antiguas, no introducir nuevas dependencias sin validación o no cambiar la API pública sin aprobación.
Estructura recomendada para empezar
La mejor forma de crear un CLAUDE.md es empezar por lo esencial y ampliarlo con el tiempo. No intentes documentarlo todo desde el primer minuto. Un archivo demasiado largo suele perder utilidad porque nadie lo mantiene al día.
Una estructura básica podría incluir estas secciones:
# CLAUDE.md
## descripción del proyecto
Breve explicación del objetivo del repositorio y tecnología principal.
## estructura
- src/: código principal
- tests/: pruebas automáticas
- docs/: documentación adicional
## comandos frecuentes
- npm install
- npm run dev
- npm test
## convenciones
- Usar TypeScript en nuevos módulos
- Mantener nombres descriptivos
- Seguir el patrón de arquitectura existente
## notas importantes
- No alterar la API pública sin revisar compatibilidad
- Revisar el lint antes de finalizar cambios
Este ejemplo es intencionalmente simple. La idea no es imponer una plantilla rígida, sino crear una base clara, legible y fácil de extender. En proyectos más complejos, puedes añadir secciones para entornos, variables, despliegue, revisión de pull requests o flujos de pruebas específicos.
Dónde colocar el archivo
En la mayoría de los casos, CLAUDE.md se coloca en la raíz del proyecto para que sea fácil de encontrar y aplicar al contexto general del repositorio. Si el proyecto tiene varias partes independientes, también puede tener sentido usar archivos adicionales en subdirectorios, siempre que tu flujo de trabajo lo justifique.
La regla práctica es sencilla: el archivo debe estar donde aporte más claridad. Si lo escondes demasiado, pierde valor; si duplicas información sin control, acabará desactualizado.
Si quieres entender mejor cómo interactúa este archivo con el proceso de arranque inicial, te recomendamos revisar también cómo usar /init para configurar un proyecto en Claude Code, porque ambos enfoques se complementan muy bien.
Qué errores evitar al crearlo
Escribir demasiado contexto irrelevante
Un error habitual es convertir CLAUDE.md en un volcado de documentación general. Eso no ayuda al asistente ni al equipo. Mantén el foco en lo que influye directamente en el desarrollo: estructura, normas, dependencias, comandos y restricciones.
Copiar y pegar información obsoleta
Si el proyecto cambia, el archivo también debe cambiar. Una instrucción antigua puede ser peor que no tener ninguna, porque genera decisiones incorrectas. Revisa el contenido cada vez que actualices el stack o refactorices una parte importante.
Mezclar documentación pública con instrucciones internas
El README explica el proyecto al mundo. CLAUDE.md explica cómo trabajar bien dentro del proyecto. Aunque ambos puedan compartir algunas ideas, conviene no mezclar objetivos ni tono. Así se mantiene cada documento útil en su propio contexto.
Cómo mantenerlo útil a largo plazo
La mejor estrategia es tratar CLAUDE.md como un archivo vivo. No hace falta revisarlo a diario, pero sí cada vez que cambien procesos importantes: nuevos scripts, nuevos estándares, nueva arquitectura o cambios en el flujo de pruebas.
También es buena idea pedir al equipo que lo use como referencia real. Si nadie lo consulta o nadie lo actualiza, acabará siendo ruido. En cambio, cuando se integra en el flujo de trabajo, se convierte en un pequeño multiplicador de productividad.
En proyectos con mucha automatización, este archivo puede ser especialmente valioso para documentar cómo debe actuar la IA ante tareas repetitivas: generación de componentes, refactorizaciones, revisiones superficiales o ejecución de tests. No reemplaza el criterio humano, pero sí lo apoya.
Relación con el resto del flujo de claude code
Crear CLAUDE.md no es un paso aislado. Forma parte de una cadena más amplia: instalar correctamente la herramienta, configurar el entorno, entender la terminal, trabajar con comandos y preparar el proyecto para que la IA tenga contexto suficiente.
Si todavía estás construyendo esa base, te vendrá bien repasar cómo configurar Claude Code y comenzar a programar y cómo usar Claude Code desde la terminal. Son piezas que, combinadas con un buen CLAUDE.md, mejoran mucho la experiencia.
En otras palabras: cuanto mejor sea tu documentación operativa, menos dependerás de repetir instrucciones manuales y más fluido será el trabajo asistido por IA.
Conclusión
Crear un archivo CLAUDE.md no consiste en escribir mucho, sino en escribir bien. Debe ser breve, preciso y útil para que la herramienta entienda el proyecto, respete tus decisiones y te ayude a trabajar con menos fricción.
Si lo preparas con criterio, este archivo se convierte en una base sólida para escalar tu flujo de desarrollo con Claude Code. Y lo mejor es que no necesitas complicarlo: con unas pocas secciones bien pensadas puedes lograr una mejora notable desde el primer día.
Fuentes y lecturas recomendadas
- Documentación oficial de Anthropic
- Novedades y anuncios de Anthropic
- MDN Web Docs: referencia técnica y buenas prácticas
Deja una respuesta