Saltar al contenido

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)
  1. Todo lo de CLAUDE.md se carga en cada sesión
  2. Qué sí va en CLAUDE.md
  3. Procedimientos a skills
  4. Reglas obligatorias a hooks
  5. Una plantilla corta de CLAUDE.md
  6. Cómo podar un CLAUDE.md existente
  7. Errores comunes
  8. Preguntas frecuentes
  9. Checklist

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.md importa 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 cargaQué entra al contexto
CLAUDE.md del proyecto, de tu usuario y de la organizaciónAl iniciar la sesiónEl contenido completo, en cada petición
CLAUDE.md de una subcarpetaAl leer, escribir o editar un archivo ahíEl contenido completo desde ese momento
.claude/rules/*.md sin pathsAl iniciar la sesiónIgual que .claude/CLAUDE.md
.claude/rules/*.md con pathsAl tocar un archivo que coincideSolo esa regla
SkillDescripción al iniciar; cuerpo al invocarlaPoco hasta que se usa
Skill con disable-model-invocation: trueSolo cuando escribes /nombreNada hasta entonces
HookEn su evento, por ejemplo antes de cada herramientaNada, salvo lo que el hook devuelva
Memoria automática (MEMORY.md)Al iniciar la sesiónLas primeras 200 líneas o 25 KB
qué entra al contexto, y cuándoinicio de sesión(y otra vez tras /compact)la tarea coincideo escribes /nombrecada evento, p. ej.antes de una herramientaCLAUDE.mdcontenido completo en cada peticiónskilldescripción desde el inicio; el cuerpo al usarlahookcorre fuera del contexto; solo entra lo que devuelvelo que se carga siempre, se paga siemprefuente: code.claude.com/docs, features-overview

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 /doctor propone 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.md con paths, 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.

un CLAUDE.md largo, repartido en tres sitiosCLAUDE.md≈400 líneas(ilustrativo)CLAUDE.mdhechos de cada sesión: comandos, convencionesse carga entero al iniciar cada sesión.claude/skills/<nombre>/SKILL.mdprocedimientos de varios pasosdescripción al iniciar; el cuerpo al usarla.claude/settings.json → hooksreglas que deben cumplirse siemprelas ejecuta Claude Code; no ocupan contextocada línea donde se carga cuando hace faltafuente: documentación de Claude Code (memoria, skills, hooks)

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.
  1. Las líneas --- abren y cierran el frontmatter en YAML.
  2. name es el comando que aparece en el menú /. Si lo omites, se usa el nombre de la carpeta.
  3. description es 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 y when_to_use juntas 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.
  4. 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.
  5. 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);
  1. "PreToolUse" es el evento: corre antes de cada llamada a una herramienta. "matcher": "Bash" lo limita a los comandos de terminal.
  2. "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.
  3. readFileSync(0) lee stdin, donde llega el JSON del evento con tool_name y tool_input.
  4. 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.
  5. La expresión busca npm o npx como palabra al inicio del comando o después de ;, &, |, ( o un salto de línea, así que atrapa cd app && npm test pero no pnpm test.
  6. 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. -->
  1. 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.
  2. "Comandos" es lo que Claude no puede adivinar: cómo se corre y qué tiene que pasar antes de terminar.
  3. "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 ask en los permisos.
  4. "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.
  5. 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:

  1. Mide. Cuenta líneas con wc -l CLAUDE.md y mira /context all para ver cuánto pesa cada archivo de memoria. Cuenta también los archivos importados con @.
  2. Marca candidatos. El script claude-md-check.mjs de 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".
  3. Decide el destino de cada línea con la tabla de abajo. El script solo señala; la decisión es tuya.
  4. Pide propuestas. /doctor propone 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.
  5. Prueba. Abre una sesión nueva, revisa /context all y 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}`);
  1. 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.
  2. 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.
  3. Dentro de un bloque de código no mira nada más, para no confundir un always de SQL con una regla.
  4. 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.
  5. steps cuenta líneas numeradas seguidas; al llegar a cuatro marca el inicio de la lista como procedimiento.
  6. 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 necesitaCLAUDE.md
Un procedimiento de varios pasos o material de referenciaUna 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 siempreUn hook, o una regla deny en permisos
Algo que Claude deduce del códigoSe borra
Una preferencia tuyaCLAUDE.local.md o ~/.claude/CLAUDE.md
CLAUDE.md, skill o hook: cómo se carganCLAUDE.mdskillhookse cargaal iniciar, enteroy tras /compactdescripción al iniciarcuerpo al usarlano entra: se ejecutaen cada eventocontextocada peticiónbajo hasta usarlacero, salvo lo quedevuelvequién decideClaude lo interpretaClaude, o tú con/nombreClaude Code, siempresirve parahechos y convencionesprocedimientosde varios pasosreglas que debencumplirse siempreuna regla en CLAUDE.md es una petición; un hook la hace cumplircada cosa en su capafuente: code.claude.com/docs/en/features-overview

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: true puede 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/ con paths.
  • 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 all en 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

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

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

← Blog