CLAUDE.md: cómo escribirlo para que Claude Code te haga caso

Un CLAUDE.md es un fichero Markdown que Claude Code lee al empezar cada sesión y que mete en su contexto: ahí van los comandos, las convenciones y las trampas que no puede adivinar mirando el código. Para que te haga caso, tiene que ser corto y con instrucciones que se puedan comprobar: la documentación oficial recomienda menos de 200 líneas por fichero. Abajo tienes cómo lo carga Claude Code (comprobado hoy en la documentación), qué poner y qué no, el sistema por capas que usamos a diario y dos plantillas para copiar.

Si todavía no usas Claude Code, empieza por la guía de Claude Code y vuelve aquí.

Cómo carga Claude Code los CLAUDE.md#

Claude Code no lee un solo CLAUDE.md: busca varios y los suma, no se pisan unos a otros. Estos son los sitios, en el orden en que entran en el contexto, según la documentación oficial a 16 de octubre de 2026:

Lo que más se ignora es cómo funciona con carpetas:

1. Hacia arriba, al arrancar. Carga el CLAUDE.md (y el CLAUDE.local.md) de la carpeta donde abres Claude Code y de todas las carpetas superiores. Van de la raíz hacia abajo, así que lo más cercano a tu carpeta se lee al final.
2. Hacia abajo, bajo demanda. Los CLAUDE.md de subcarpetas no se cargan al empezar: entran la primera vez que Claude lee, escribe o edita un fichero de esa subcarpeta.
3. Imports con @ruta. Dentro de un CLAUDE.md puedes escribir @README o @docs/git.md y ese fichero se expande en el contexto. Las rutas relativas cuentan desde el fichero que importa, admite hasta cuatro saltos de imports encadenados y, si el fichero está fuera de tu proyecto, la primera vez te pide aprobarlo.
4. Reglas en .claude/rules/. Siguen existiendo: ficheros .md por tema. Sin cabecera se cargan siempre; con un campo paths en el frontmatter solo entran cuando Claude toca ficheros que encajan con el patrón.

Dos detalles que cambian cómo escribes. El primero: el contenido de CLAUDE.md llega al modelo como un mensaje de usuario después del prompt de sistema, no como parte del prompt de sistema. Es contexto, no configuración obligatoria; si algo tiene que cumplirse siempre, va en un hook. El segundo: los comentarios HTML de bloque (<!-- nota -->) se quitan antes de pasarlo al modelo, así que puedes dejar notas para personas sin gastar contexto.

Para ver qué ha cargado de verdad, escribe /context en la sesión y mira la lista Memory files. /memory te lista los ficheros de memoria, te deja abrirlos en tu editor y activar o desactivar la memoria automática.

AGENTS.md: cuándo lo lee y cuándo no#

Según la documentación oficial, desde la versión 2.1.277 Claude Code lee AGENTS.md, el fichero que usan otros agentes de programación. Pero por defecto solo si no hay ningún CLAUDE.md o CLAUDE.local.md en tu carpeta ni en las superiores. Si hay los dos, lee solo los CLAUDE.md. Se cambia en /config, opción Project instructions.

Esto nos afecta de lleno: como tenemos un CLAUDE.md en la carpeta raíz de todos los proyectos, un AGENTS.md suelto dentro de un proyecto no se lee con la configuración por defecto. La solución que recomienda la documentación, y la que usamos en un proyecto Next.js, es importarlo desde el CLAUDE.md:

@AGENTS.md

# mi-proyecto
...

En Windows usa el import y no un enlace simbólico: la propia documentación avisa de que crearlos pide permisos de administrador o el modo desarrollador, y git los puede sacar como un fichero de texto de una línea.

Menos es más: cada línea compite por la atención#

Todo lo que pones en CLAUDE.md entra en cada petición de la sesión. La documentación oficial lo dice sin rodeos: apunta a menos de 200 líneas por fichero, porque los ficheros más largos «consumen más contexto y reducen el cumplimiento». Y en la guía de buenas prácticas propone una prueba para cada línea:

«Would removing this cause Claude to make mistakes?» If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!

Es decir: si quitar la línea no haría que Claude se equivocara, sobra. Tres consecuencias prácticas:

• Partir en imports no ahorra nada. Los ficheros importados también se cargan al arrancar. Ordena, pero no adelgaza.
• Lo que solo importa en una parte del código va a una regla con paths o a una skill, que se cargan solo cuando hacen falta.
• El «IMPORTANTE» se gasta. La documentación recomienda poner énfasis en la línea que Claude se salta, y solo en esa: si lo pones en muchas, ninguna destaca.

También avisa de las contradicciones: si dos instrucciones chocan (por ejemplo, la del CLAUDE.md global y la del proyecto), Claude puede escoger una al azar.

Qué poner y qué dejar fuera#

Lo de los secretos merece una línea aparte. El CLAUDE.md de proyecto suele ir a git, y aunque no vaya, lo lee el modelo en cada sesión. En nuestros ficheros el patrón es decir dónde está, nunca qué es: en uno de ellos pone que una contraseña de administración está «SOLO en un fichero de .secretos/ (ignorado por git)». En la plantilla global de abajo verás la regla general.

Lo que cambia cada día (qué quedó a medias, qué toca mañana) tampoco va ahí. Nosotros lo guardamos en una nota de estado por proyecto en la memoria del asistente, que le llega con cada encargo. Así el CLAUDE.md dice cómo se trabaja y la nota dice por dónde vamos.

Todo lo anterior cabe en cuatro preguntas. Es el filtro que pasamos a cada línea antes de dejarla:

Desliza para ver la figura completa

Nuestro sistema de CLAUDE.md por capas#

En GamzyHost trabajamos con un asistente propio montado sobre Claude Code en una VPS con Windows Server 2022, que entra cada día en más de veinte proyectos (lo contamos en cómo montar un asistente de IA propio). Cada proyecto vive en C:\Proyectos\<Área>\<proyecto> y cada nivel de carpeta tiene su CLAUDE.md. Como Claude Code carga todas las carpetas superiores, al abrir un proyecto el modelo recibe las tres capas sumadas, y la cuarta si toca la parte que la tiene.

Desliza para ver la figura completa

Usamos una carpeta madre (C:\Proyectos) en vez de ~/.claude/CLAUDE.md para las reglas comunes por una razón práctica: así solo se aplican a los proyectos, no a cualquier sesión que se abra en la máquina, y viajan con la carpeta si la movemos. Estos son extractos reales, recortados y adaptados.

Capa común (23 líneas en total). Lo que vale para cualquier proyecto: dónde va cada cosa, dónde se apunta lo hecho y qué no se toca sin permiso.

# Proyectos de Ferran: reglas para cualquier sesión de Claude Code

## Orden
- Una carpeta madre por proyecto y todo lo del proyecto dentro,
  cada parte en su subcarpeta (web, panel, documentos, capturas...).
- Trabaja solo dentro de la carpeta del proyecto.

## Cuidado
- Las dependencias (node_modules, .venv...) no están copiadas:
  instálalas con el gestor del proyecto antes de ejecutar.
- Nada de git push, despliegues ni cambios en servidores sin su vale.
- Nunca escribas secretos (claves, tokens, contraseñas) en ficheros
  del proyecto ni en notas.

Capa de área (5 líneas). Casi nada: qué es el área y qué proyectos tiene. No hace falta más.

# Área Otros
Proyectos que todavía no tienen área propia. Si uno crece o encaja
en otra área, se mueve allí.
Proyectos: `proyecto-a`, `proyecto-b`, `blog-ia`, ...

Capa de proyecto (unas 40 líneas en el de una app Node). Aquí está lo que de verdad ahorra errores: comandos exactos, cómo se comprueba, cómo se despliega y las trampas.

## Cómo se trabaja (app/)
- Stack: Node 22 + Express 5 + better-sqlite3 en `server/`;
  React 19 + Vite + Tailwind v4 en `src/`; `shared/` lo usan los dos.
- Comandos: `npm install`; `npm run build:app`; `npm test` (vitest);
  `npx tsc --noEmit -p tsconfig.json`.
- E2E: marca estados en la cuenta con la que entra. NO correrlo con
  la cuenta real de Ferran; crear antes una cuenta de pruebas.
- Migraciones en `server/db.ts`: nunca editar una publicada, añadir otra.

Las mejores líneas de nuestros CLAUDE.md son trampas que costaron una tarde: en un proyecto de Expo, que npx expo start --web falla con web.output: "static" y para capturas hay que cambiarlo a "single" sin hacer commit; en otro de vídeo, que el ffmpeg que trae Remotion viene recortado y hay que medir el volumen con loudnorm. Ninguna se deduce del código.

Plantilla de CLAUDE.md para un proyecto web con Node#

Cópiala en la raíz del proyecto y rellena solo lo que aplique. Si una sección se queda vacía, bórrala.

# nombre-del-proyecto

Qué es en una frase y para quién. Dónde corre (producción, pruebas).

## Cómo se trabaja
- Stack: Node 22 + Express 5 en `server/`; React 19 + Vite en `src/`.
- Instalar: `npm install` (node_modules no está en el repo).
- Desarrollo: `npm run dev` (puerto 3000). Build: `npm run build`.
- Antes de dar algo por terminado: `npm test` y `npx tsc --noEmit`.
- Variables: ver `.env.example`. El `.env` real no se muestra ni se copia.

## Convenciones
- Módulos ES (`import`), no `require`.
- Migraciones en `server/migrations/`: nunca editar una publicada; añadir otra.
- Textos de la interfaz en español.

## Desplegar
- `npm run deploy`, solo con el visto bueno de <responsable>.
- Nunca `git push --force` ni commits directos a `main`.

## Trampas
- (Vacío al principio: aquí va cada cosa en la que Claude falle dos veces.)

Plantilla para la capa global#

Puede ir en ~/.claude/CLAUDE.md (todas tus sesiones) o en una carpeta madre que contenga tus proyectos, como hacemos nosotros. Debe ser la más corta de todas, porque entra en todo.

# Reglas para cualquier proyecto

## Orden
- Todo lo de un proyecto, dentro de su carpeta. Nada suelto fuera.
- Lo temporal, en `temp/` del proyecto; bórralo al acabar.

## Cuidado
- Nada de git push, despliegues ni cambios en servidores sin que lo confirme.
- Nunca escribas secretos en ficheros ni notas: di dónde están, no qué son.
- Las dependencias no están instaladas: instálalas antes de ejecutar.

## Al terminar
- Di qué has cambiado y cómo lo has comprobado.
- Si aprendes algo técnico que valga para la próxima vez, añádelo
  al CLAUDE.md del proyecto, en una línea.

La última línea es la que mantiene vivo el sistema: es el propio agente quien apunta las trampas que descubre, y tú solo revisas que sean cortas.

Empezar con /init y mantenerlo vivo#

Para un proyecto sin CLAUDE.md, el camino corto es /init: Claude analiza el código y genera uno con los comandos de build, los tests y las convenciones que encuentra. Si ya existe, propone mejoras en vez de sobrescribirlo. Según la documentación, con la variable CLAUDE_CODE_NEW_INIT=1 el /init pasa a ser un asistente por fases que pregunta qué quieres montar (CLAUDE.md, skills, hooks) y te enseña una propuesta antes de escribir nada.

Lo que genera /init es un borrador. Tacha lo que Claude deduciría solo (el árbol de carpetas, la lista de dependencias) y deja lo que no.

Después, la regla para añadir una línea es la misma que propone la documentación oficial: cuando Claude se equivoca dos veces en lo mismo. Una vez puede ser casualidad; dos veces es que le falta un dato. Otras señales de que toca una línea:

• Escribes en el chat la misma corrección que la sesión anterior.
• Una revisión de código encuentra algo que Claude tendría que haber sabido.
• Una persona nueva en el proyecto necesitaría ese mismo dato.

Para añadirla, díselo tal cual: «añade esto al CLAUDE.md». Si solo dices «recuerda que…», lo guarda en su memoria automática, que es otra cosa (ahora lo vemos). Y para limpiar, la documentación describe /doctor prompt-audit (desde la versión 2.1.283), que revisa tus ficheros de instrucciones en busca de reglas viejas, referencias a ficheros que ya no existen y contradicciones, y no cambia nada hasta que se lo pidas.

CLAUDE.md, rules, skills y memoria: qué va en cada sitio#

La frontera con las skills es la que más se confunde. Si es un procedimiento de varios pasos (desplegar, publicar, preparar un informe), va en una skill: solo se carga cuando hace falta. En el CLAUDE.md, como mucho, una línea que diga que esa skill existe. La documentación lo resume igual: si una entrada es un procedimiento o solo afecta a una parte del código, sácala a una skill o a una regla.

La memoria automática guarda notas que Claude escribe solo en ~/.claude/projects/<proyecto>/memory/, y la puedes desactivar con /memory o con la variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Nosotros la tenemos apagada en las sesiones de nuestro asistente: según nuestras mediciones, sus instrucciones eran unos 3.000 tokens en cada mensaje y nuestra memoria ya vive en un vault de Obsidian ordenado por proyectos. Si no tienes nada parecido, déjala encendida: es útil para lo que no quieres escribir a mano.

Errores típicos con CLAUDE.md#

• Pegar el README. Lo que ya está en el código o en la documentación del proyecto, Claude lo lee si lo necesita. El CLAUDE.md es para lo que no está escrito en otro sitio.
• Instrucciones que no se pueden comprobar. «Escribe código limpio» no cambia nada. «Ejecuta npm test antes de hacer commit» sí. La documentación pone el ejemplo de «usa 2 espacios de sangría» frente a «formatea bien el código».
• Contradicciones entre capas. Si la capa global dice una cosa y la del proyecto otra, Claude puede seguir cualquiera de las dos. Repasa las capas juntas de vez en cuando.
• Usarlo como candado. Una línea de «no edites .env» es una petición, no una garantía. Lo que debe cumplirse siempre va en un hook o en los permisos.
• Meter el estado del día. Tareas, lo que quedó a medias, la fecha de la última sesión: envejece en horas y luego confunde. Eso va en otra nota.
• Creer que se ha cargado. Un CLAUDE.md en una subcarpeta no sale en /context al arrancar, y un AGENTS.md con CLAUDE.md por encima no se lee por defecto. Compruébalo antes de culpar al modelo.
• Partirlo en imports para «adelgazarlo». Ordena, pero el coste en contexto es el mismo.

Qué hacer ahora#

1. Abre Claude Code en tu proyecto y ejecuta /context: mira qué CLAUDE.md está cargando hoy.
2. Si no tienes ninguno, ejecuta /init y recorta el borrador con la prueba de «¿se equivocaría sin esta línea?».
3. Copia la plantilla global y quédate solo con las reglas que de verdad aplicas en todos tus proyectos.
4. Deja la sección «Trampas» vacía y llénala con cada error que Claude repita dos veces.

Si lo que quieres es que el agente sepa hacer tareas completas, sigue con skills de Claude. Si quieres conectarlo a tus servicios, mira qué es MCP.