Guía completa de CLAUDE.md: cómo dar contexto a Claude Code sobre tu proyecto

Si usas Claude Code para trabajar en tus proyectos, hay un fichero que marca la diferencia entre tener que explicar lo mismo en cada sesión o que Claude entienda tu proyecto desde el primer momento: CLAUDE.md.

Qué es CLAUDE.md

CLAUDE.md es un fichero Markdown que se coloca en la raíz de tu proyecto (o en otros lugares, como veremos) y que Claude Code lee automáticamente al inicio de cada sesión. Funciona como un manual de instrucciones persistente: le dice a Claude cómo está organizado tu proyecto, qué comandos usar, qué convenciones seguir y qué errores evitar.

Piensa en él como el onboarding que le harías a un compañero nuevo, pero escrito una sola vez y reutilizado en cada conversación.

Por qué es importante

Sin CLAUDE.md, cada sesión con Claude Code empieza de cero. Le tienes que explicar que usas Go, que los tests se lanzan con go test ./..., que los errores se wrappean con contexto, que el proyecto no tiene base de datos... Con CLAUDE.md, todo eso ya está cargado en contexto antes de que escribas tu primera pregunta.

Las ventajas concretas:

• Persistencia: las instrucciones sobreviven entre sesiones.
• Consistencia: todo el equipo comparte las mismas reglas si el fichero está en el repositorio.
• Ahorro de tokens: no repites las mismas explicaciones una y otra vez.
• Mejor calidad de respuestas: Claude toma decisiones más acertadas cuando conoce el contexto.

Dónde colocarlo

CLAUDE.md puede vivir en varios sitios, cada uno con un alcance diferente. Los más específicos tienen precedencia sobre los más generales:

Cuando arranca una sesión, Claude recorre el árbol de directorios hacia arriba buscando ficheros CLAUDE.md y los concatena todos. Los de subdirectorios se cargan bajo demanda cuando Claude lee ficheros en esas carpetas.

CLAUDE.local.md es para preferencias personales que no quieres commitear: URLs de sandbox, datos de prueba, atajos de tu workflow.

Qué incluir

Sí incluir

• Comandos de build, test y despliegue: los que Claude no puede adivinar.
• Convenciones de código que se desvíen del estándar del lenguaje.
• Instrucciones de testing: frameworks, cómo lanzar tests, qué evitar.
• Arquitectura del proyecto: decisiones que no son evidentes leyendo el código.
• Variables de entorno necesarias (sin sus valores reales).
• Gotchas: cosas no obvias que pueden hacer perder el tiempo.

No incluir

• Secretos: ni API keys, ni tokens, ni contraseñas. Nunca.
• Convenciones estándar que Claude ya conoce (no necesitas decirle que en Go las funciones exportadas empiezan en mayúscula).
• Documentación extensa: mejor enlazar a los docs.
• Descripciones fichero a fichero: Claude puede leer el código.
• Información que cambia constantemente: se queda desactualizada y confunde.

Estructura recomendada

Un buen CLAUDE.md no debería superar las 200 líneas. Si se pasa, pierde efectividad porque diluye la atención de Claude. Aquí va una estructura que funciona:

# CLAUDE.md

Instrucciones para Claude Code al trabajar en este proyecto.

## Sobre el proyecto

Descripción breve: qué es, qué stack usa, qué problema resuelve.

## Comandos frecuentes

- Build: `go build ./cmd/server`
- Tests: `go test ./...`
- Lint: `golangci-lint run`
- Dev: `air`

## Dependencias

Tabla o lista de las dependencias principales y para qué sirve cada una.
Solo las que no sean evidentes.

## Convenciones de código

- Idioma del código: inglés.
- Idioma de commits: español.
- Usar `slog` para logging.
- Errores: siempre hacer wrap con contexto.

## Arquitectura

Las decisiones importantes que Claude necesita conocer:
- Sin base de datos, los posts son ficheros Markdown.
- File watcher con fsnotify para recarga en caliente.
- Patrón handler -> service -> content loader.

## Estructura de directorios

Solo si no es la estándar del framework/lenguaje.

## Cosas a evitar

Lo que NO hay que hacer. Esto es especialmente útil:
- No usar `panic` fuera de `init()`.
- No añadir dependencias sin justificación.
- No hacer commits directos a main.

Sé específico

La diferencia entre un CLAUDE.md útil y uno inútil está en la especificidad:

Funciones avanzadas

Importar otros ficheros con @

Puedes referenciar ficheros externos para no duplicar información:

Consulta @README.md para la visión general del proyecto.
Consulta @docs/api.md para la documentación del API.

Directorio .claude/rules/

Para proyectos grandes, puedes organizar las instrucciones en ficheros separados por tema:

.claude/
├── CLAUDE.md
└── rules/
    ├── code-style.md
    ├── testing.md
    └── security.md

Cada fichero se carga automáticamente. Además, puedes limitar reglas a ficheros concretos con frontmatter YAML:

---
paths:
  - "internal/handler/**/*.go"
---

# Reglas para handlers

- Los handlers devuelven error, no llaman a http.Error directamente.
- Usar AppError para errores con código HTTP.

Generar un CLAUDE.md inicial con /init

Si partes de cero, ejecuta /init en la raíz de tu proyecto. Claude Code analizará la estructura, detectará el sistema de build, los frameworks y los patrones, y generará un CLAUDE.md base que puedes refinar.

CLAUDE.md vs Auto Memory

Claude Code tiene dos mecanismos de persistencia que se complementan:

No compiten: CLAUDE.md define las reglas del juego, Auto Memory recuerda las jugadas.

Errores comunes

Claude no sigue mis instrucciones:

• Verifica que el fichero se carga ejecutando /memory.
• Sé más específico: las instrucciones vagas se ignoran.
• Busca contradicciones entre ficheros si tienes varios.
• Poda si supera las 200 líneas.

El fichero es demasiado largo:

• Mueve el detalle a ficheros separados con @path.
• Usa .claude/rules/ para organizar por tema.
• Elimina todo lo que Claude puede deducir leyendo el código.

Las instrucciones desaparecen tras /compact:

• CLAUDE.md sobrevive a la compactación, eso no es el problema.
• Si una instrucción desapareció, solo estaba en la conversación. Añádela al fichero.

Mantenimiento

Trata CLAUDE.md como código:

1. Revísalo periódicamente, especialmente tras cambios grandes en el proyecto.
2. Elimina lo que ya no aplique.
3. Añade los patrones nuevos que surjan.
4. Haz PR de los cambios para que el equipo los revise.

Un CLAUDE.md desactualizado es peor que no tener ninguno, porque Claude tomará decisiones basándose en información incorrecta.

Conclusión

CLAUDE.md es el fichero más rentable que puedes añadir a tu proyecto si trabajas con Claude Code. Unas pocas líneas bien escritas ahorran horas de repetición y mejoran drásticamente la calidad de las respuestas. Empieza con /init, refina con lo que sabes de tu proyecto, y mantelo vivo.