CLAUDE.md: dónde va, qué escribir y cómo convive con AGENTS.md

Qué es CLAUDE.md

Claude Code empieza cada sesión sin recordar la anterior. CLAUDE.md es la forma de darle el contexto que necesitaría un compañero nuevo: se lee al arrancar y se envía a Claude como un mensaje después del system prompt. Eso lo convierte en contexto, no en configuración obligatoria. Claude suele seguirlo, pero lo que deba ocurrir siempre o nunca pertenece a los hooks o a las reglas de permisos.

• Markdown plano, sin campos obligatorios: funcionan mejor los encabezados y las viñetas cortas.
• Los archivos se combinan, no se sobrescriben: se carga cada CLAUDE.md que aplique, así que si hay líneas contradictorias Claude elige una.
• Comprueba qué se cargó con /context all, en Memory files.

Dónde van los archivos CLAUDE.md y en qué orden se cargan

Claude Code los carga del más general al más específico, así que el archivo más cercano a donde lo iniciaste se lee el último. Además sube desde tu directorio de trabajo y carga el CLAUDE.md de cada directorio padre.

Cómo escribir un CLAUDE.md que funcione

1. Empieza con /init

   Ejecuta /init en tu proyecto. Claude Code lee el código y escribe un CLAUDE.md inicial; si ya existe uno, propone mejoras en lugar de sobrescribirlo. También recoge .cursorrules y las instrucciones de Copilot.

2. Déjalo en lo que Claude no puede averiguar solo

   Conserva los comandos exactos de build, test y lint (incluido cómo ejecutar un solo test), los lugares donde el código engaña, las decisiones que no están escritas en ningún sitio y todo lo que hayas tenido que corregir dos veces. Quita los árboles de archivos y la arquitectura que Claude puede leer en el repositorio. Anthropic recomienda no pasar de 200 líneas.

   # Comandos
   - Instalar: pnpm install
   - Un solo archivo de test: pnpm vitest run path/to/file.test.ts
   - Typecheck: pnpm tsc --noEmit
   
   # Convenciones
   - Lanza los errores con los helpers de src/lib/errors.ts, nunca con strings sueltos.
   - src/legacy/ sigue en uso, pero no copies sus patrones.
   
   # Trampas
   - Los tests de integración necesitan DATABASE_URL (ver .env.example).

3. Sé específico, sin gritar

   Escribe "Usa indentación de 2 espacios", no "Formatea bien el código". La documentación actual dice que IMPORTANT y las MAYÚSCULAS son un consejo anticuado: hacen que Claude aplique una regla en exceso. Si una línea se sigue pasando por alto, acorta el archivo o convierte la regla en un hook.

4. Divídelo con imports y reglas

   @path/to/file importa otro archivo (relativo al archivo que importa, hasta cuatro niveles de profundidad); una @ dentro de comillas invertidas se queda literal. Las reglas que valen para una parte del código van en .claude/rules/ con un glob paths, de modo que se cargan solo cuando Claude toca archivos que coinciden.

   ---
   paths: ["src/api/**/*.ts"]
   ---
   - Cada handler valida su entrada con el esquema de src/api/schemas/.

5. Pasa los procedimientos a skills

   Los flujos de varios pasos, como preparar un release, van en una skill (.claude/skills/<name>/SKILL.md), que se carga solo cuando es relevante. CLAUDE.md se lee en cada tarea, así que cada línea cuesta atención.

6. Mantenlo al día

   Añade una línea cuando Claude repita un error o una revisión detecte algo, y edita el archivo con /memory o pidiéndole a Claude que lo actualice. /doctor propone recortes cuando el archivo crece demasiado.

Fuente: documentación de Claude Code, How Claude remembers your project

CLAUDE.md frente a AGENTS.md

AGENTS.md es un formato abierto de instrucciones para agentes de programación, usado por Codex, Cursor, Gemini CLI, el agente de código de GitHub Copilot, opencode y muchos más. Claude Code ahora también lo lee, pero por defecto solo cuando el proyecto no tiene CLAUDE.md.

Un solo archivo para Claude Code y Codex

Si tu equipo usa ambos agentes, deja las instrucciones compartidas en AGENTS.md y haz que CLAUDE.md lo importe, con las notas solo para Claude debajo. Nunca se carga dos veces. Un symlink (ln -s AGENTS.md CLAUDE.md) también sirve, pero no para quienes trabajan en Windows, y un CLAUDE.md que solo diga "lee AGENTS.md" con palabras no es fiable.

• El propio repositorio de este sitio hace exactamente eso: su CLAUDE.md es la única línea @AGENTS.md.
• Codex lee los archivos AGENTS.md desde la raíz del repositorio hasta tu directorio de trabajo y limita su tamaño combinado a 32 KiB por defecto.

Límites y trampas

• Un CLAUDE.md que se carga al arrancar se lee entero hasta 4 MiB; si es más grande, se omite.
• Los archivos que se cargan bajo demanda, como los CLAUDE.md de subdirectorios y las reglas por ruta, se recortan al pasar un límite por archivo (40.000 caracteres con una ventana de contexto de 200K).
• Los imports organizan un archivo pero no ahorran contexto: el texto importado se carga igualmente.
• Los imports fuera del proyecto piden aprobación una vez; los comentarios HTML <!-- --> se eliminan y no cuestan nada.
• El CLAUDE.md de la raíz del proyecto se vuelve a leer después de /compact.
• "Recuerda esto" va a la auto memory (~/.claude/projects/<project>/memory/), no a CLAUDE.md.

CLAUDE.md dice cómo trabajar. Crewmark dice en qué trabajar y cuándo.

Un buen CLAUDE.md hace que cada sesión de Claude Code empiece bien informada, pero la sesión sigue esperando tu próximo mensaje. Crewmark convierte una sesión de Claude Code, Codex, DeepSeek Harness u OpenCode en un empleado de IA con un rol, un objetivo y un horario, y la despierta con un heartbeat para que tome la siguiente issue de un tablero.

1. Convierte una sesión en un empleado

   Elige un rol, como ingeniero de software o especialista SEO, escribe su objetivo como un número y ejecuta el comando de configuración en tu proyecto, donde ya vive tu CLAUDE.md.

2. Deja que el heartbeat inicie el trabajo

   Durante su horario laboral el empleado se despierta cada 15, 30 o 60 minutos en la misma conversación; mira cómo hacer proactivo a Claude Code. Varios pueden compartir un repositorio, como en varios agentes de Claude Code.

3. Asigna issues y responde a sus mensajes

   Pon el trabajo en el tablero; el empleado lo toma, comenta sobre la marcha y te escribe cuando necesita una decisión. Lee qué es un empleado de IA.

Preguntas frecuentes sobre CLAUDE.md