# Regla: Sin duplicación de reglas globales en CLAUDE.md de proyecto

Esta regla es **OBLIGATORIA** y aplica al diseño/auditoría de cualquier
`CLAUDE.md` de proyecto donde el sistema SWL esté instalado. Extiende el
contrato canónico de `swl-claudemd` con un sub-caso específico: la
duplicación inline de reglas que ya viven en `~/.claude/rules/`.

---

## Principio

> Cuando una regla ya está documentada en `~/.claude/rules/` (carga global
> automática en todas las sesiones del usuario), **el `CLAUDE.md` del
> proyecto NO debe duplicarla inline**. La duplicación viola DRY a nivel
> de gobernanza, genera drift cuando la regla global se actualiza, y
> erosiona el contrato canónico de `CLAUDE.md` (≤200 LOC).

La regla global es **la fuente de verdad**. El `CLAUDE.md` del proyecto
puede referenciarla con `@~/.claude/rules/<archivo>.md` o agregar
**matices propios del proyecto**, pero NUNCA re-derivar el principio.

---

## Cuándo aplicar

OBLIGATORIO al:

- Crear un `CLAUDE.md` de proyecto nuevo (`/swl:claudemd init-project`,
  `/swl:nuevo-proyecto`, `/swl:adoptar-proyecto`).
- Modificar `CLAUDE.md` de proyecto inline (`/swl:aprender` Paso 6 Tipo A,
  edición manual del usuario, `Edit`/`Write` programático).
- Revisar `CLAUDE.md` (`/swl:claudemd audit`, `/swl:claudemd refactor`,
  hook `claudemd-bloat-detector`, hook `claudemd-duplicacion-detector`).

NO aplica al:

- `~/.claude/CLAUDE.md` (user-level) — ahí SÍ pueden declararse
  preferencias personales que parafrasean o complementan reglas globales.
- Documentación dentro del proyecto que no es `CLAUDE.md` (READMEs,
  ADRs, docs de feature) — ahí no aplica el contrato canónico.

---

## Catálogo de reglas globales conocidas

Las siguientes reglas globales se cargan automáticamente cada sesión y
NO deben duplicarse en `CLAUDE.md` de proyecto:

| Regla global | Sección canónica | Referencia para citar |
|---|---|---|
| `brevedad-output.md` | Idioma obligatorio: español de México | `@~/.claude/rules/brevedad-output.md § Idioma obligatorio` |
| `brevedad-output.md` | Brevedad y eficiencia de output | `@~/.claude/rules/brevedad-output.md § Brevedad` |
| `git-coauthor.md` | Sin co-autores en commits | `@~/.claude/rules/git-coauthor.md` |
| `arreglar-al-detectar.md` | Detectar → Informar → Arreglar | `@~/.claude/rules/arreglar-al-detectar.md` |
| `debatir-antes-de-aceptar.md` | Debatir decisiones que chocan con reglas | `@~/.claude/rules/debatir-antes-de-aceptar.md` |
| `usar-context7.md` | Consultar Context7 antes de dependencias | `@~/.claude/rules/usar-context7.md` |

Catálogo declarativo completo:
`scripts/lib/reglas-globales-conocidas.json`. El catálogo es la fuente
de verdad consumida por el auditor (`scripts/auditar-claudemd.js`) y el
hook (`hooks/claudemd-duplicacion-detector.js`).

---

## Qué SÍ es legítimo en CLAUDE.md de proyecto

Lo siguiente NO se considera duplicación y es bienvenido:

1. **Matiz local específico**: "Convenciones locales: identificadores
   técnicos en inglés (rutas, comandos), prosa en español." — el matiz
   es del proyecto, no la regla del idioma.
2. **Override explícito documentado**: "Override de
   `~/.claude/rules/brevedad-output.md` § Brevedad: este proyecto usa
   docstrings extendidos por requerimiento legal." — el override es
   explícito y nombra la regla global.
3. **Excepción acotada con justificación**: "Excepción a
   `~/.claude/rules/arreglar-al-detectar.md`: bugs cosméticos en el
   módulo legacy `X/` se difieren a Q3 por congelación." — la excepción
   nombra la regla y justifica.
4. **Referencia `@`**: `@~/.claude/rules/<archivo>.md` — incluir la
   regla por referencia, no inline.

---

## Cómo detectarlo

### Manual

```bash
node scripts/auditar-claudemd.js
# Buscar en el output: "duplicacion-reglas-globales"
```

### Automático

- **Auditor síncrono**: `scripts/auditar-claudemd.js` (dimensión 7,
  severidad WARN, no bloquea).
- **Hook async**: `hooks/claudemd-duplicacion-detector.js` (PostToolUse,
  emite nudge a `.planning/evolution/nudges.jsonl`).
- **Comando**: `/swl:claudemd audit` reporta el conteo; `/swl:claudemd
  refactor` propone el reemplazo concreto.

---

## Cómo remediar

1. **Identificar el bloque** señalado por el auditor (línea aproximada).
2. **Decidir**:
   - ¿El bloque es 100% paráfrasis de la regla global? → **eliminar**.
   - ¿El bloque agrega matiz local? → **reescribir como matiz corto**
     (≤3 líneas) que nombra la regla global ("Convenciones locales:
     <matiz>. Ver `@~/.claude/rules/<archivo>.md`.").
3. **Verificar**: re-ejecutar `node scripts/auditar-claudemd.js` hasta
   que la duplicación desaparezca.

---

## Anti-patrones

- **Copiar contenido de reglas globales "para que esté visible"**: la
  regla global YA está visible — se carga automáticamente. Copiarla en
  cada proyecto es deuda silenciosa.
- **Re-derivar el principio con palabras propias**: si dices "todo
  contenido generado debe ser en español de México con acentos
  correctos…" estás re-derivando `brevedad-output.md § Idioma`.
- **Bloque "Reglas de máxima prioridad" que repite reglas globales**:
  las reglas globales SON prioritarias por construcción — duplicarlas
  no aumenta su prioridad.
- **Idioma "Language" en inglés que dice "español"**: paradójico y
  duplica la regla.
- **Override implícito sin nombrar la regla global**: "este proyecto
  usa docstrings extendidos" sin decir que es override de qué.
- **Ignorar el WARN del auditor argumentando "es para claridad"**: el
  auditor lleva razón. La regla global es suficiente claridad.

---

## Relación con otras reglas

- `~/.claude/rules/memoria-consolidada.md § Reglas de no-duplicación`:
  principio general "un dato vive en exactamente un canal". Esta regla
  lo aplica al canal CLAUDE.md.
- `~/.claude/rules/fragmentos-compartidos.md`: la analogía a nivel de
  agentes (fragmentos `_*.md` se incrustan, no se duplican).
- `~/.claude/rules/skills-estandar.md`: la analogía a nivel de skills
  (skill referencia otro skill, no duplica su contenido).
- `reglas/auditorias-documentales-estructurales.md § Para prosa
  cuantificada en campos descriptivos`: hermana — verifica drift
  cross-manifest. Esta regla verifica drift cross-fuente.

---

## Origen de esta regla

Sesión 2026-05-22, swl-ses v1.7.0. El usuario pegó 4 fragmentos de
`CLAUDE.md` de distintos proyectos que repetían la misma regla de idioma
"español de México" en formas distintas (lista con bullets, H3 inline,
lista numerada, sección "Language" en inglés). El análisis reveló:

- La regla ya vivía en `~/.claude/rules/brevedad-output.md § Idioma
  obligatorio: español de México` desde sesiones previas.
- Cada proyecto la había re-derivado por iteraciones de
  `/swl:aprender` Tipo A sin que ningún check detectara la
  duplicación.
- El bloat acumulado en cada `CLAUDE.md` consumía 7-15 líneas que
  podían eliminarse sin perder semántica.

Resolución: crear el catálogo declarativo + detector + dimensión 7 del
auditor + hook PostToolUse + esta regla. Release v1.7.0 MINOR.

---

## Checklist al modificar CLAUDE.md de proyecto

- [ ] ¿El bloque que voy a agregar parafrasea una regla global de
      `~/.claude/rules/`?
- [ ] Si sí: ¿agrega matiz local genuino, o solo repite el principio?
- [ ] Si solo repite: NO agregar — la regla global ya aplica.
- [ ] Si agrega matiz: redactar en ≤3 líneas que **nombran la regla
      global** (referencia con `@~/.claude/rules/<archivo>.md`).
- [ ] Tras escribir: ejecutar `node scripts/auditar-claudemd.js` y
      confirmar 0 hallazgos `duplicacion-reglas-globales`.
