Mi CLAUDE.md tiene 582 líneas. Seis capas y el fallo detrás de cada una

Cada chat nuevo de Claude Code empieza de cero. No conoce el proyecto, no recuerda lo que hablamos hace una hora en la ventana de al lado, y no tiene idea de que un puerto de un servidor no debe tocarse. Este post recorre el CLAUDE.md que construí para resolver eso: seis capas, el incidente que originó cada una, por qué un hook funciona donde una regla escrita falla, el único ajuste que mantuvo fuera de mi máquina un paquete npm comprometido, y qué partes conservaría en un proyecto normal. El 12 de abril de 2026, cuando salió el original en ruso, la configuración tenía 582 líneas.

Un CLAUDE.md debería resolver dos problemas a la vez: transportar contexto entre sesiones y evitar que el agente haga algo irreversible. r/ClaudeAI tiene cada semana una historia de terror nueva. Un agente tiró una base de datos de producción. Un agente subió secretos a un repositorio público. Un agente "optimizó" un servicio de facturación hasta que cada cliente recibió una factura a cero. Un CLAUDE.md típico de cinco a diez líneas no resuelve ninguno de los dos problemas. Decidí tratarlo como una tarea de arquitectura y no como una lista de deseos, y cada regla de ahí tiene una historia concreta detrás.

Tres incidentes detrás de las primeras reglas

El agente "arregló" un sistema que funcionaba. Domingo por la tarde. El agente ve 127.0.0.1 en la configuración de un servicio de almacenamiento externo y decide que una sesión anterior dejó un error allí. Pone la IP real. Las subidas se rompen. Media hora de depuración después resulta que el tráfico pasaba por un proxy SNI a través de un túnel local, y 127.0.0.1 era el valor correcto. Sin contexto, la solución obvia era el daño.

La regla que salió de ahí: no cambies una configuración hasta entender por qué los valores actuales son los que son. Si un valor parece raro, primero entiéndelo y después actúa.

fail2ban tomó al agente por un atacante de fuerza bruta. El agente comprobaba el estado del servidor y abría una conexión SSH nueva para cada comprobación. Una docena de conexiones en un minuto parecía un ataque, y la IP quedó baneada media hora. En esa máquina había un entrenamiento en marcha, y yo ya no podía llegar a ella.

Regla: un único puente SSH para todo, un cliente por sesión, y nada de scripts separados para comprobar, arreglar y verificar. Agrúpalos en una sola llamada.

"Filtrar" resultó significar "borrar". Pedí que se filtrara un conjunto de datos, es decir, que se quitaran las imágenes no aptas. El agente lo leyó al pie de la letra y borró los archivos. No los movió ni los marcó. Los borró.

Regla: filtrar significa mover o marcar, nunca borrar. Antes de cualquier borrado, comprueba que el usuario pidió borrar con esas palabras.

Escribir "ten cuidado" no funciona. Hace falta un sistema.

Seis capas, ninguna planificada

Cada capa apareció tras un fallo concreto.

Reglas, 9 archivos. Se cargan según la situación. Cuando el agente escribe un artículo no necesita las reglas de SSH; cuando depura código no necesita las reglas sobre prosa. Claude Code puede cargar el archivo de reglas que corresponde a la tarea.

Memoria, 78 archivos. Apareció cuando el agente olvidó por tercera vez la configuración de un servidor. Entre sesiones guarda ahora ajustes de infraestructura, decisiones del proyecto, mis preferencias y errores pasados. Los archivos se enlazan entre sí como [[filename]], 178 enlaces cruzados en total, así que el Markdown normal se convierte en un grafo de conocimiento. Una parte siempre se carga; el resto, por tema.

Handoffs. Aparecieron cuando un chat nuevo volvía directamente al callejón sin salida del chat anterior. Al cerrarse una sesión, el agente escribe un resumen: qué se hizo, qué NO funcionó (la parte valiosa) y una acción siguiente. Uno real, traducido del ruso:

## Session goal
Colour checker: CNN sweep + diffusion, first visual results.

## Done
- CNN baseline: median 1.99 deg (11M params, 21 MB)
- Sweep on 5 GPUs: crop128 (3.17), bs16 (2.04), lr3e-4 (NaN)
- Diffusion training started: epoch 5/50, loss 0.827

## Did NOT work
- EfficientNet-B0: hash mismatch in the Docker image
- lr=3e-4: NaN after epoch 10-13, no gradient clipping
- CNN, visually: three numbers give stray colour casts

## Next step
Inference script for diffusion + visual sheets with 24 patches

El chat siguiente lee unos 1.500 tokens en lugar de analizar el proyecto desde cero. En cuatro días se acumularon 27 handoffs, y ningún callejón sin salida se repitió. También funciona entre cuentas: tengo tres suscripciones, dos de trabajo y una personal, y un handoff me permite seguir en otra sin volver a explicarlo todo. Cómo esto creció hasta convertirse en una herramienta para varias personas trabajando a la vez está en Varios Claude en un mismo repo.

Crónicas. Aparecieron cuando, tras veinte handoffs, ya no estaba claro cómo había llegado el proyecto a su estado actual. Un handoff responde a "¿y ahora qué?"; una crónica responde a "¿cómo llegamos aquí?". Decisiones clave, giros y callejones sin salida, de tres a siete líneas por hito.

Hooks. Aparecieron cuando la regla "comprueba los enlaces de CLAUDE.md" dejó de cumplirse veinte minutos después de empezar una sesión. La siguiente sección trata de ellos.

Skills, 16. Conocimiento empaquetado para trabajos concretos. La descripción está escrita como un disparador para el modelo, "use when: GPU hung, server health check needed", y no como "ayuda con servidores".

Una regla es un deseo, un hook es una garantía

Esto fue lo menos obvio que aprendí en ese mes. Una regla en CLAUDE.md es una instrucción dentro de un prompt. El modelo puede olvidarla, reinterpretarla o descartarla tarde en una sesión larga, cuando el contexto está lleno de otras cosas. Mi regla de "comprueba los enlaces antes de trabajar" aguantó unos diez minutos, y luego el agente se metió de lleno en la tarea.

Un hook es un script de Python que Claude Code ejecuta ante un evento: SessionStart, Stop, PreToolUse. No olvida ni reinterpreta. Se ejecuta siempre. Este es el que pide un handoff antes de cerrar una sesión larga:

# remind_handoff.py  (Stop hook, simplified)
age = session_age_minutes()
if age < 15:
    return                      # short session, nothing to hand off

if fresh_handoff_exists():
    return                      # already written

print(json.dumps({              # block the close, ask for the handoff
    "decision": "block",
    "reason": f"Session ran {int(age)} min with no handoff. "
              f"Write one into .claude/handoffs/ before exiting."
}))

El modelo suele saber por sí mismo cuándo es el momento, cuando una tarea ha terminado o el contexto se está llenando. El hook cubre las veces que se le olvida.

Si algo tiene que pasar siempre, es un hook, no una regla.

Una línea de configuración frente a un ataque a la cadena de suministro

El 31 de marzo de 2026, el paquete oficial de npm axios, con unos 100 millones de descargas semanales, fue comprometido a través de la cuenta de un mantenedor (Elastic Security Labs). Una versión maliciosa 1.14.1 salió a las 00:21 UTC, y las versiones malas se quedaron en npm hasta las 03:15 UTC, unas tres horas (la autopsia de axios). Microsoft atribuye el ataque a Sapphire Sleet, un actor estatal norcoreano (Microsoft Security Blog).

Mi .npmrc tenía una sola línea:

min-release-age=7

Los paquetes publicados hace menos de siete días no se instalan. La mayoría de los paquetes maliciosos se detectan en uno a tres días, así que siete es un margen cómodo. No me afectó, y costó una línea. El equivalente en Python va en uv.toml:

exclude-newer = "7 days"

La investigación detrás: 37 artículos

Buena parte de las reglas no vinieron de mis propios errores, sino de trabajo académico: 37 artículos de arXiv reelaborados como principios. Cuatro de ellos cambiaron más mi flujo de trabajo.

• Bucle de verificación. El agente dice que las pruebas pasan; tú lo compruebas, y no pasan. El bucle de prueba prohíbe al agente dar por buena su propia obra. Necesita artefactos: la salida de las pruebas y un veredicto de un verificador en una sesión nueva que nunca vio el trabajo. Fuente: arXiv 2603.10165.
• Razonamiento estructurado. En lugar de un "quizás esto, quizás aquello" de texto libre: lo que sabemos con certeza por el código y los logs, una traza paso a paso, lo que se sigue de ahí, y qué hipótesis se probaron y se descartaron. En los experimentos de Ugare y Chandra, este tipo de razonamiento semiformal subió la precisión en equivalencia de parches del 78 % al 88 % en ejemplos seleccionados, y al 93 % en parches reales generados por agentes (arXiv 2603.01896).
• Orquestación determinista. Todo lo determinista, como pruebas, linters y formateo, se ejecuta mediante un script de shell. Un modelo pierde la cuenta en los bucles y confunde las condiciones de rama. Un script no.
• Líneas rojas. Las reglas ordinarias se interpretan con creatividad. Las líneas rojas son prohibiciones absolutas sin excepciones, cada una ligada a un incidente: no borrar sin confirmación, no cambiar configuraciones de producción sin entenderlas. El patrón viene de equipos de ingeniería chinos, 红线, literalmente "línea roja".

Lo demás, desde el generador-evaluador y la autoinvestigación hasta la descomposición multiagente, el contexto codificado, la seguridad de agentes y la integridad de la documentación, está descrito en el repositorio.

Cifras, y el lugar donde falló

78 archivos de memoria. 178 enlaces cruzados. 27 handoffs en cuatro días. Una tasa de aciertos de caché KV del 96,9 % en 83 sesiones en una semana. La configuración se mantiene sola: tras cada cambio, el agente comprueba si algún enlace quedó obsoleto, y un hook de SessionStart los valida automáticamente.

¿Funciona perfectamente? No. Una auditoría encontró cuatro archivos de memoria que se habían caído del índice. Deriva de la documentación, dentro del sistema construido para evitar la deriva de la documentación. Sin el sistema habría sido peor.

Lo que no tengo claro

No estoy convencida de que todo el mundo necesite todo esto. Para la mayoría de los proyectos bastarían probablemente cinco principios: orquestación determinista, razonamiento estructurado, defensa de la cadena de suministro, contexto codificado y handoffs.

Tampoco estoy convencida de que seis capas sea el mínimo. Puede que lo haya sobredimensionado. Pero en ese mes no se perdió contexto y no volvió ningún callejón sin salida.

Uno de los principios, la prueba de supuestos, lo dice claramente. Cada componente de la configuración codifica un supuesto sobre lo que el modelo no puede hacer por sí solo, y los modelos mejoran. Quita componentes y mide. Probablemente alguna capa de aquí ya sobra.

Qué cambió después de abril

Actualización, septiembre de 2026. El repositorio pasó de llamarse claude-code-config a codex-claude-code-config, porque los mismos principios, hooks y skills ahora también dirigen Codex y sesiones mixtas de Claude y Codex, y el nombre antiguo ya no lo describía. La URL antigua sigue redirigiendo. El 23 de septiembre de 2026 contenía 30 principios, 58 skills, 35 archivos de reglas y 73 scripts en hooks/, con 150 estrellas y 24 forks en GitHub.

Las cifras de las secciones anteriores (9 archivos de reglas, 78 archivos de memoria, 16 skills, 37 artículos, 582 líneas) describen mi configuración del 12 de abril. Eran ciertas ese día, y las he dejado como estaban.

Por dónde empezar

Pega esto en un chat de Claude Code:

https://github.com/AnastasiyaW/codex-claude-code-config - study it, pick what fits my work and set up my Claude Code

Empieza poco a poco: defensa de la cadena de suministro (una línea en .npmrc), orquestación determinista (pruebas mediante scripts) y razonamiento estructurado (un formato para depurar). Añade el resto cuando un fallo lo pida. Todo está bajo licencia MIT.

La página del proyecto en esta web es codex-claude-code-config. La biblioteca de referencia que creció a su lado se describe en 785 artículos para agentes, no para personas, y por qué confío más en los handoffs que en el historial de sesiones de la propia app de escritorio se explica en 45 MB de sesiones de Claude Code que nunca miras.