Tu CLAUDE.md es demasiado largo: procedimientos a skills y reglas a hooks
En la práctica/ 17 min de lectura
CLAUDE.md se carga completo en cada sesión. Deja ahí los hechos, pasa los procedimientos a skills que se cargan al usarlas y las reglas obligatorias a hooks.
- Claude Code
- IA
En este artículo (9)
Tu CLAUDE.md se carga completo al inicio de cada sesión de Claude Code y ocupa contexto en cada petición, lo uses o no. Déjalo en hechos que toda sesión necesita: comandos, convenciones y estructura. Los procedimientos van a skills, que se cargan al usarlas, y las reglas obligatorias a hooks, que Claude Code ejecuta siempre.
Aquí verás qué se carga y cuándo, según la documentación de Claude Code revisada el 19 de noviembre de 2026, una plantilla corta, un ejemplo de skill, un hook en Node que probamos y un método para podar el archivo que ya tienes. Si tu repo usa AGENTS.md, cómo conviven los dos archivos está en la guía de AGENTS.md; aquí no lo repetimos.
Todo lo de CLAUDE.md se carga en cada sesión
La página de memoria de Claude Code lo dice sin rodeos: los CLAUDE.md y CLAUDE.local.md del directorio donde abres Claude Code y de todos los directorios superiores se cargan al iniciar, junto con tu ~/.claude/CLAUDE.md y el de la organización si existe. No se reemplazan entre sí: se concatenan, del más general al más cercano. Los CLAUDE.md de subcarpetas llegan después, cuando Claude lee, escribe o edita un archivo dentro de esa subcarpeta.
Tres detalles cambian cómo deberías escribirlo:
- Es contexto, no configuración. La documentación dice que Claude trata estos archivos como contexto y no como configuración que se hace cumplir. Si algo debe bloquearse diga lo que diga Claude, la propia página manda a un hook
PreToolUse. - Más largo no es más claro. La recomendación es menos de 200 líneas por archivo: los archivos largos consumen más contexto y reducen el apego a las instrucciones. Si pasas del largo recomendado, Claude Code te avisa al iniciar y en
/status. - Los imports no ahorran nada. Una línea con
@docs/git.mdimporta ese archivo (rutas relativas al archivo que importa, hasta cuatro saltos), pero el contenido importado se carga junto con el CLAUDE.md. Ordena, no adelgaza.
Lo que sí no cuesta: los comentarios HTML de bloque (<!-- nota -->) se eliminan antes de llegar al contexto, así que sirven para notas a quien mantiene el archivo. Y el CLAUDE.md de la raíz del proyecto sobrevive a /compact: Claude Code lo vuelve a leer del disco. Para ver qué cargó tu sesión, usa /context all y revisa la lista de archivos de memoria.
La página Extend Claude Code resume el costo de cada pieza. Esta tabla junta lo que dicen las tres páginas:
| Qué | Cuándo se carga | Qué entra al contexto |
|---|---|---|
| CLAUDE.md del proyecto, de tu usuario y de la organización | Al iniciar la sesión | El contenido completo, en cada petición |
| CLAUDE.md de una subcarpeta | Al leer, escribir o editar un archivo ahí | El contenido completo desde ese momento |
.claude/rules/*.md sin paths | Al iniciar la sesión | Igual que .claude/CLAUDE.md |
.claude/rules/*.md con paths | Al tocar un archivo que coincide | Solo esa regla |
| Skill | Descripción al iniciar; cuerpo al invocarla | Poco hasta que se usa |
Skill con disable-model-invocation: true | Solo cuando escribes /nombre | Nada hasta entonces |
| Hook | En su evento, por ejemplo antes de cada herramienta | Nada, salvo lo que el hook devuelva |
Memoria automática (MEMORY.md) | Al iniciar la sesión | Las primeras 200 líneas o 25 KB |
Desliza la figura para verla completa
Qué sí va en CLAUDE.md
La documentación pone el criterio así: hechos que Claude debe tener en cada sesión, como comandos de build, convenciones, estructura del proyecto y reglas del tipo "siempre haz X". Si una entrada es un procedimiento de varios pasos o solo importa en una parte del código, va a una skill o a una regla con paths. Y sugiere cuándo agregar algo: cuando Claude comete el mismo error dos veces, cuando una revisión de código atrapa algo que Claude debió saber, o cuando escribes en el chat la misma corrección que la sesión anterior.
Escribe instrucciones que se puedan comprobar. "Usa 2 espacios de sangría" funciona; "formatea bien el código" no. "Los handlers de la API viven en app/api/" funciona; "mantén el orden" no. Si dos instrucciones se contradicen, Claude puede elegir una al azar, así que revisar el archivo es parte de mantenerlo.
Lo que sobra en la mayoría de los CLAUDE.md que se vuelven largos:
- Lo que Claude deduce del código. El árbol de carpetas, la lista de dependencias y la descripción general de la arquitectura. El chequeo
/doctorpropone justo esos recortes en un CLAUDE.md versionado, y conserva las trampas, las razones y las convenciones que difieren de los valores por defecto. - Procedimientos. Cómo publicar una versión, cómo crear una migración, cómo preparar un despliegue: van a una skill.
- Reglas de una carpeta. Las convenciones de
app/api/van a.claude/rules/api.mdconpaths, y solo se cargan cuando Claude toca esos archivos. - Lo personal. Tus URLs de prueba o tus datos de ejemplo van en
CLAUDE.local.md, fuera de git. - La tarea de hoy. Los criterios de aceptación de un cambio concreto van en una especificación, no en el archivo que lee cada sesión.
Si heredaste un proyecto, CLAUDE.md es donde dejas lo que aprendiste al leerlo: los comandos que funcionan y las trampas que no se ven en el código. Cómo hacer esa primera lectura está en entender un repositorio heredado con Claude Code.
Desliza la figura para verla completa
Procedimientos a skills
Una skill es una carpeta con un SKILL.md: en .claude/skills/<nombre>/ para el proyecto o en ~/.claude/skills/<nombre>/ para todos tus proyectos. Al iniciar, Claude solo ve su nombre y su descripción. El cuerpo se carga cuando escribes /nombre o cuando Claude decide que la descripción coincide con tu tarea. La documentación lo resume así: a diferencia de CLAUDE.md, el cuerpo de una skill solo se carga cuando se usa, así que el material largo casi no cuesta hasta que lo necesitas.
Así queda una sección de "cómo crear una migración" sacada de CLAUDE.md. Los comandos son de un proyecto de ejemplo; cámbialos por los tuyos:
---
name: nueva-migracion
description: Crea una migración de base de datos y la prueba. Úsala cuando haya que crear o cambiar una tabla, una columna o un índice.
---
# Crear una migración
1. Crea db/migrations/NNNN_nombre_corto.sql con el siguiente número libre.
2. Escribe el cambio para que pueda correr dos veces: create table if not exists, add column if not exists.
3. Nunca edites una migración que ya está en main: crea una nueva.
4. Corre pnpm db:migrate contra la base local y después pnpm test.
5. Responde con el nombre del archivo y el resultado de las pruebas.
- Las líneas
---abren y cierran el frontmatter en YAML. namees el comando que aparece en el menú/. Si lo omites, se usa el nombre de la carpeta.descriptiones lo único que Claude ve en cada sesión, y con eso decide si cargar la skill. Pon primero qué hace y después cuándo usarla, con las palabras que dirías al pedirlo. En el listado, la descripción ywhen_to_usejuntas se cortan a 1,536 caracteres, y si tienes muchas skills Claude Code recorta las descripciones de las que menos usas para caber en un presupuesto del 1% de la ventana de contexto.- El cuerpo son los pasos. Se carga una vez, entra a la conversación y se queda; Claude Code no vuelve a leer el archivo en turnos siguientes.
- El paso 3 es una regla, pero solo importa al migrar, así que vive aquí y no en CLAUDE.md.
Para procedimientos con efectos, como un despliegue, agrega disable-model-invocation: true: Claude no puede invocarla por su cuenta y su descripción ni siquiera entra al contexto; solo corre cuando escribes /deploy. Mantén SKILL.md por debajo de 500 líneas y manda la referencia larga a archivos de apoyo dentro de la carpeta. Después de compactar la conversación, Claude Code vuelve a adjuntar los primeros 5,000 tokens de cada skill invocada, con un tope de 25,000 entre todas, así que pon lo importante arriba. Tus archivos viejos de .claude/commands/ siguen funcionando.
Reglas obligatorias a hooks
"Nunca uses npm" en CLAUDE.md es una petición. La página de funciones lo dice así: una instrucción como "nunca edites .env" en CLAUDE.md o en una skill es una petición, no una garantía; un hook PreToolUse que bloquea la edición es lo que la hace cumplir. Un hook es un comando que Claude Code ejecuta en un evento, sin que Claude decida, y no ocupa contexto salvo lo que devuelva.
Este hook bloquea npm y npx en un repo que usa pnpm. Va en .claude/settings.json, que se versiona para todo el equipo:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "node",
"args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/no-npm.mjs"]
}
]
}
]
}
}
// Hook PreToolUse: este repo usa pnpm, así que bloquea cualquier comando de Bash que corra npm o npx.
import { readFileSync } from "node:fs";
let input;
try {
input = JSON.parse(readFileSync(0, "utf8")); // Claude Code manda el evento como JSON por stdin
} catch {
process.exit(0); // entrada ilegible: sin decisión, sigue el flujo normal de permisos
}
const command = input.tool_input?.command ?? "";
// npm o npx al inicio del comando o después de ; & | ( o un salto de línea
if (/(^|[;&|(\n]\s*)(npm|npx)(\s|$)/.test(command)) {
console.error("Este repo usa pnpm. Usa pnpm en lugar de npm, y pnpm dlx en lugar de npx.");
process.exit(2); // salida 2 en PreToolUse: la llamada se bloquea y Claude lee stderr
}
process.exit(0);
"PreToolUse"es el evento: corre antes de cada llamada a una herramienta."matcher": "Bash"lo limita a los comandos de terminal."command": "node"con"args"es la forma sin shell: Claude Code sustituye${CLAUDE_PROJECT_DIR}por la raíz del proyecto como texto plano, así que la misma línea sirve en Git Bash y en PowerShell.readFileSync(0)lee stdin, donde llega el JSON del evento contool_nameytool_input.- Si el JSON no se puede leer, el script sale con 0 y sin salida: según la documentación eso no aprueba nada, solo deja la llamada en el flujo normal de permisos.
- La expresión busca
npmonpxcomo palabra al inicio del comando o después de;,&,|,(o un salto de línea, así que atrapacd app && npm testpero nopnpm test. - Con salida 2, Claude Code bloquea la llamada y le pasa a Claude el texto de stderr. Por eso el mensaje dice qué usar en lugar de npm: Claude corrige el comando en el siguiente intento.
Lo probamos pasándole JSON a mano, sin abrir Claude Code:
$ echo '{"tool_name":"Bash","tool_input":{"command":"cd app && npm test"}}' | node .claude/hooks/no-npm.mjs; echo "exit $?"
Este repo usa pnpm. Usa pnpm en lugar de npm, y pnpm dlx en lugar de npx.
exit 2
$ echo '{"tool_name":"Bash","tool_input":{"command":"pnpm test"}}' | node .claude/hooks/no-npm.mjs; echo "exit $?"
exit 0
Límites que conviene conocer. Cualquier otro código de salida distinto de 0 y 2 no bloquea: la acción sigue. Un hook que se pasa de su tiempo (600 segundos por defecto) tampoco bloquea. Y la expresión no ve un npm que corre dentro de un script, ni sudo npm. Es una guarda para la regla, no un sandbox. Si solo quieres prohibir un comando sin explicar la alternativa, una regla deny basta: está en permisos de Claude Code en settings.json. Para proteger archivos como .env, el caso completo está en el hook que protege .env.
Una plantilla corta de CLAUDE.md
Con los procedimientos en skills y las reglas en hooks, lo que queda cabe en una pantalla. Esta es la plantilla para el proyecto de ejemplo:
# Tienda: frontend
Next.js 15 con App Router y TypeScript estricto. Gestor de paquetes: pnpm.
## Comandos
- Desarrollo: pnpm dev
- Antes de dar algo por terminado: pnpm test y pnpm typecheck
## Convenciones
- Server Components por defecto; "use client" solo si hay estado o eventos.
- Los precios se guardan en centavos enteros y se formatean solo en la UI.
- No hagas commit ni push sin que te lo pida.
## Dónde está cada cosa
- Rutas de API en app/api/. Lógica compartida en lib/.
- Migraciones: sigue la skill nueva-migracion.
- Despliegue: lo hago yo con /deploy; tú no despliegues.
<!-- Para quien mantiene este archivo (no llega a Claude):
el bloqueo de npm y npx vive en .claude/hooks/no-npm.mjs. -->
- La primera línea y el párrafo dicen qué es el proyecto y con qué se construye. Nada más: el resto Claude lo lee del código.
- "Comandos" es lo que Claude no puede adivinar: cómo se corre y qué tiene que pasar antes de terminar.
- "Convenciones" son decisiones que no se ven en un solo archivo, escritas de forma que se puedan comprobar. Si "no hagas commit" tiene que cumplirse siempre, ponlo además como regla
asken los permisos. - "Dónde está cada cosa" apunta a las skills. La de migraciones Claude ya la ve por su descripción; la de despliegue no, porque tiene
disable-model-invocation, así que la línea le dice que no despliegue. - El comentario HTML explica a las personas por qué no hay regla de npm en el archivo. Claude Code lo quita antes de cargarlo.
Cómo podar un CLAUDE.md existente
No reescribas de memoria. Mide, clasifica cada línea y mueve. El método:
- Mide. Cuenta líneas con
wc -l CLAUDE.mdy mira/context allpara ver cuánto pesa cada archivo de memoria. Cuenta también los archivos importados con@. - Marca candidatos. El script
claude-md-check.mjsde abajo (Node, sin dependencias) lista las secciones más largas y marca las listas numeradas de cuatro pasos o más, los bloques de código largos y las líneas con "nunca", "siempre" o "must". - Decide el destino de cada línea con la tabla de abajo. El script solo señala; la decisión es tuya.
- Pide propuestas.
/doctorpropone recortes para un CLAUDE.md versionado, y/doctor prompt-audit(desde la versión 2.1.283) busca instrucciones viejas, archivos o comandos que ya no existen y contradicciones entre archivos. No cambia nada hasta que se lo pides. - Prueba. Abre una sesión nueva, revisa
/context ally pide una tarea que use un procedimiento que moviste. Si Claude no carga la skill, mejora su descripción.
Guárdalo como claude-md-check.mjs y córrelo con node claude-md-check.mjs CLAUDE.md:
// Usage: node claude-md-check.mjs [path/to/CLAUDE.md]
// Prints size, the longest sections, and lines worth moving out of CLAUDE.md.
import { readFileSync } from "node:fs";
const file = process.argv[2] ?? "CLAUDE.md";
const lines = readFileSync(file, "utf8").trimEnd().split(/\r?\n/);
console.log(`${file}: ${lines.length} lines${lines.length > 200 ? " (over the 200-line target)" : ""}`);
const sections = [];
const flags = [];
let inCode = false, codeStart = 0, steps = 0;
lines.forEach((line, i) => {
const n = i + 1;
if (line.startsWith("```")) {
if (inCode && n - codeStart > 6) flags.push([codeStart, `code block of ${n - codeStart - 1} lines -> skill`]);
inCode = !inCode;
codeStart = n;
return;
}
if (inCode) return;
if (/^#{1,3} /.test(line)) sections.push({ title: line, start: n });
steps = /^\s*\d+[.)] /.test(line) ? steps + 1 : 0;
if (steps === 4) flags.push([n - 3, "numbered procedure -> skill"]);
if (/\b(never|always|must|do not|don't|nunca|siempre|no hagas)\b/i.test(line)) flags.push([n, "hard rule -> hook if it must hold every time"]);
});
sections.forEach((s, i) => (s.size = (sections[i + 1]?.start ?? lines.length + 1) - s.start));
console.log("\nLongest sections:");
for (const s of [...sections].sort((a, b) => b.size - a.size).slice(0, 5)) console.log(` ${String(s.size).padStart(4)} ${s.title}`);
console.log("\nCandidates to move:");
for (const [n, why] of flags.sort((a, b) => a[0] - b[0])) console.log(` line ${n}: ${why}`);
- Lee el archivo, quita el salto final y lo parte en líneas. Si pasa de 200, lo dice en la primera línea de la salida.
- Recorre las líneas una vez. Una línea que empieza con tres comillas invertidas abre o cierra un bloque de código; al cerrarlo, si tenía más de cinco líneas, lo marca como candidato a skill.
- Dentro de un bloque de código no mira nada más, para no confundir un
alwaysde SQL con una regla. - Cada encabezado
#,##o###abre una sección. Al final, el tamaño de cada sección es la distancia hasta la siguiente, y se imprimen las cinco más largas. stepscuenta líneas numeradas seguidas; al llegar a cuatro marca el inicio de la lista como procedimiento.- Las líneas con "never", "always", "must", "nunca", "siempre" o "no hagas" se marcan como posibles hooks. Es una pista: tú decides si la regla debe cumplirse siempre.
Esto devolvió el script con un CLAUDE.md de ejemplo de 32 líneas (ilustrativo):
$ node claude-md-check.mjs CLAUDE.md
CLAUDE.md: 32 lines
Longest sections:
10 ## Migraciones
7 ## Proceso de release
5 ## Convenciones
4 # Tienda: frontend
4 ## Comandos
Candidates to move:
line 11: hard rule -> hook if it must hold every time
line 12: hard rule -> hook if it must hold every time
line 15: numbered procedure -> skill
line 22: code block of 6 lines -> skill
La línea 11 ("Nunca uses npm en este repo") pasa al hook de arriba. La 12 ("Siempre corre pnpm test antes de dar algo por terminado") se queda: es una convención que Claude puede seguir y que no se bloquea con un PreToolUse. La 15 abre el proceso de release, que pasa a una skill con disable-model-invocation. La 22 es una plantilla SQL, que va dentro de la skill de migraciones.
| Si la línea es… | Va a |
|---|---|
| Un comando, una convención o un dato que toda sesión necesita | CLAUDE.md |
| Un procedimiento de varios pasos o material de referencia | Una skill en .claude/skills/ |
| Un procedimiento con efectos (desplegar, publicar) | Una skill con disable-model-invocation: true |
| Una regla que solo aplica a una carpeta o tipo de archivo | .claude/rules/ con paths |
| Una regla que debe cumplirse siempre | Un hook, o una regla deny en permisos |
| Algo que Claude deduce del código | Se borra |
| Una preferencia tuya | CLAUDE.local.md o ~/.claude/CLAUDE.md |
Desliza la figura para verla completa
Errores comunes
- Partir el archivo con imports y creer que ya es corto. Lo importado se carga con el CLAUDE.md que lo importa; el costo es el mismo.
- Escribir reglas obligatorias como texto. Si una regla tiene que cumplirse siempre, un texto en CLAUDE.md no lo garantiza. Usa un hook o una regla de permisos.
- Descripciones de skill vagas. "Ayuda con la base de datos" no le dice a Claude cuándo cargarla. Pon qué hace y cuándo usarla, con las palabras que usarías al pedirlo.
- Dejar que Claude invoque un despliegue. Una skill con efectos sin
disable-model-invocation: truepuede correr cuando Claude cree que el código está listo. - Un hook que falla en silencio. Un error que sale con código 1 no bloquea nada. Prueba el script con JSON a mano antes de confiar en él.
- Copiar el árbol de carpetas en CLAUDE.md. Claude lo lee del repositorio y la copia queda vieja en la siguiente refactorización.
Preguntas frecuentes
¿Cuántas líneas debería tener mi CLAUDE.md?
La documentación de Claude Code recomienda menos de 200 por archivo. No es un límite duro: por encima Claude Code te avisa, porque un archivo largo consume más contexto y reduce el apego a las instrucciones. Lo que cuenta es que cada línea le sirva a todas las sesiones.
¿Las skills consumen contexto aunque no las use?
Un poco: su nombre y su descripción están en cada petición para que Claude sepa que existen. El cuerpo solo entra cuando se usa. Con disable-model-invocation: true ni la descripción entra, y la skill solo corre cuando escribes su nombre.
¿Un hook puede reemplazar a CLAUDE.md?
No. El hook hace cumplir una regla concreta en un evento concreto, pero no le explica a Claude cómo trabajar en tu proyecto. Usa los dos: CLAUDE.md dice qué se espera y el hook impide lo que nunca debe pasar.
¿Qué diferencia hay entre .claude/rules y una skill?
Una regla sin paths se carga al iniciar, como CLAUDE.md, y una con paths cuando Claude toca un archivo que coincide. Una skill se carga cuando la invocas o cuando su descripción coincide con la tarea. Las reglas son para convenciones de una parte del código; las skills, para procedimientos y referencia.
Checklist
- El CLAUDE.md tiene menos de 200 líneas, contando lo importado con
@. - Solo tiene comandos, convenciones y datos que toda sesión necesita.
- Cada procedimiento de varios pasos vive en una skill con una descripción concreta.
- Las skills con efectos llevan
disable-model-invocation: true. - Las reglas de una carpeta están en
.claude/rules/conpaths. - Las reglas que deben cumplirse siempre son hooks o reglas de permisos, probados con JSON a mano.
- Las notas para personas van en comentarios HTML.
- Revisaste
/context allen una sesión nueva después de podar.
¿Viste esto en Instagram? Todas las guías de los Reels están en ecomlabs.dev/guias.
Escrito por

Publicado el 19 de noviembre de 2026 · actualizado el 20 de noviembre de 2026