Qué se carga en la cabeza de Claude, cuándo se carga, y cómo CI mantiene todo honesto — para que nadie tenga que adivinar dónde vive una regla.
La idea en una frase: las reglas no son un PDF que nadie lee — se cargan automáticamente en el contexto de Claude según dónde estés trabajando, y una capa de guardrails en CI verifica que esas reglas existan, sean válidas y no se erosionen. Reglas que se aplican solas + verificación que no depende de la memoria de nadie.
Claude Code carga varias capas de instrucciones. Unas entran al arrancar la sesión; otras son perezosas (lazy) — solo entran cuando tocas un archivo que les corresponde. Cuando dos capas se contradicen, gana la más específica.
docs/adr/CLAUDE.md en una carpetaCLAUDE.md dentro de una subcarpeta. Carga solo cuando lees/editas un archivo en ese subárbol. Override de la raíz para esa área..claude/rules/*.md — reglas por dominiopaths: en el frontmatter. Cargan solo cuando tocas un archivo que matchea el glob — csharp.md al abrir un .cs, frontend-ui.md al tocar apps/**. Es el modelo oficial de Anthropic (ADR-0098). Ver Parte 2.docs/lookbook.mdCLAUDE.md — universal (~207 líneas)~/.claude/CLAUDE.md (por-dev)qiiub-doctor detecta esa deriva.La regla de oro de seguridad: como .claude/rules/ y los sub-CLAUDE.md son lazy, una regla que siempre debe aplicar — MerchantId-first, "nunca secretos en el código", el Security Checklist — se queda always-on en el root. Si la mueves a un archivo lazy, no estaría cargada hasta que alguien abra un archivo de ese tipo: un agujero silencioso. Esa es la política central del ADR-0098.
El root CLAUDE.md se redujo de 464 → 207 líneas moviendo las reglas de dominio a .claude/rules/. Un backend dev ya no carga las reglas de UI (≈39% del root viejo) que nunca usa, y viceversa. Archivos más livianos = Claude respeta mejor las reglas que sí aplican.
CLAUDE.md (universal + seguridad)src/QIIUB.Api/.../Endpoint.cssrc/**/* + **/*.csCLAUDE.md (universal + seguridad)apps/qiiub-portal/.../Page.tsxapps/** + packages/qiiub-ui/**Un archivo, dos subárboles hermanos. frontend-ui.md tiene paths: [apps/**, packages/qiiub-ui/**] — cubre las dos carpetas sin duplicar. Eso es lo que un sub-CLAUDE.md no puede hacer (está atado a su propia carpeta), y es la ventaja que probamos con el test T6c antes de confiar en ella.
Las reglas no sirven si se erosionan en silencio. Estos chequeos corren automáticamente — en tu máquina, en cada commit y en cada PR — para que la deriva rebote sola, sin depender de que alguien se acuerde de verificar.
main local está fresco (<24h)?CLAUDE.md tiene su header de versión?~/.claude)feat fix docs chore…)covers: sin doble-claim, refs válidas.claude/EXPECTED_CC_VERSION.* @jflores @mgandia)BLOCKED hasta el approve correcto.Dónde entra cada pieza, de principio a fin. Cada "gate" es un punto donde un guardrail verifica antes de dejar pasar.
Claude carga el cascade. Tú corres el doctor.
↳ qiiub-doctorLas reglas del dominio cargan solas según el path que tocas.
↳ .claude/rules/El hook valida el mensaje (prefijo + ≤50, sin atribución).
↳ commit-msgCI corre los guards + el lint; CODEOWNERS exige review.
↳ cascade-guards · lintSolo con el review correcto y CI verde. Decisiones grandes = ADR.
↳ CODEOWNERS · ADREl principio detrás de todo: CI es el límite de confianza, no los pre-commit hooks. Un hook se puede saltar (git commit crudo); el merge no. Por eso las reglas que de verdad importan se verifican en el PR, donde nadie las puede bypassear.
Todo el diseño descansa en comportamientos de carga de Claude Code. En vez de confiar en la doc, los validamos con fixtures reales (knowledge-cascade-behavior.md). "Replay-then-trust": se prueba antes de depender de ello, y se re-prueba en cada versión nueva.
El cascade carga cada CLAUDE.md desde el CWD hacia arriba.
En conflicto, el sub-CLAUDE.md más específico override la raíz.
Carga ≥30K tokens reales sin truncar (validado con relleno de alta entropía).
El sub-CLAUDE.md entra al primer Read/Edit en su subárbol.
Editar un CLAUDE.md cargado inyecta un diff-note; Claude usa lo nuevo.
.claude/rules/ carga solo en el path que matchea (incl. 2 subárboles hermanos, T6c).