Mejores Prácticas para CLAUDE.md: 9 Reglas para que Claude Code Te Haga Caso (2026)

Mejores Prácticas para CLAUDE.md: 9 Reglas para que Claude Code Te Haga Caso (2026)

La mayoría de los artículos sobre mejores prácticas de CLAUDE.md te dan una plantilla y ya está — pero el archivo que escribiste la semana pasada probablemente ya se está ignorando, y no sabes por qué. La solución rara vez es "añadir más reglas." Casi siempre es lo contrario. Hemos desplegado Claude Code en todos los proyectos de clientes recientes, y estas 9 reglas son las que realmente marcan la diferencia: jerarquía que coincide con cómo Claude carga los archivos, un presupuesto de instrucciones que no puedes romper, la decisión sobre AGENTS.md, y las seis razones por las que Claude silenciosamente descarta tu archivo a mitad de sesión.

Puntos Clave

• CLAUDE.md es la memoria de proyecto que se carga en el contexto de Claude Code — mantenlo por debajo de 200 líneas o las reglas empezarán a caerse.
• Los archivos se cargan de arriba hacia abajo: global, raíz del proyecto, subdirectorio (carga diferida), y CLAUDE.local.md (personal, en gitignore).
• Usa AGENTS.md si también ejecutas Cursor o Copilot; crea un enlace simbólico de CLAUDE.md a AGENTS.md para apuntar a ambas herramientas.
• Si Claude ignora tu archivo, el 90% de las veces es por extensión, vaguedad, o la falta de un "por qué".

Qué Hace Realmente CLAUDE.md (Y Por Qué Importa)

En resumen: CLAUDE.md es un archivo markdown que Claude Code lee como memoria de proyecto al inicio de cada sesión. No es un system prompt, un hook, ni un skill — es contexto orientativo que empuja a Claude hacia las convenciones de tu equipo. Piensa en él menos como documentación y más como un archivo de configuración que tu par programador IA realmente lee.

Muchos equipos escriben CLAUDE.md como si fuera un README. Ese es el primer error. Un README explica el proyecto a humanos que pueden ojear y saltarse secciones. CLAUDE.md lo consume Claude Code completo al inicio de cada sesión — cada línea cuesta tokens y adherencia. Se parece mucho más a un archivo de configuración o un conjunto de fixtures de tests que a documentación.

Tampoco es la única forma de guiar a Claude. Los hooks ejecutan acciones deterministas (formateo, bloqueo de commits). Los skills agrupan flujos de trabajo reutilizables. CLAUDE.md se sitúa en el medio como contexto orientativo — Claude lo evalúa, a veces lo sobrescribe, y definitivamente olvida partes si escribes demasiado. Esa distinción es la base de todo lo que sigue, y es por qué CLAUDE.md es una herramienta dentro de la práctica más amplia de la ingeniería de contexto, no una solución mágica.

Regla #1: Trátalo como código, no como docs. Versiona el archivo. Revísalo en PRs. Recórtalo igual que refactorizarías un módulo inflado. Según la guía de CLAUDE.md de Anthropic, el archivo se carga con la misma prioridad que cualquier instrucción de sistema — lo que significa que una regla obsoleta de hace seis meses sigue activamente dando forma a cada respuesta hoy.

Cómo se Carga CLAUDE.md: La Jerarquía de 4 Niveles

En resumen: Claude Code carga CLAUDE.md desde cuatro niveles: global (~/.claude/CLAUDE.md), raíz del proyecto, CLAUDE.local.md para sobrescrituras personales, y archivos de subdirectorio que se cargan de forma diferida solo cuando Claude lee archivos dentro de ese directorio. Los subdirectorios hermanos nunca ven el CLAUDE.md del otro, lo que mantiene la memoria de Claude Code bien acotada.

La jerarquía es la parte más mal entendida de CLAUDE.md, y es donde ninguno de los 5 primeros resultados en los buscadores profundiza. Esto es lo que ocurre realmente bajo el capó:

Dos términos que vale la pena fijar: carga diferida y aislamiento entre hermanos.

La carga diferida significa que un CLAUDE.md de subdirectorio no entra en el contexto de Claude hasta que Claude abre un archivo dentro de ese directorio. Si dices "arregla el bug de login" y Claude solo toca backend/, tu frontend/CLAUDE.md nunca se carga. Esto es bueno — mantiene la ventana de contexto limpia — pero le da problemas a los equipos que ponen reglas críticas en subdirectorios esperando que siempre apliquen.

El aislamiento entre hermanos es el corolario: frontend/CLAUDE.md y backend/CLAUDE.md nunca se cargan mutuamente. Solo comparten lo que está en la raíz del proyecto. Así que si tus reglas de frontend contradicen las de backend, está bien. Si necesitan compartir una convención, súbela al archivo raíz.

CLAUDE.local.md es la válvula de escape. Se carga pero no se commitea, perfecto para anulaciones del tipo "yo prefiero pnpm pero el equipo estandarizó con npm". La trampa: no se añade automáticamente al gitignore. Tienes que hacerlo tú mismo. Si te olvidas, commitearás tus reglas personales en el repo del equipo.

Regla #4: Ubica las instrucciones donde Claude realmente las lee. Las reglas de estilo para componentes React pertenecen a frontend/CLAUDE.md, no a la raíz. Las reglas de migraciones de base de datos pertenecen a backend/. La documentación de Memoria de Anthropic (actualizada en noviembre de 2025) lo confirma — el comportamiento de carga diferida es intencional y funcional.

Qué Poner Dentro de CLAUDE.md (Y Qué Dejar Fuera)

En resumen: Dentro de CLAUDE.md va todo lo que Claude no puede inferir de tu código: comandos de build, convenciones de nomenclatura, antipatrones que tu equipo ya ha sufrido, y el por qué detrás de cada regla. Fuera queda lo que ya está en el README, lo que está en package.json, y cualquier regla que cambie semanalmente. Las instrucciones de Claude Code deben ser verificables y específicas.

Aquí tienes un CLAUDE.md mínimo que realmente trabaja:

# Project: techsy-app

## Commands
- Build: `pnpm build` (Turbopack — Webpack flags don't apply)
- Test: `pnpm test --run` (we use Vitest, not Jest)
- Lint: `pnpm lint` (will fail CI on warnings, not just errors)

## Conventions
- Server components by default. Add `'use client'` only when truly needed.
  Why: we hit 8s LCP last quarter from over-clienting.
- Database access only via `lib/db/` helpers — never raw SQL in routes.
  Why: row-level security policies live in those helpers.
- Tests colocate as `*.test.ts` next to the file under test.

## Don'ts
- Don't add a new dependency without opening a PR comment first.
- Don't use `any` — use `unknown` and narrow.

## Where to look
- Schema: `db/schema.ts`
- Auth flow: `lib/auth/README.md`

Ahora compáralo con la versión anti-patrón que la mayoría de los equipos manda:

# Project Rules

- Write clean, maintainable code.
- Follow best practices.
- Use TypeScript properly.
- Make sure tests pass.
- Be consistent with existing patterns.
- Document complex logic.

El segundo archivo no es incorrecto. Es simplemente inútil. Claude ya quiere escribir código limpio. "Sé consistente" no le dice a Claude con qué patrón ser consistente. Los ejemplos públicos del ingeniero de Anthropic Boris Cherny se inclinan fuertemente hacia el primer estilo — comandos concretos, herramientas nombradas, y el por qué detrás de las decisiones que no son obvias por el código.

Regla #2: Sé específico, no aspiracional. "Escribe código limpio" es aspiracional. "Componentes de servidor por defecto; añade 'use client' solo cuando sea realmente necesario" es verificable. La misma disciplina sustenta un buen prompt engineering: las instrucciones específicas y verificables superan a las aspiraciones vagas, ya vivan en un prompt o en un CLAUDE.md.

Regla #3: Explica por qué importa cada regla. El "por qué" no es relleno — es como Claude decide los casos límite. Una regla con una razón ("tuvimos LCP de 8s por sobre-clientizar") generaliza a situaciones similares. Una regla sin razón se ignora en el momento en que el contexto cambia. El patrón también está documentado en la guía de CLAUDE.md de Builder.io.

¿Por Qué Claude Ignora Tu CLAUDE.md? El Presupuesto de Instrucciones

En resumen: Claude no es malicioso — se le acaba la atención. Pasadas unas 80 líneas empezarás a ver cómo se caen reglas; pasadas 200 líneas, bloques enteros se ignoran; pasadas 500 palabras de reglas densas, la adherencia se derrumba. La solución es un presupuesto de instrucciones. Trata cada línea como un coste sobre la memoria de Claude Code y la adherencia por regla.

La investigación reciente confirma lo que los usuarios en producción siguen descubriendo: el seguimiento de instrucciones se degrada de forma no lineal con el número de reglas. El artículo de arxiv 2507.11538 sobre capacidad de seguimiento de instrucciones muestra que la adherencia por regla disminuye a medida que añades más — y el análisis de HumanLayer de CLAUDE.md en producción confirma el mismo hallazgo.

Lo que esto significa: cada regla que añades hace que todas las demás tengan un poco menos de probabilidades de seguirse. Así que un CLAUDE.md de 400 líneas no es 4 veces más efectivo que uno de 100 líneas. A menudo es menos efectivo, porque las reglas que realmente te importan quedan diluidas por las que escribiste un viernes hace tres meses y nunca borraste.

En nuestros archivos CLAUDE.md, todo lo que pasa de la línea 150 empieza a perder adherencia de forma visible. En la línea 250 hemos visto a Claude saltarse secciones enteras. Así que lo limitamos.

wc -l CLAUDE.md

Esa es toda la herramienta. Ejecútala. Si estás por encima de 200, estás sobre presupuesto. La regla dura que entregamos a los clientes:

Trata CLAUDE.md como un presupuesto de 200 líneas. Cada línea cuesta adherencia. Gástala donde importa.

Regla #1 reforzada: Mantenlo corto. Menos de 200 líneas. Menos de 500 palabras de reglas densas. Si te encuentras queriendo añadir reglas de automatización ("siempre ejecutar prettier tras las ediciones"), esas probablemente pertenecen a hooks de Claude Code — los hooks son deterministas y no consumen tokens del presupuesto de instrucciones.

¿CLAUDE.md, AGENTS.md, .cursorrules o copilot-instructions?

En resumen: Si solo usas Claude Code, CLAUDE.md está bien. Si usas dos o más CLIs de agentes (Codex, Cursor, Copilot, Sourcegraph), cambia a AGENTS.md y crea un enlace simbólico de CLAUDE.md a AGENTS.md. AGENTS.md surgió a finales de 2025 como estándar entre herramientas — la mayoría de los agentes modernos recurren a él como fallback, así que un solo archivo alimenta todo el ecosistema.

Esta es la pregunta que ninguno de los 5 primeros resultados responde realmente. Aquí está la matriz:

El truco de apuntar a ambas herramientas es una sola línea:

ln -s AGENTS.md CLAUDE.md

Eso es todo. Ahora Claude Code, Codex, y cualquier herramienta compatible con AGENTS.md leen el mismo archivo. Actualizas una vez, cada agente lo recoge. La especificación de AGENTS.md es abierta e intencionalmente mínima — es solo markdown con secciones convencionales.

Dos matices del mundo real. Primero: si tu equipo tiene un usuario avanzado de Cursor, las reglas .cursorrules de Cursor adoptan un enfoque diferente — un solo archivo, sin jerarquía, formato más rígido. Algunos equipos mantienen ambos: AGENTS.md para las reglas compartidas, .cursorrules para las peculiaridades específicas de Cursor. Segundo: el .github/copilot-instructions.md de Copilot no hace fallback a AGENTS.md, así que los equipos que usan mucho Copilot necesitan un archivo separado.

Si estás eligiendo una pila de agentes desde cero, nuestro análisis de Claude Code vs Cursor vs Copilot cubre las compensaciones a nivel de harness. La versión corta: la jerarquía de Claude Code es la más potente para monorepos, la UX de Cursor gana para trabajo en solitario, y la integración de IDE de Copilot sigue siendo la más fluida para adopción incremental.

Regla #9: Usa AGENTS.md si ejecutas más de un CLI de agentes. No mantengas dos archivos diciendo lo mismo. Elige el archivo que lee la mayoría de tu pila, crea enlaces simbólicos para el resto.

CLAUDE.md vs Hooks vs Skills: El Triángulo de Decisión

En resumen: CLAUDE.md = contexto orientativo. Hooks = acciones deterministas. Skills = capacidades empaquetadas. Elige el incorrecto y quemarás presupuesto de instrucciones en algo que debería manejar un hook, o escribirás una regla de CLAUDE.md para algo que solo un skill puede entregar. El triángulo es la forma más económica de mantener CLAUDE.md ligero.

Tres herramientas, tres trabajos. El error que vemos más a menudo: poner "siempre ejecutar prettier después de editar" en CLAUDE.md. Claude lo lee. Claude a veces ejecuta prettier. Te frustras. La solución es sacar esa línea de CLAUDE.md y meterla en un hook — porque los hooks se disparan determinísticamente cada vez, sin margen de maniobra orientativo.

Si una regla debe dispararse siempre, pertenece a un hook. Si es una preferencia de estilo que Claude puede evaluar en contexto, pertenece a CLAUDE.md. Si es un flujo de trabajo multi-paso con assets empaquetados (plantillas, scripts, prompts), pertenece a un skill.

Regla #8: Elige correctamente entre CLAUDE.md, hooks y skills — meter un hook en CLAUDE.md es el desperdicio más común del presupuesto de instrucciones. Configura acciones deterministas con hooks de Claude Code y empaqueta flujos reutilizables como skills de Claude. Tu CLAUDE.md se hace más corto, tus guardianes se vuelven más firmes, y Claude deja de "olvidar" las reglas que importan.

Patrones para Monorepos: CLAUDE.md Anidado, @imports y .claude/rules/

En resumen: En un monorepo, mantén el CLAUDE.md raíz pequeño — solo punteros y convenciones compartidas. Empuja los detalles a apps/*/CLAUDE.md para que cada subárbol tenga reglas acotadas. Usa @imports para compartir archivos de reglas modulares mediante .claude/rules/. Esto es divulgación progresiva — Claude recoge cada pieza solo cuando es relevante.

Un árbol típico de CLAUDE.md en un monorepo:

.
├── CLAUDE.md                        # 30 líneas — apunta a subdirs y reglas compartidas
├── .claude/
│   └── rules/
│       ├── style.md
│       ├── testing.md
│       └── security.md
├── apps/
│   ├── web/
│   │   └── CLAUDE.md                # Reglas específicas de Next.js
│   └── api/
│       └── CLAUDE.md                # Reglas específicas de Fastify
└── packages/
    └── shared/
        └── CLAUDE.md                # Reglas de autor de librería

La sintaxis @import permite que el archivo raíz incluya fragmentos de reglas compartidas sin repetirlos:

# Root CLAUDE.md

This is a Turborepo. See subdir CLAUDE.md for app-specific rules.

@import .claude/rules/style.md
@import .claude/rules/testing.md
@import .claude/rules/security.md

## Top-level commands
- `pnpm dev` runs all apps in parallel
- `pnpm test` runs every workspace's test script

Esto es la divulgación progresiva en la práctica. El archivo raíz es un puntero de 30 líneas. Cada CLAUDE.md de subdirectorio añade 50-80 líneas de reglas focalizadas. Los archivos .claude/rules/ contienen fragmentos de convenciones que múltiples subdirectorios pueden importar. Nada se duplica, nada se pierde, y ningún archivo individual supera el presupuesto de instrucciones.

La regla de carga diferida de antes importa aún más aquí: cuando Claude trabaja en apps/web/Button.tsx, ve el archivo raíz más apps/web/CLAUDE.md más los archivos de reglas importados con @import. No ve apps/api/CLAUDE.md. Ese es el punto — las convenciones de backend no contaminan el contexto de frontend, y tu ventana de contexto sigue siendo usable.

Regla #6: Usa @imports para mantener el archivo raíz por debajo de 200 líneas. La guía de Mejores Prácticas de Anthropic para Claude Code trata esto como el patrón estándar para monorepos. Los subagentes también heredan el contexto del CLAUDE.md padre, lo que vale la pena saber si anidas flujos de trabajo — consulta la ingeniería de contexto para ver cómo interactúa con el diseño de subagentes.

6 Razones por las que Claude Ignora Tu Archivo (Y la Solución para Cada Una)

En resumen: Cuando Claude ignora CLAUDE.md, casi siempre es una de estas seis causas: archivo demasiado largo, frases vagas, "por qué" ausente, compactación de contexto, archivo padre en conflicto, o nombre de archivo incorrecto. Cada una tiene una solución de 60 segundos. Prueba en una sesión nueva después de cada cambio — esa es la Regla #7.

1. Archivo demasiado largo (>200 líneas / >500 palabras)

Ejecuta wc -l CLAUDE.md. Si supera 200, recorta agresivamente. Mueve las reglas de automatización a hooks. Mueve los flujos de trabajo a skills. Divide los fragmentos compartidos en .claude/rules/ e impórtalos con @import. La razón más común por la que Claude "dejó de seguir" tus reglas es que el archivo fue creciendo con el tiempo y la adherencia se colapsó silenciosamente.

2. Frases vagas ("escribe código limpio")

Reemplaza cada regla aspiracional con una específica y verificable. "Sé consistente" es invisible para Claude. "Usa componentes de servidor por defecto; solo añade 'use client' para formularios o UI interactiva" es algo que Claude puede aplicar realmente.

3. Falta el "por qué"

Las reglas sin razones no generalizan. Claude no puede inferir cuándo doblar la regla porque no sabe qué está protegiendo. Cada regla no obvia recibe una línea: "usamos unknown y no any porque tuvimos tres crashes en runtime por respuestas de API tipadas como any el trimestre pasado."

4. La compactación de contexto lo descartó

Las sesiones largas desencadenan la compactación — Claude resume el contexto anterior para ajustarse a la ventana, y el contenido de CLAUDE.md a veces queda resumido hasta desaparecer. La solución: /clear después de grandes quemas de contexto, o reinicia la sesión por completo. Esto es exactamente lo que sigue apareciendo en el Issue #17530 de GitHub.

5. Conflicto con un CLAUDE.md padre

El global dice "usa 4 espacios." La raíz del proyecto dice "usa 2 espacios." El subdirectorio no dice nada. Claude elige uno — a veces el incorrecto. Audita ~/.claude/CLAUDE.md y la raíz del proyecto en busca de contradicciones. El más específico debería ganar, pero solo si lo haces explícito.

6. Ubicación incorrecta o capitalización del nombre de archivo

Claude.md y CLAUDE.md son archivos diferentes en Linux y macOS. Lo mismo ocurre con claude.md y CLAUDE.md. Confirma que la ruta es exactamente ./CLAUDE.md (todo en mayúsculas), y confirma que Claude Code se lanza desde el directorio que lo contiene. El Issue #668 de GitHub está lleno de casos donde el archivo existía pero Claude no podía verlo por rutas incorrectas.

Regla #7: Prueba en una sesión nueva. Después de cualquier cambio en CLAUDE.md, abre una sesión nueva y pide a Claude que "resuma las reglas en CLAUDE.md". Si el resumen se pierde algo, el archivo no está haciendo su trabajo.

Tu Primer CLAUDE.md en 10 Minutos: Un Arranque en 5 Pasos

En resumen: Ejecuta /init para generar un borrador, recórtalo a 6-10 reglas reales con razones, añade 3 comandos que Claude debería conocer, añade 2 antipatrones que tu equipo ha sufrido, y luego prueba en una sesión nueva pidiendo a Claude que resuma el archivo. Tiempo total: unos 10 minutos. La receta de 5 pasos es la que usamos el día 1 de cada repo nuevo.

1. Ejecuta /init para generar un borrador. El comando /init de Claude Code escanea tu repo y escribe un CLAUDE.md inicial. No entregues lo que genera. La salida de /init es un punto de partida, no un archivo terminado — y francamente, la mayor parte de lo que genera puede irse.

2. Recórtalo a 6-10 líneas de reglas reales con razones. Elimina todo lo genérico. Elimina lo que ya está en el README. Conserva solo las reglas que Claude no puede inferir del código.

3. Añade 3 comandos que Claude debería conocer. Build, test, lint. Incluye el comando exacto y cualquier flag no obvio. Si usas Vitest en lugar de Jest, dilo.

4. Añade 2 antipatrones que este equipo ha sufrido. Reales. "No uses any porque tuvimos tres crashes en runtime" gana siempre a "usa TypeScript correctamente".

5. Abre una sesión nueva y verifica. Pide a Claude que "resuma las reglas en CLAUDE.md". Si se pierde algo, el archivo es demasiado largo, demasiado vago, o le falta un "por qué". Corrige y repite.

Regla #5: No auto-generes solo con /init. /init es un punto de partida, no un archivo terminado. Los 8 minutos que pasas recortándolo son donde está el valor.

Preguntas Frecuentes

¿Qué es un archivo CLAUDE.md?

Un archivo CLAUDE.md es un archivo markdown que Claude Code lee como memoria de proyecto al inicio de cada sesión. Le dice a Claude tus convenciones, comandos y antipatrones para que no tenga que adivinar. Funciona en cuatro niveles: global, raíz del proyecto, subdirectorio (carga diferida), y un CLAUDE.local.md personal que mantienes en gitignore.

¿Qué longitud debería tener un archivo CLAUDE.md?

Menos de 200 líneas y menos de 500 palabras de reglas densas. Pasados esos umbrales, el seguimiento de instrucciones de Claude se degrada — cada regla que añades hace que todas las demás tengan un poco menos de probabilidades de seguirse. Trátalo como un presupuesto fijo. Si necesitas más, divide en archivos CLAUDE.md de subdirectorio y usa @import para fragmentos compartidos.

¿Dónde debería poner CLAUDE.md?

El principal va en la raíz de tu proyecto (./CLAUDE.md) y se commitea. Añade archivos CLAUDE.md de subdirectorio para reglas específicas de aplicación en monorepos. Pon preferencias entre proyectos en ~/.claude/CLAUDE.md. Usa CLAUDE.local.md para anulaciones personales que no quieres commitear — pero recuerda añadirlo al gitignore manualmente.

¿Por qué Claude está ignorando mi CLAUDE.md?

El 90% de las veces es una de estas tres cosas: el archivo es demasiado largo (más de 200 líneas), las reglas son vagas ("escribe código limpio"), o las reglas no tienen un "por qué" que Claude pueda usar para aplicarlas. Ejecuta wc -l CLAUDE.md y luego audita la especificidad. Prueba los cambios en una sesión nueva pidiendo a Claude que resuma el archivo.

¿Debería usar CLAUDE.md o AGENTS.md?

Si tu equipo solo usa Claude Code, quédate con CLAUDE.md. Si usas dos o más CLIs de agentes (Codex, Cursor, Sourcegraph), cambia a AGENTS.md y crea un enlace simbólico de CLAUDE.md hacia él: ln -s AGENTS.md CLAUDE.md. La mayoría de los CLIs de agentes modernos hacen fallback a AGENTS.md, así que un solo archivo alimenta todas las herramientas.

¿Debería ejecutar /init para generar CLAUDE.md?

Sí — como borrador. No — como archivo terminado. /init escanea tu repo y produce un punto de partida, pero es verboso y genérico. Tanto Anthropic como HumanLayer recomiendan recortar agresivamente después de ejecutar /init. Los 8 minutos que pasas cortando y añadiendo líneas de "por qué" son donde el archivo se vuelve realmente útil.

¿Cómo funcionan los archivos CLAUDE.md en un monorepo?

El CLAUDE.md raíz se mantiene pequeño — solo punteros y reglas compartidas. Cada app obtiene su propio apps/*/CLAUDE.md con convenciones acotadas. Los archivos de subdirectorio se cargan de forma diferida solo cuando Claude lee archivos dentro de ese subárbol, por lo que los hermanos permanecen aislados. Usa @import .claude/rules/style.md para compartir fragmentos de reglas modulares sin duplicarlos entre apps.

¿Cuál es la diferencia entre CLAUDE.md, hooks y skills?

CLAUDE.md es contexto orientativo — Claude lo lee y generalmente lo sigue. Los hooks son acciones deterministas que siempre se disparan (formateo, bloqueo de commits). Los skills son capacidades empaquetadas para flujos de trabajo reutilizables con assets. Usa CLAUDE.md para guía de estilo, hooks para reglas duras, y skills para trabajos multi-paso que repetirás en varios proyectos.

Cómo lo Hace Techsy

En Techsy, todos los proyectos de Claude Code que entregamos tienen un CLAUDE.md de menos de 150 líneas y un enlace simbólico a AGENTS.md. Tratamos el archivo como código — lo versionamos, revisamos los cambios en PRs, y volvemos a probar en sesiones nuevas antes del merge. ¿Necesitas ayuda para conectar agentes de IA a tu flujo de desarrollo? Solicita una consulta gratuita.