Guía de CLAUDE.md: qué es & cómo escribir uno (con plantilla, 2026)

Jasmine (una dev que usa Claude Code a diario y escribe & afina archivos CLAUDE.md en proyectos reales).

¿Qué es CLAUDE.md?

Si alguna vez te frustró que Claude Code "olvide" una y otra vez que tu proyecto usa pnpm en lugar de npm, o que cree un archivo nuevecito en vez de editar el que ya existe, entonces CLAUDE.md es justo lo que te faltaba.

CLAUDE.md es un archivo Markdown ubicado en la raíz de tu proyecto que Claude Code carga en el contexto automáticamente en el instante en que comienza una sesión, actuando como instrucciones de sistema duraderas para todo el proyecto. Dicho de otro modo, en lugar de reescribir "este proyecto usa TypeScript, corre los tests con el comando X, no toques el directorio Y" cada vez que abres una sesión nueva, escribes esas convenciones una sola vez en CLAUDE.md. El agente lo lee como leería el briefing de un compañero de equipo que ya conoce el código.

La distinción clave: CLAUDE.md no es un prompt que tengas que acordarte de pegar cada vez, y no es documentación para lectores humanos. Es contexto para el agente: escrito para ser corto, imperativo y centrado en lo que ayuda a Claude a tomar la decisión correcta. Cuanto más específico y certero, menos se desvía el agente. Si todavía no tienes claro qué es siquiera Claude Code, lee primero qué es Claude Code y luego vuelve aquí.

Otra forma de imaginarlo: cuando incorporas a una persona desarrolladora nueva, no quieres reexplicar todo cada mañana. Escribes una página de onboarding, ella la lee y luego opera por su cuenta. CLAUDE.md es esa página de onboarding, pero para el agente, y se vuelve a leer automáticamente en cada sesión. Por eso también vale la pena invertir en el archivo: escríbelo bien una vez y el beneficio se acumula a lo largo de los cientos de sesiones que vienen después. Según la guía de buenas prácticas de Anthropic, refinar CLAUDE.md poco a poco con el tiempo (tratándolo como un prompt vivo) funciona notablemente mejor que intentar escribirlo perfecto al primer intento.

¿Cómo funciona CLAUDE.md? (por qué el agente lo sigue)

El mecanismo es realmente simple: cuando abres una sesión dentro del directorio de un proyecto, Claude Code busca archivos CLAUDE.md y los carga al frente del contexto, antes de tu primerísimo prompt. Varias capas se cargan a la vez:

• Raíz del proyecto - ./CLAUDE.md, convenciones compartidas para todo el repositorio (se cargan para todas las personas que trabajan en el proyecto).
• Tu archivo personal - ~/.claude/CLAUDE.md, tus propias preferencias aplicadas en todos tus proyectos.
• Directorios padre/hijo - Claude Code sube por el árbol de directorios y también lee un CLAUDE.md dentro de un subdirectorio cuando está trabajando ahí, así que las convenciones específicas de un módulo pueden vivir justo al lado de ese módulo.

Como este contenido está al frente del contexto, está sujeto al sesgo de primacía (primacy bias): el modelo tiende a "escuchar" con más fuerza lo que aparece temprano. Por eso deberías poner tus restricciones más importantes (los límites de "NO hagas") al principio del archivo, en lugar de enterrarlas en medio de un párrafo largo.

Una salvedad honesta: CLAUDE.md crea un contexto de Claude Code fuerte, pero no es una ley inquebrantable. Cuando el contexto se llena o el archivo se hace demasiado largo, la señal se diluye y el agente todavía puede pasar cosas por alto. La forma más rápida de verificar que el agente realmente lo leyó es preguntarle directamente: "según CLAUDE.md, ¿cuál es el comando para correr los tests?". Si responde bien, tu memoria de proyecto llegó al contexto.

Los 3 tipos de CLAUDE.md & dónde van

Mucha gente supone que solo hay un archivo. En realidad hay tres ámbitos, y saber dónde va cada uno evita que amontones todo en un solo archivo:

En cuanto a CLAUDE.local.md, es un archivo privado y sin versionar para notas personales por proyecto: URLs de sandbox o datos de prueba locales que solo tú necesitas. Según la documentación oficial al momento de escribir esto (2026-08-20), el archivo sigue teniendo soporte total, no está obsoleto como afirman algunas guías más antiguas: se carga junto con CLAUDE.md y se trata igual; solo tienes que añadirlo al .gitignore. Si trabajas en varios worktrees del mismo proyecto y quieres compartir notas personales entre ellos, la documentación sugiere importar desde tu directorio home, algo como @~/.claude/my-project-instructions.md, en lugar de duplicar el contenido en cada worktree; vuelve a verificar esta sintaxis antes de depender de ella, porque puede cambiar entre versiones. Si quieres la respuesta corta a "¿dónde pongo CLAUDE.md?": convenciones del equipo en la raíz del repo, preferencias personales en el archivo de usuario, notas sin versionar en CLAUDE.local.md, excepciones específicas de módulo en el subdirectorio.

¿Qué deberías poner en CLAUDE.md? (6 secciones esenciales)

Esta es la pregunta más importante, y la mayoría de los archivos flojos falla porque mete lo que no es. Ordenadas por ROI, de mayor a menor, las seis secciones que vale la pena tener son:

1. Comandos (mayor ROI). Cómo testear, buildear, correr el lint y levantar el dev. El agente adivina mal los comandos con más frecuencia, así que es aquí donde más tiempo ahorras. Ejemplo: pnpm test, pnpm build, pnpm lint.
2. Tech stack + versiones. Lenguaje, framework, gestor de paquetes, base de datos. Ejemplo: "Next.js 15 (App Router), TypeScript strict, pnpm, PostgreSQL + Prisma". Evita que el agente eche mano de APIs desactualizadas.
3. Estructura de directorios - una línea por entrada. Ejemplo: "app/ rutas; components/ UI; lib/ helpers compartidos". Lo justo para que el agente sepa dónde va un archivo nuevo.
4. Convenciones de código. Nomenclatura, orden de imports, manejo de errores, estilo de tests. Señala lo que es fácil de equivocar; no copies tu guía de estilo entera.
5. Los límites de "NO hagas". Esta es la sección que marca la mayor diferencia, y va cerca del principio. Ejemplo: "NO crees un archivo nuevo cuando puedes editar uno existente", "NO hagas commit salvo que te lo pidan", "NO toques la carpeta migrations/ ya aplicada".
6. Importa @path a docs detallados. En lugar de pegar un documento largo inline, apunta a él: @docs/architecture.md. Esto mantiene el archivo principal ligero y a la vez le da al agente una vía hacia los detalles cuando hace falta (divulgación progresiva). Algunas cosas que la gente hace mal: las rutas relativas se resuelven respecto al archivo que hace la importación, no a tu cwd; los imports se anidan hasta 4 niveles de profundidad - cualquier cosa más profunda se ignora; para mencionar una ruta literalmente sin disparar una importación, envuélvela en comillas invertidas, por ejemplo `@README`.

La regla de filtrado: si una línea no ayuda al agente a tomar una decisión distinta, córtala. CLAUDE.md no es un README. Un README le explica el proyecto a lectores humanos; CLAUDE.md le dice al agente cómo comportarse. Dos propósitos distintos: no los mezcles, o el archivo se hincha con contenido que el agente nunca usa de verdad al decidir qué hacer.

La plantilla estándar de CLAUDE.md (copiar y pegar)

Abajo tienes una plantilla completa y funcional para un proyecto típico de Next.js + TypeScript. Es justo lo que la mayoría de las guías deja fuera: un archivo que puedes pegar y usar de inmediato, y luego recortar para que encaje con tu propio proyecto.

Copia esta plantilla y luego ajústala a tu proyecto: cambia la tech stack, los comandos y la estructura de directorios para que coincidan. Mantén la sección "NO hagas" al principio.

# CLAUDE.md

Web app for managing clinic appointment scheduling. Priority: correct business logic > coding speed.

## Do NOT (read first)
- Do NOT create a new file if you can edit an existing one.
- Do NOT commit/push unless explicitly asked.
- Do NOT edit files in `prisma/migrations/` that already ran - create a new migration.
- Do NOT use `any` in TypeScript. Do NOT disable lint to get past errors.

## Tech stack
- Next.js 15 (App Router) + TypeScript (strict)
- pnpm (do NOT use npm/yarn)
- PostgreSQL + Prisma
- Tailwind CSS + shadcn/ui
- Vitest (unit) + Playwright (e2e)

## Commands
- Dev: `pnpm dev`
- Test: `pnpm test` # single file: `pnpm test path/to/file`
- Build: `pnpm build`
- Lint: `pnpm lint`
- DB: `pnpm prisma migrate dev`

## Directory structure
- `app/` - routes (App Router)
- `components/` - reusable UI
- `lib/` - shared helpers, no JSX
- `server/` - server-side logic, DB queries
- `prisma/` - schema + migrations

## Code conventions
- Components: PascalCase; functions/variables: camelCase; constants: UPPER_SNAKE.
- Prefer named exports; absolute imports via the `@/` alias.
- Error handling: throw `AppError` (see `lib/errors.ts`), never swallow errors silently.
- Every new feature ships with a test.

## Workflow
- Before calling anything done: run `pnpm lint` and `pnpm test`, fix all errors.
- Large changes: describe a short plan before editing many files.

## Detailed docs (import when needed)
@docs/architecture.md
@docs/api-conventions.md

Hazlo & No lo hagas - ejemplos incorrecto → correcto

La diferencia entre un archivo que el agente obedece y uno que ignora suele reducirse a la redacción, no a la longitud. Unos cuantos pares reales de antes/después:

La regla de oro: escríbelo como le harías el briefing a una dev nueva y lista que aún no sabe nada del proyecto - específico, imperativo, corto. Cada línea vaga ("escribe código limpio", "sigue las buenas prácticas") es casi inútil porque el agente no puede medirla. Cambia "escribe código limpio" por "funciones de máximo 40 líneas, divide cuando sea más largo"; cambia "maneja los errores con cuidado" por "lanza AppError, sin try/catch vacíos". Lo que es medible es lo que el agente puede seguir. Para ver el conjunto completo de comandos de Claude Code que quizá quieras referenciar en el archivo, revisa la hoja de referencia de comandos de Claude Code.

Mantén CLAUDE.md ligero & eficiente en tokens

Hay un error común: cuanto más largo el archivo, más "entiende" el agente el proyecto. Es al revés. CLAUDE.md se come la ventana de contexto de cada sesión y, a medida que se hincha, cada línea importante se pierde entre docenas de líneas ruidosas: la señal se adelgaza y el agente es más propenso a pasar por alto justo lo que más necesitabas. Esto no es solo intuición: mira si los archivos de contexto AGENTS.md/CLAUDE.md realmente funcionan para ver la evidencia detrás de esto.

Experiencia práctica: apunta a alrededor de ~200 líneas, con un tope de unas 300-500 líneas para proyectos grandes. Pasarte bien de ahí es señal de que deberías separar cosas. Cómo mantener CLAUDE.md optimizado:

• Divulgación progresiva mediante imports. Mantén el archivo principal como un "índice de decisiones"; empuja los detalles largos (arquitectura, convenciones de API) a archivos separados y apúntalos con @docs/....
• Corta todo lo que no cambia el comportamiento. Historia del proyecto, textos de marketing, explicaciones interminables - déjalos ir.
• Fusiona duplicados. Si ya dijiste "usa pnpm" en la tech stack, no hace falta repetirlo en otros tres lugares.
• Prioriza por ROI. Comandos y límites al principio; material "bueno saberlo" al final o movido a un import.

Divide reglas por ruta con .claude/rules/

A medida que un proyecto crece, amontonar cada convención en un único CLAUDE.md cada vez más largo deja de funcionar. En su lugar, Claude Code te deja dividir las instrucciones en varios archivos pequeños dentro de .claude/rules/, cada uno dueño de una porción:

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

Cada archivo de regla puede llevar frontmatter YAML para limitar cuándo se carga, usando el campo paths::

---
paths:
  - "src/api/**/*.ts"
---
Validate all input with Zod before writing to the DB.

Una regla sin paths: (sin ámbito) se carga en cada sesión con la misma prioridad que ./CLAUDE.md. Una regla con paths: solo se carga cuando Claude abre un archivo que coincide con el glob - por eso mismo ahorra contexto: no pagas tokens por convenciones de rutas de API mientras editas CSS. ~/.claude/rules/ es personal, se aplica a cada uno de tus proyectos y se carga antes que las reglas a nivel de proyecto.

Esto conecta con la estrategia más amplia de gestión de tokens - mira Gestionar el contexto & la memoria en Claude Code para ver dónde encaja .claude/rules/ en el panorama más grande del presupuesto de tokens.

Consejos rápidos: /init y la tecla #

No tienes que escribir CLAUDE.md desde cero. Dos herramientas integradas lo hacen mucho más rápido:

• /init - corre este comando en tu proyecto y Claude Code escaneará el repo y generará un CLAUDE.md inicial para ti (adivinando la tech stack, los comandos y la estructura). No lo tomes tal cual - trátalo como un borrador y luego recórtalo hasta las seis secciones esenciales de arriba.
• La tecla # - mientras trabajas, escribe # seguido de una nota y Claude Code se ofrecerá a guardarla en CLAUDE.md (tú eliges el archivo del proyecto o el del usuario). Así agregas memoria de proyecto a mitad de sesión, en el instante en que detectas una convención que vale la pena registrar - sin parar a abrir un editor.

Si recién empiezas, el flujo más ligero es: correr /init → recortar el archivo hasta la plantilla de arriba → usar la tecla # para irlo construyendo con el tiempo. Los 10 pasos para empezar con Claude Code recorren todo este flujo.

Estándares de CLAUDE.md listos para usar de un kit (AgentKit)

Escribir un buen CLAUDE.md por tu cuenta lleva unas cuantas rondas de prueba y error. Si quieres un atajo, algunos kits como el bundle de AgentKit (viene con convenciones estándar de CLAUDE.md) empaquetan convenciones de CLAUDE.md junto con reglas/skills en un estándar consistente, así no arrancas desde una página en blanco. No reemplaza declarar los comandos y límites de tu propio proyecto, pero sí te ahorra el andamiaje y las convenciones que se repiten entre proyectos - puedes probar AgentKit (20% de descuento por el enlace) para ver su estructura de ejemplo y quedarte con las partes que te encajen.

Preguntas frecuentes (FAQ)

¿El nombre de archivo CLAUDE.md distingue mayúsculas de minúsculas?

Sí. Nómbralo exactamente como CLAUDE.md, con la parte del nombre toda en mayúsculas. En sistemas que distinguen mayúsculas de minúsculas (Linux, común en CI), un nombre incorrecto como claude.md puede hacer que Claude Code no reconozca el archivo.

¿Debería versionar CLAUDE.md en git?

Sí, el archivo de la raíz del proyecto - es una convención compartida, así que versiónalo y todo el equipo trabaja desde el mismo contexto. En cambio, ~/.claude/CLAUDE.md es personal y no pertenece al repositorio. Las notas personales por proyecto deberían vivir en el archivo de usuario o en un import, no en un commit.

¿Qué hago si Claude no sigue CLAUDE.md?

Suele ser una de tres causas: el archivo es demasiado largo y la señal se diluye, una regla importante está enterrada en el medio, o el contexto ya está lleno. Soluciones: acorta el archivo, mueve las restricciones de "NO hagas" al principio y verifica preguntándole al agente por una regla específica para ver si responde bien.

¿CLAUDE.md funciona con Cursor u otras herramientas?

CLAUDE.md es una convención de Claude Code. Otras herramientas usan sus propios archivos de contexto (por ejemplo AGENTS.md o el archivo de reglas de esa herramienta). El contenido que escribes suele ser reutilizable, pero el nombre del archivo y el mecanismo de carga difieren de una herramienta a otra.

¿Qué largo debería tener CLAUDE.md?

Apunta a alrededor de 200 líneas, con un tope de 300-500 líneas para proyectos grandes. Prioriza la calidad de la señal por encima del número de líneas: conserva solo lo que cambia las decisiones del agente y empuja el resto a archivos importados.

¿En qué se diferencia el archivo de proyecto de ~/.claude/CLAUDE.md?

El archivo de proyecto (./CLAUDE.md) contiene convenciones que aplican a todo el repositorio y al equipo, y se versiona en git. El archivo de usuario (~/.claude/CLAUDE.md) contiene tus preferencias personales, aplica a todos tus proyectos y queda fuera del repositorio. Claude Code carga ambos a la vez cuando existen los dos.

Conclusión + próximos pasos

CLAUDE.md es la inversión más pequeña y de mayor retorno que puedes hacer con Claude Code: escríbelo una vez y el agente sigue tus convenciones en cada sesión. Copia la plantilla de arriba, recórtala a tu proyecto, pon las restricciones de "NO hagas" al principio y mantén el archivo ligero. Si recién empiezas, lee los 10 pasos para principiantes; si quieres consultas rápidas de comandos, mantén la hoja de referencia de comandos de Claude Code junto al teclado.