6 CLAUDE.md en Claude Code: ganó el de 65 líneas

Tengo seis CLAUDE.md en mis repositorios locales. El más corto son 65 líneas. El más largo son 559. Esta semana me senté a ver qué contiene cada uno y cuál es el que uso con menos fricción. El resultado no fue el que esperaba: el que uso con cero fricción es el de 65 líneas.

Durante meses leí a varias personas de la comunidad de agentes IA argumentar que CLAUDE.md debe ser denso y exhaustivo. “Si no está escrito, el modelo no lo sabe.” Me creí ese argumento y mis archivos crecieron. Después hice la medición y vi que crecer era parte del problema.

Qué medí (y qué tengo verificado)

Seis repos activos en mi laptop. Para cada uno medí tres cosas con wc -l, un grep de secciones y un parser de bloques de código. Los números salen de los archivos reales en ~/repos/ del 2026-10-12. Los puedes reproducir uno a uno si tienes CLAUDE.md en varios repos.

El de 559 líneas de sns-operations tiene 52 secciones. El de 65 líneas de kenimoto-dev tiene 6. Un orden de magnitud de diferencia en superficie, con la misma cantidad de “reglas con penalización real” (unas 15-20 en cada uno, las conté a mano).

Por qué el de 65 me resulta menos frustrante

Lo que sigue es observación mía trabajando a diario con los seis repos. Vale como hipótesis, con los límites que eso implica. Tres patrones que noto repetirse:

1. Densidad de reglas vs. densidad de texto

En kenimoto-dev las 65 líneas son casi todas reglas con penalización concreta (“usa .cat-dot, no emoji, el build te va a cortar”). En sns-operations una fracción pequeña de las 559 líneas son reglas; el resto son ejemplos, plantillas y flujos ilustrativos. Si tengo 15 reglas en 65 líneas vs 20 reglas en 559 líneas, la “razón señal/ruido” baja casi 10×. El modelo tiene que distinguir regla de ejemplo, y gasta atención en esa clasificación.

2. Context rot empieza mucho antes de llenar la ventana

Como medí en japonés hace meses, Chroma publicó datos de que a 50K tokens ya hay degradación medible en todos los modelos frontier. Opus 4.7 tiene 1M, pero la zona útil real está muy por debajo. Cada línea del CLAUDE.md compite por esa capacidad de atención, antes de que yo escriba el primer prompt.

3. Las plantillas envejecen más rápido que las reglas

El sns-operations tiene plantillas de “cómo escribir un post de X” con ejemplos completos. Esos ejemplos los escribí en mayo. Hoy ya no uso ese formato. Cuando le pido al agente que escriba un post, a veces copia el ejemplo viejo porque está ahí, textual, en el archivo. En kenimoto-dev no hay ejemplos de artículos: solo las reglas de formato con un puntero a docs/article-formats.md.

Cómo distinguir regla de plantilla (test de 15 segundos)

El criterio que uso ahora para decidir qué va en CLAUDE.md:

• Regla: si el agente la rompe, hay una penalización verificable (build cae, test rojo, PR bloqueado, auditor humano reclama).
• Plantilla: si el agente la rompe, se ve raro pero funciona.

Las reglas van en CLAUDE.md. Las plantillas van en playbooks/ o docs/ donde se cargan bajo demanda cuando el agente las necesita.

Con ese criterio, de las 559 líneas de sns-operations sobran como 300. El problema es la ubicación: viven en el archivo que se lee al abrir el repo cuando por su función deberían ser material de consulta.

Mi plan para esta semana

No voy a cortar sns-operations de 559 a 65 de golpe. Eso sería ingenuo. Mi plan es:

1. Marcar cada sección como “regla” o “plantilla”. Pre-conteo rápido: ~60% es plantilla.
2. Mover las plantillas a playbooks/ donde ya viven otras plantillas que Claude lee bajo demanda vía skills.
3. Agregar una regla al CLAUDE.md reducido: “si vas a escribir un post, lee playbooks/platforms/<plataforma>.md primero.”

Objetivo realista: 220 líneas. sns-operations tiene más superficie legítima que kenimoto-dev.

Si el plan funciona, voy a volver a este post en un mes con el antes y después medido con el mismo método (líneas, secciones, % code).

Qué hacer en tu laptop esta tarde

Es un test de 15 minutos.

1. Lista tus CLAUDE.md: find ~ -name CLAUDE.md -not -path '*/node_modules/*' | xargs wc -l | sort -n.
2. Para el más largo, abre el archivo y marca cada sección: ¿es regla con penalización o es plantilla/ejemplo?
3. Mueve las plantillas a un directorio que el modelo lea bajo demanda (playbooks/, docs/, lo que uses).

Si tu archivo largo tiene más del 50% en plantillas, ahí está la deuda técnica de tu Context Engineering.

Qué no estoy diciendo

Nunca dije que los CLAUDE.md deban tener 65 líneas. La tesis es otra: lo que escribas ahí compite por atención con la sesión, así que ahí solo van reglas con penalización. Las plantillas y los ejemplos tienen su lugar en archivos que el modelo lee bajo demanda. CLAUDE.md se lee automáticamente al abrir el repo y por eso tiene que ser denso en reglas.

Un CLAUDE.md de 65 líneas con 15 reglas concretas gana en claridad a uno de 559 con 20 reglas diluidas entre 10 plantillas. La diferencia la paga tu agente leyendo basura antes de ayudarte.

Resumen

• 6 CLAUDE.md míos miden entre 63 y 559 líneas. El de 559 tiene 52 secciones y 26% en bloques de código (plantillas). El de 65 tiene 6 secciones.
• El archivo más corto es el que uso con menos fricción. Lo tomo como observación personal, y concuerda con lo que la investigación de context rot predice.
• Plan: mover las plantillas de sns-operations fuera del CLAUDE.md y volver a medir en un mes.
• Regla para decidir qué va: si al romperla hay penalización verificable, es regla y va en CLAUDE.md. Si solo “se ve raro”, es plantilla y va a playbooks/.

ken imoto · WebRTC & Voice AI engineer · kenimoto.dev