CLAUDE.md: cómo escribirlo bien (con ejemplo comentado)

El archivo CLAUDE.md es la forma de darle a Claude Code instrucciones que se mantienen de una sesión a otra: cómo compilar, cómo probar, qué convenciones seguir y qué no tocar. Claude lo lee al empezar cada sesión, así que no tienes que repetir lo mismo en cada conversación. En esta guía ves dónde va, cómo crearlo, una plantilla comentada línea por línea y los errores que hacen que Claude lo ignore.

Cómo se hizo esta guía: está redactada con ayuda de IA y contrastada con la documentación oficial de Claude Code (consultada el 12 de noviembre de 2026). La plantilla es un ejemplo ilustrativo, no el archivo de un proyecto real. Más detalles en cómo usamos la IA en este sitio.

Qué es CLAUDE.md y cuándo se lee

Es un archivo de texto en formato Markdown con instrucciones persistentes. Claude Code lo carga al inicio de cada sesión como contexto. Conviene entender una limitación: son indicaciones que guían el comportamiento, no una configuración que se haga cumplir. Si algo tiene que ejecutarse siempre sin excepción, la documentación recomienda usar un hook en lugar de una instrucción en CLAUDE.md.

Dónde colocar el archivo

Hay varios niveles. Claude recorre los directorios desde donde lo ejecutas hacia arriba y concatena todos los que encuentra; no se pisan unos a otros.

Nivel	Ubicación	Para qué sirve
Usuario	~/.claude/CLAUDE.md	Tus preferencias personales en todos los proyectos
Proyecto	./CLAUDE.md o ./.claude/CLAUDE.md	Instrucciones del equipo, se versiona con git
Local	./CLAUDE.local.md	Tus notas en este proyecto; añádelo a .gitignore
Subcarpetas	CLAUDE.md dentro de una carpeta	Se carga solo cuando Claude lee archivos de esa carpeta
Organización	Ruta del sistema (en Linux, /etc/claude-code/CLAUDE.md)	Políticas para todos los usuarios de una empresa

Cómo crearlo con /init

Dentro de tu proyecto abre Claude Code y ejecuta el comando de inicialización. Analiza el código y genera un primer CLAUDE.md con comandos de compilación, pruebas y convenciones. Si ya existe uno, propone mejoras en vez de sobrescribirlo.

claude
> /init

Trata ese resultado como un borrador: léelo, quita lo obvio y añade lo que solo tú sabes (por ejemplo, por qué una carpeta no se debe tocar).

Ejemplo de CLAUDE.md comentado

Esta plantilla es para un proyecto ficticio en Python con pruebas en pytest. Los comentarios de bloque en HTML (<!-- ... -->) se eliminan antes de enviar el archivo a Claude, de modo que puedes dejar notas de mantenimiento sin gastar contexto.

# Proyecto: gestor-de-tareas

<!-- Qué es y para quién: dos líneas bastan -->
API en Python (FastAPI) para gestionar tareas. Se despliega en un contenedor Docker.

## Comandos
- Instalar dependencias: `pip install -r requirements.txt`
- Ejecutar pruebas: `pytest -q`
- Ejecutar solo una prueba: `pytest -q tests/test_tareas.py::test_crear`
- Servidor local: `uvicorn app.main:app --reload`

## Convenciones
- Sangría de 4 espacios y tipos en todas las funciones públicas.
- Los nombres de funciones y variables van en español; los de clases, en inglés.
- Cada cambio de comportamiento lleva su prueba en `tests/`.

## Flujo de trabajo
- Antes de dar una tarea por terminada, ejecuta `pytest -q` y muestra el resultado.
- Haz cambios pequeños: un tema por commit, con mensaje en imperativo.

## No tocar
- `migrations/` se genera con Alembic; no edites esos archivos a mano.
- No agregues dependencias nuevas sin preguntar antes.

## Notas del proyecto
<!-- Decisiones que no se ven en el código -->
- La tabla `tareas` usa borrado lógico (campo `eliminada`); no hagas DELETE reales.

Fíjate en tres rasgos: cada instrucción se puede verificar (un comando, una carpeta concreta), no hay explicaciones largas y todo cabe en una pantalla.

Qué poner y qué dejar fuera

Sí conviene incluir

• Comandos exactos para instalar, probar y ejecutar.
• Convenciones que no se deducen leyendo el código.
• Carpetas o archivos que no deben modificarse, y por qué.
• Decisiones de diseño que sorprenderían a alguien nuevo en el proyecto.

Mejor dejarlo fuera

• Descripciones largas de la arquitectura que ya están en el README (puedes enlazarlas con una importación).
• Instrucciones vagas como «escribe código limpio» o «prueba tus cambios».
• Procedimientos de varios pasos: la documentación recomienda moverlos a una skill.

Regla práctica de la documentación: mantén el archivo por debajo de unas 200 líneas. Los archivos más largos consumen más contexto y reducen el grado de cumplimiento.

Importar otros archivos con @

Dentro de CLAUDE.md puedes referenciar otros archivos con @ruta. Las rutas relativas se resuelven desde el archivo que contiene la importación y se admiten hasta cuatro niveles. Importar sirve para organizar, no para ahorrar contexto: los archivos importados se cargan igualmente al iniciar.

Resumen del proyecto en @README.md y comandos de npm en @package.json.

## Flujo con git
@docs/git-instructions.md

Si tu equipo ya usa un AGENTS.md para otras herramientas, Claude Code lee CLAUDE.md, no AGENTS.md. La solución es crear un CLAUDE.md que empiece con @AGENTS.md y añada debajo lo específico de Claude.

Reglas por carpeta con .claude/rules

Cuando el archivo crece, divide por temas en .claude/rules/ (por ejemplo testing.md o seguridad.md). Cada regla puede limitarse a ciertas rutas con una cabecera paths, y solo se carga cuando Claude lee archivos que coinciden:

---
paths:
  - "src/api/**/*.py"
---

# Reglas de la API
- Todos los endpoints validan la entrada con un modelo de Pydantic.

Cómo comprobar que Claude lo está leyendo

Ejecuta /memory dentro de Claude Code. Muestra todos los archivos CLAUDE.md, CLAUDE.local.md y reglas cargados en la sesión, y te permite abrir cualquiera en tu editor. También puedes pedirle directamente «añade esto a CLAUDE.md».

Errores comunes

• Archivo demasiado largo. Claude pierde precisión. Recórtalo o pásalo a reglas por ruta.
• Instrucciones contradictorias. Si dos reglas chocan, Claude puede elegir una al azar. Revisa el archivo de vez en cuando.
• Instrucciones vagas. «Formatea bien el código» no se puede comprobar; «usa sangría de 4 espacios» sí.
• Esperar cumplimiento garantizado. Es contexto, no una regla forzada. Para lo crítico, usa un hook.
• Olvidar que se recarga tras compactar. El CLAUDE.md de la raíz se vuelve a leer después de /compact; los de subcarpetas solo cuando Claude lee archivos de esas carpetas.

Preguntas frecuentes

¿CLAUDE.md es lo mismo que la memoria automática?

No. CLAUDE.md lo escribes tú; la memoria automática son notas que Claude guarda por su cuenta en una carpeta aparte. Ambas se cargan al inicio, pero se gestionan por separado.

¿Lo subo a git?

El de proyecto, sí: así todo el equipo comparte las mismas instrucciones. Tus notas personales van en CLAUDE.local.md, que debes añadir al .gitignore.

¿Cuánto debe medir?

Como referencia oficial, menos de 200 líneas. Si necesitas más, divide en reglas por tema o ruta.

Siguientes pasos

Si estás empezando a programar y quieres una base antes de delegar código a un asistente, repasa la guía de introducción a Python.

Fuente: documentación oficial de Claude Code, sección de memoria y archivos CLAUDE.md (code.claude.com/docs/en/memory).