Si ya has empezado a trabajar con Claude Code, seguramente te habrás dado cuenta de que el asistente puede adaptarse bastante bien a un proyecto, pero necesita contexto para hacerlo con precisión. Ahí es donde entra CLAUDE.md: un archivo de instrucciones pensado para guardar información útil sobre tu repositorio y guiar el comportamiento del modelo dentro de ese entorno.
En términos sencillos, CLAUDE.md funciona como una especie de “manual de proyecto” que Claude Code puede leer para entender reglas, preferencias y decisiones técnicas que deberían mantenerse en el tiempo. No es un sustituto de la documentación del equipo, sino una capa práctica para que la IA trabaje con menos ambigüedad y tome mejores decisiones al escribir, modificar o revisar código.
Para qué sirve realmente
La utilidad principal de CLAUDE.md es reducir fricción. En desarrollo de software, muchas tareas repetitivas no fallan por falta de capacidad del asistente, sino por falta de contexto: convenciones de estilo, estructura de carpetas, patrones arquitectónicos, comandos habituales o requisitos de despliegue. Con ese archivo, puedes centralizar esa información y hacer que Claude Code la tenga en cuenta desde el inicio.
Esto es especialmente valioso en proyectos con varias personas, porque evita que cada sesión empiece desde cero. También ayuda cuando trabajas en repositorios grandes o con reglas específicas, donde responder “como siempre lo hacemos aquí” ahorra tiempo y reduce errores.
Casos de uso comunes
CLAUDE.md suele usarse para indicar cosas como el framework principal, cómo ejecutar pruebas, qué carpetas no deben tocarse o qué estilo de código debe respetarse. También puede incluir pautas sobre nombres de variables, linters, formato de commits o decisiones de arquitectura que no conviene romper.
Por ejemplo, si en tu proyecto usas una estructura basada en módulos, o si tienes un flujo concreto para lanzar la aplicación localmente, Claude Code puede seguir esas reglas si están documentadas allí. Eso lo convierte en una herramienta muy útil para automatizar tareas sin perder coherencia con el proyecto.
Cómo se relaciona con el flujo de trabajo de Claude Code
Una de las ventajas de Claude Code es que no solo responde a una pregunta aislada, sino que puede trabajar sobre un proyecto completo y mantener el contexto de la sesión. Si quieres entender mejor ese comportamiento general, te recomendamos repasar primero cómo configurar Claude Code y comenzar a programar, porque CLAUDE.md encaja precisamente en ese flujo de configuración inicial.
También tiene sentido estudiarlo junto con cómo iniciar tu primer proyecto con Claude Code y cómo usar Claude Code desde la terminal, ya que en esos escenarios es donde más se nota la diferencia entre trabajar “a ciegas” y trabajar con reglas persistentes.
Qué tipo de información conviene incluir
No hace falta convertir CLAUDE.md en una enciclopedia. Lo más útil es incluir instrucciones accionables, breves y estables. Piensa en todo lo que un nuevo desarrollador necesitaría saber para no romper el proyecto en sus primeras modificaciones.
Entre los elementos más habituales suelen estar:
– nombre y objetivo del proyecto
– estructura de directorios importante
– comandos para instalar dependencias, compilar y probar
– convenciones de estilo y formato
– restricciones sobre archivos sensibles
– notas sobre arquitectura, módulos o patrones de diseño
Dónde encaja dentro del repositorio
En la práctica, CLAUDE.md suele vivir en la raíz del proyecto o en un nivel relevante del árbol de directorios para que Claude Code lo encuentre con facilidad. La idea es que actúe como referencia cercana al código sobre el que estás trabajando, no como un documento perdido en otra carpeta.
Esto lo diferencia de una wiki externa o de un documento de onboarding: aquí la prioridad no es solo informar a humanos, sino también aportar contexto operacional a un asistente que va a generar o modificar código. Por eso, lo ideal es mantenerlo sincronizado con la realidad del repositorio.
Un ejemplo práctico
Imagina un proyecto frontend con React, TypeScript y pruebas con Vitest. En CLAUDE.md podrías dejar claro qué comando se usa para levantar el entorno, qué alias importa usar, cómo se nombran los componentes y qué patrón sigue el código para manejar estados o efectos.
# CLAUDE.md
# Instrucciones para Claude Code en este repositorio
## Convenciones generales
- Usa TypeScript en todos los nuevos archivos.
- Mantén componentes pequeños y reutilizables.
- Sigue la estructura de carpetas existente.
## Comandos útiles
- Instalar dependencias: npm install
- Desarrollo local: npm run dev
- Ejecutar tests: npm run test
- Lint: npm run lint
## Reglas importantes
- No modificar archivos de configuración sin confirmarlo.
- No crear dependencias nuevas si ya existe una solución en el proyecto.
- Documentar cambios relevantes antes de cerrar tareas.Este tipo de archivo no reemplaza la revisión humana, pero sí reduce decisiones improvisadas y ayuda a que los cambios sean más consistentes con el resto del sistema.
Buenas prácticas para escribirlo bien
La clave no es escribir mucho, sino escribir lo justo y mantenerlo actualizado. Un CLAUDE.md desordenado o lleno de contradicciones puede generar más confusión que ayuda. Conviene evitar instrucciones demasiado genéricas, como “escribe buen código”, porque no aportan señales concretas al modelo.
En su lugar, es mejor definir reglas que puedan ejecutarse o verificarse. Por ejemplo, indicar el comando exacto para pruebas, la ruta de los archivos de configuración o la forma habitual de nombrar componentes y servicios. Cuanto más claro sea el contexto, más útil será la respuesta de Claude Code.
Errores frecuentes
Uno de los fallos más comunes es copiar instrucciones desactualizadas. Si el proyecto cambió de gestor de paquetes, de framework o de pipeline, el archivo también debe cambiar. Otro error frecuente es incluir demasiadas excepciones o notas personales, lo que termina restando claridad.
También conviene no mezclar documentación de usuario final con instrucciones para el asistente. CLAUDE.md tiene una función operativa muy concreta: ayudar a Claude Code a trabajar mejor dentro del proyecto. Si se mantiene ese foco, funciona mucho mejor.
Relación con los comandos slash y con /init
Si ya has explorado cómo usar los comandos slash de Claude Code, verás que CLAUDE.md complementa muy bien ese enfoque. Los comandos slash sirven para pedir acciones concretas en una sesión; CLAUDE.md, en cambio, aporta contexto persistente para que esas acciones se ejecuten con criterio.
Algo parecido ocurre con /init para configurar un proyecto en Claude Code. Ese comando ayuda a arrancar el contexto inicial, mientras que CLAUDE.md puede refinanarlo y mantenerlo vivo a medida que el proyecto evoluciona.
Por qué es tan útil en proyectos reales
En un entorno real, el valor de CLAUDE.md no está solo en ahorrar tiempo: está en reducir desviaciones. Cuando un asistente entiende el contexto del repositorio, es menos probable que proponga cambios incompatibles con la base de código o que utilice soluciones fuera del estándar del equipo.
Eso repercute en tareas cotidianas como refactorizar un componente, añadir pruebas, arreglar un bug o preparar una revisión. El archivo actúa como memoria de proyecto, algo especialmente útil cuando hay muchas sesiones separadas, colaboración entre varias personas o mantenimiento de código heredado.
Conclusión
CLAUDE.md es una pieza pequeña, pero muy poderosa dentro del ecosistema de Claude Code. Sirve para convertir instrucciones dispersas en contexto reutilizable, y eso mejora tanto la calidad de las respuestas como la coherencia del trabajo sobre el repositorio.
Si quieres sacar más partido a Claude Code, piensa en CLAUDE.md como el puente entre la documentación del proyecto y la ejecución asistida por IA. Bien redactado, puede marcar una diferencia notable en productividad, consistencia y control técnico.
Fuentes y lecturas recomendadas
Documentación oficial de Anthropic
Noticias y actualidad de IA en OpenAI
Deja una respuesta