---
name: swl-claudemd
description: Conocimiento operacional para auditar y mantener archivos CLAUDE.md — contrato canónico de secciones (best practices Anthropic, ADR-0016), umbrales de bloat (líneas totales, bullets gigantes, placeholders, @references rotas), reglas de extracción a archivos referenciados con @, y plantillas de inicialización (init-user para ~/.claude/CLAUDE.md, init-project para CLAUDE.md raíz detectando stack). Provee las reglas; el comando /swl:claudemd ejecuta el flujo. Cargar desde ese comando o cuando el hook claudemd-bloat-detector sugiera intervención.
version: "1.2.0"
herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
exclusiones:
  - "No cargar para editar reglas globales en ~/.claude/rules/ — usar Edit directo."
  - "No cargar para crear ADRs — usar habilidades/doc-coauthoring o Write directo."
  - "No cargar para validar otros archivos (.md de docs, READMEs) — solo CLAUDE.md tiene contrato canónico."
  - "No cargar para generar el bloque del installer en CLAUDE.md de proyectos destino — eso lo hace scripts/lib/transformadores/claude.js."
evolvable: true
evolved: true
evolved-from: "1.1.0"
evolved-at: "2026-05-22"
evolved-by: "aprender"
evolved-note: "Dimensión 8 — detección de duplicación de reglas globales (catálogo declarativo en scripts/lib/reglas-globales-conocidas.json). Refactor propone reemplazo canónico. Hook claudemd-duplicacion-detector.js complementa la capa async. Aplica regla nueva reglas/sin-duplicacion-reglas-globales.md (v1.7.0)."
---

# Habilidad: Tratamiento profesional de CLAUDE.md

## Propósito

Aplicar las cinco recomendaciones del video oficial Anthropic
*"The CLAUDE.md file"* (`temp/YouTube · O0FGCxkHM-U.md`) como mecanismo
verificable y mantenible:

1. **Compacto** — empieza sin uno, agrega solo lo que tengas que corregir
2. **Stack arriba** — lenguaje, framework, ORM, BD
3. **Commands** — cómo correr dev, tests, lint, build
4. **Code style** — convenciones de indentación, exports, nombrado
5. **Conventions** — dónde van las cosas, qué patrones preferir

Más dos prácticas auxiliares del video:

- **`@filepath`** para referenciar docs en lugar de duplicar contenido
- **"Ask Claude to save to memory"** — el archivo crece con correcciones
  explícitas, no por adelantar reglas hipotéticas

## Cuándo cargar

- El usuario invoca `/swl:claudemd [audit|check|refactor|init-user|init-project]`
- El hook `claudemd-bloat-detector` emite nudge sugiriendo `/swl:claudemd refactor`
- El usuario pregunta "¿está bien mi CLAUDE.md?" o "¿cómo mejoro mi CLAUDE.md?"
- Se está generando un proyecto nuevo y se necesita CLAUDE.md raíz
- Se está cambiando de máquina y se necesita transportar `~/.claude/CLAUDE.md`

## Cuándo NO cargar

- El usuario quiere editar `~/.claude/rules/*.md` (reglas globales) — usar Edit directo
- El usuario quiere validar otros `.md` (READMEs, docs/) — no aplica el contrato canónico de CLAUDE.md
- El usuario quiere generar el bloque del installer — eso lo hace `scripts/lib/transformadores/claude.js`
- El usuario quiere crear un ADR — usar `Skill("doc-coauthoring")` o Write directo

---

## Subcomando: audit

Ejecuta el auditor determinista:

```bash
node scripts/auditar-claudemd.js
node scripts/auditar-claudemd.js --json    # para parsing
node scripts/auditar-claudemd.js --strict  # exit 1 si WARN
```

El auditor verifica ocho dimensiones:

| Dimensión | Regla | Severidad |
|---|---|---|
| Existencia | Archivo presente en `./CLAUDE.md` o `./.claude/CLAUDE.md` | ERROR si ausente |
| Tamaño total | Líneas ≤ `SWL_CLAUDEMD_MAX_LINES` (default 200) | WARN |
| Bullets monolíticos | Cada bullet/párrafo ≤ `SWL_CLAUDEMD_MAX_BULLET_CHARS` (default 1000). Tablas y bloques de código se ignoran | WARN |
| Secciones canónicas | Stack, Comandos, Code style, Conventions presentes | WARN |
| @references | Archivos >80 líneas usan al menos un `@docs/...md` | WARN |
| Placeholders | `[TBD]`, `[TODO]`, `[COMPLETAR]` | ERROR |
| Karpathy reference | Project-level >50 LOC menciona "Karpathy", los 4 principios, o `prevencion-sobreingenieria` | WARN |
| Duplicación reglas globales | Bloque inline parafrasea regla de `~/.claude/rules/` ya cargada globalmente (catálogo en `scripts/lib/reglas-globales-conocidas.json`) | WARN |

Veredicto final: ERROR → WARN → OK (el más severo gana).

### Cómo interpretar los resultados

- **OK**: el archivo cumple. No hay acción requerida.
- **WARN líneas**: el archivo creció demasiado. Ejecuta `refactor` para
  identificar candidatos a extracción.
- **WARN bullet gigante**: un bullet/párrafo es ilegible. Convertirlo a
  tabla, lista jerárquica, o extraer su contenido a archivo separado.
- **WARN secciones ausentes**: las secciones canónicas Anthropic no
  están. Si el archivo es proyecto greenfield, agregarlas. Si es CLAUDE.md
  de overview/meta-sistema, considerar si aplica el contrato.
- **WARN sin @references**: el archivo es grande pero no enlaza nada
  externo. Identificar contenido duplicable a `@docs/`, `@.planning/`, etc.
- **ERROR placeholders**: bloqueador. Resolver antes de commitear.

---

## Subcomando: refactor

**No modifica archivos** — propone diff. El usuario decide aplicar.

### Algoritmo

1. Lee `CLAUDE.md` actual.
2. Para cada bullet/párrafo > `MAX_BULLET_CHARS`:
   - Si contiene **una sola lista de items homogéneos** → propone tabla
   - Si contiene **definiciones técnicas extensas** → propone extracción a `docs/[tema].md`
   - Si contiene **enumeración de variables/configuración** → propone extracción a `docs/variables-[scope].md`
3. Para cada sección > 50 líneas:
   - Identifica el "tema" del header
   - Propone `docs/[tema-kebab].md` y reemplazo en CLAUDE.md por:
     `Para detalles ver @docs/[tema].md`
4. Imprime diff propuesto en formato unified.

### Patrones de extracción típicos

| Si la sección/bullet contiene… | Mover a… |
|---|---|
| Variables de entorno opt-in | `docs/variables-entorno.md` |
| Reglas de gobernanza extensas | `docs/gobernanza.md` |
| Catálogo completo de comandos | `COMANDOS.md` (referenciar) |
| Mapa de propagación detallado | `docs/mapa-propagacion.md` |
| Convenciones por capa | `docs/convenciones-{capa}.md` |
| Lista de dependencias / stack histórico | `docs/stack-historico.md` |
| Decisiones puntuales antiguas | ADR en `.planning/adrs/` |

### Anti-patrones de refactor

- **NO extraer reglas de máxima prioridad** — esas DEBEN estar en CLAUDE.md raíz
- **NO extraer la sección Stack** — es la primera info que Claude necesita
- **NO extraer la sección Commands** — son acción inmediata, deben estar visibles
- **NO crear más de 3 archivos `@`-referenciados nuevos en un solo refactor** — fragmentar demasiado dispersa el contexto

---

## Subcomando: init-user

Genera `~/.claude/CLAUDE.md` (en Windows: `%USERPROFILE%\.claude\CLAUDE.md`)
con template de preferencias personales si NO existe. Si existe, sugiere
secciones faltantes pero NO sobreescribe.

### Pasos

1. Detectar la ruta:
   - Linux/macOS: `$HOME/.claude/CLAUDE.md`
   - Windows: `$env:USERPROFILE/.claude/CLAUDE.md` (en PowerShell)
2. Si existe → leer, identificar secciones faltantes, sugerir patches
3. Si no existe → crear directorio `~/.claude/` si falta, escribir template

### Template

Ver template completo en el comando `/swl:claudemd` sección `init-user`.

Las secciones canónicas para user-level son DISTINTAS de project-level:

| Sección | Project-level | User-level |
|---|---|---|
| Stack | Sí — del proyecto | No (varía por proyecto) |
| Comandos | Sí — del proyecto | No |
| Code style | Sí — convenciones del equipo | Sí — preferencias personales (indent, naming favorito) |
| Conventions | Sí — del proyecto | No |
| Mi rol y stack preferido | No | Sí |
| Estilo de comunicación | No | Sí |
| Patrones que aplico siempre | No | Sí — meta-preferencias cross-project |

---

## Subcomando: init-project

Genera `./CLAUDE.md` raíz del proyecto detectando stack actual.

### Pasos

1. Verificar que `./CLAUDE.md` NO exista. Si existe → mensaje "ya existe,
   considera `/swl:claudemd refactor`" y salir sin tocar.
2. Ejecutar `detectarStackDetallado(process.cwd())` (de
   `scripts/lib/detectar-stack-detallado.js`).
3. Generar archivo con secciones pobladas:
   - **Reglas obligatorias**: `@reglas/usar-sistema-swl.md`
   - **Reglas de máxima prioridad** con sub-sección **Cuatro principios de
     implementación (Karpathy)** — bloque exacto definido abajo
   - **Stack**: lenguaje + framework + ORM + package manager detectados
   - **Comandos**: npm scripts detectados o comandos típicos por lenguaje
   - **Code style**: placeholders explícitos (`<!-- pendiente: definir convención de X -->`)
   - **Conventions**: placeholders explícitos
   - **@references**: enlazar a `.planning/PROYECTO.md`, `README.md`,
     `CONTRIBUTING.md` solo si existen
4. Imprimir mensaje con próximo paso: "ejecuta `/swl:claudemd audit`
   para verificar".

### Bloque obligatorio Karpathy en init-project

Toda generación nueva incluye esta sub-sección literal en "Reglas de
máxima prioridad":

```markdown
### Cuatro principios de implementación (Karpathy)
Antes de implementar, refactorizar o corregir bugs: (1) **pensar antes de codificar** (no asumir en silencio), (2) **simplicidad primero** (sin abstracciones especulativas), (3) **cambios quirúrgicos** (leer archivo completo antes de editar, no refactor de oportunidad), (4) **ejecución orientada a metas** (criterios verificables, test que reproduce bugs antes del fix). Detalle + 9 ejemplos MAL→BIEN: `Skill("prevencion-sobreingenieria")` + `recursos/EXAMPLES.md`.
```

Justificación: el skill `prevencion-sobreingenieria` y su `recursos/EXAMPLES.md`
se distribuyen con cada instalación SWL, así que la referencia siempre resuelve.
La sub-sección compacta (5 líneas) ataca los gaps cognitivos más frecuentes
de cualquier proyecto sin agregar opinión específica.

### Check Karpathy en audit

`scripts/auditar-claudemd.js` debe verificar (search regex case-insensitive):

- `/karpathy/i`
- `/cuatro principios/i` o `/4 principios/i`
- `/prevencion-sobreingenieria/`
- `/Skill\(["'`]prevencion-sobreingenieria["'`]\)/`

Si NO encuentra ninguna AND el archivo tiene >50 LOC AND es project-level
(no `~/.claude/CLAUDE.md`): emitir hallazgo WARN con mensaje:

```
CLAUDE.md no menciona los cuatro principios Karpathy ni el skill
prevencion-sobreingenieria. Considerar agregar la sub-sección compacta
(ver /swl:claudemd init-project § Bloque obligatorio Karpathy).
```

Esta dimensión es WARN, no ERROR — guía sin imponer. CLAUDE.md user-level
(`~/.claude/`) NO se evalúa contra este check.

---

## Interacción con /swl:aprender (contrato cruzado)

`/swl:aprender` y `/swl:claudemd` operan sobre el mismo archivo desde
ángulos opuestos: aprender **muta**, claudemd **prescribe contrato**.
Sin coordinación explícita, una sesión de aprender puede romper el
contrato silenciosamente.

### El gap arquitectural que esta interacción cierra

`/swl:aprender` Paso 6 Tipo A agrega reglas a `CLAUDE.md` del proyecto.
El hook `claudemd-bloat-detector.js` (PostToolUse, async, no bloqueante)
emite nudge tras Write/Edit/MultiEdit sobre CLAUDE.md, pero **el nudge
llega después** del comando de aprender. Resultado: aprender termina,
reporta éxito al usuario, y solo después aparece el nudge — con el
commit ya hecho.

Origen detectado: sesión 2026-05-22 al evaluar el flujo SIGAF→swl-ses.
CLAUDE.md SIGAF recibió ~25 líneas inline de "Triangulación schema
cross-stack" sin validación post-mutación → archivo probablemente
superó el umbral de 200 LOC sin warning consciente.

### Contrato canónico de interacción

Para cualquier comando SWL que escriba a CLAUDE.md del proyecto
(`/swl:aprender`, `/swl:adoptar-proyecto`, `/swl:nuevo-proyecto`,
`/swl:claudemd init-project`, futuros comandos similares):

1. **Antes de escribir**: opcional, pero recomendado — leer el tamaño
   actual del archivo y estimar el delta.
2. **Después de escribir**: OBLIGATORIO ejecutar el auditor síncrono:

   ```bash
   node scripts/auditar-claudemd.js --json
   # o fallback:
   npx -y @saulwade/swl-ses@latest audit-claudemd --json
   ```

3. **Evaluar veredicto**:
   - `OK` → continuar
   - `WARN tamano-total` → proponer condensar o extraer a `@docs/lessons-<tema>.md`
   - `WARN bullet-gigante` → proponer condensar a tabla/lista jerárquica
   - `WARN secciones-canonicas` / `WARN sin-at-references` / `WARN karpathy-reference` → reportar al usuario, permitir continuar
   - `ERROR placeholders` → **DETENER** y revertir

4. **Re-ejecutar el auditor** tras la corrección hasta veredicto OK o
   WARN aceptable.

### Doble red de seguridad

El sistema tiene dos capas de protección complementarias:

| Capa | Mecanismo | Cuándo actúa | Bloqueo |
|------|-----------|--------------|---------|
| Síncrona | Paso 6.5 de `/swl:aprender` (y equivalente en otros comandos) | Justo después del Write/Edit, antes del reporte final | Bloquea pasos posteriores hasta resolver |
| Asíncrona | Hook `claudemd-bloat-detector.js` (PostToolUse) | Tras cualquier Write/Edit/MultiEdit a CLAUDE.md (incluso fuera de comandos SWL) | No bloquea — emite nudge a `.planning/evolucion/nudges.jsonl` |

La capa síncrona es proactiva (detiene el comando antes de reportar
éxito). La asíncrona es retroactiva (cubre escrituras desde fuera de
comandos SWL, ej. edición manual).

### Por qué NO se duplica al hook

El hook async existente cubre el caso de escrituras desde **cualquier
fuente** (edición manual del usuario, otros comandos, scripts externos).
Es la red de seguridad universal. La validación síncrona en aprender es
específica para el flujo del comando — donde el agente puede actuar
sobre el WARN antes de continuar.

NO crear un hook nuevo dedicado a aprender — duplicaría el rol del
existente. La invocación síncrona en el Paso 6.5 es suficiente.

### Reglas duras

- `/swl:aprender` Paso 6.5 es OBLIGATORIO si se aplicó Tipo A.
- `/swl:adoptar-proyecto` Paso 8 debe ejecutar el auditor tras
  generar/modificar CLAUDE.md.
- `/swl:nuevo-proyecto` Paso 6 debe ejecutar el auditor tras generar
  CLAUDE.md inicial.
- `/swl:claudemd init-project` debe ejecutar el auditor sobre el
  archivo recién generado.

Cualquier comando futuro que escriba a CLAUDE.md DEBE seguir este
contrato.

---

---

## Detección de duplicación de reglas globales (dimensión 8)

### Por qué existe

Las reglas en `~/.claude/rules/` se cargan automáticamente en cada
sesión SWL. Si un proyecto duplica inline el contenido de esas reglas
en su `CLAUDE.md`, ocurren tres patologías:

1. **Bloat acumulativo**: 7-15 líneas por regla duplicada × N proyectos
   = inflación silenciosa que rompe el umbral de 200 LOC.
2. **Drift al actualizar la global**: si la regla global cambia, las
   copias en cada CLAUDE.md quedan obsoletas sin alerta.
3. **Erosión del contrato canónico**: cada CLAUDE.md re-deriva el
   principio con palabras propias, generando 4 paráfrasis distintas
   del mismo contenido.

La regla `reglas/sin-duplicacion-reglas-globales.md` (v1.7.0) prohíbe
esta duplicación. Esta dimensión del auditor la detecta.

### Catálogo declarativo

`scripts/lib/reglas-globales-conocidas.json` lista las reglas globales
conocidas con sus patrones de detección. Estructura por entrada:

```json
{
  "id": "idioma-espanol-mexico",
  "regla_global": "brevedad-output.md",
  "seccion_canonica": "Idioma obligatorio: español de México",
  "referencia_canonica": "@~/.claude/rules/brevedad-output.md § Idioma obligatorio",
  "patrones": ["\\bespañol\\s+de\\s+M[ée]xico\\b", "..."],
  "min_matches": 2,
  "remediacion_sugerida": "Eliminar el bloque local..."
}
```

Reglas incluidas en v1.7.0:

- `idioma-espanol-mexico` (brevedad-output.md § Idioma)
- `brevedad-sin-aiisms` (brevedad-output.md § Brevedad)
- `git-sin-coautores` (git-coauthor.md)
- `arreglar-al-detectar` (arreglar-al-detectar.md)
- `debatir-antes-de-aceptar` (debatir-antes-de-aceptar.md)
- `usar-context7` (usar-context7.md)

### Cuándo NO se evalúa

- **User-level** (`~/.claude/CLAUDE.md`): ahí sí pueden declararse
  preferencias personales que parafrasean reglas globales. La opción
  `esUserLevel: true` skipea la evaluación.
- **Archivos < 20 LOC**: CLAUDE.md mínimos no acumulan duplicaciones
  con suficiente densidad para evaluar.

### Capa async — hook

`hooks/claudemd-duplicacion-detector.js` (PostToolUse, no bloquea)
ejecuta el detector tras cualquier Write/Edit a CLAUDE.md y emite
nudge a `.planning/evolucion/nudges.jsonl` con `kind:
claudemd-duplicacion-reglas`. Opt-out: `SWL_CLAUDEMD_DUPLICACION=0`.

### Cómo refactorizar duplicaciones detectadas

Tres opciones para cada hallazgo:

1. **Eliminar** (default recomendado): el bloque solo repite la regla
   global, eliminarlo no pierde información.
2. **Convertir a matiz local** (≤3 líneas): si el bloque agrega valor
   local genuino, reescribirlo corto referenciando la regla global:
   ```markdown
   Convenciones locales: identificadores técnicos en inglés (rutas,
   comandos). Ver @~/.claude/rules/brevedad-output.md.
   ```
3. **Documentar override explícito** (raro): si el proyecto contradice
   la regla global por requerimiento documentable:
   ```markdown
   Override de @~/.claude/rules/brevedad-output.md § Brevedad: este
   proyecto exige docstrings extendidos por compliance regulatorio.
   ```

### Anti-patrón: "lo dejo por claridad"

La regla global YA es visible — se carga automáticamente. Duplicarla
no aumenta su prioridad ni su claridad; solo crea deuda. Si el WARN
del auditor incomoda, la respuesta correcta es **resolver la
duplicación**, no aceptar el WARN.

---

## Gotchas / Errores comunes no obvios

- **Marcar tablas como bullets gigantes**: el detector debe excluir
  líneas que empiezan con `|` (tablas Markdown). Sin ese filtro genera
  falsos positivos en cualquier CLAUDE.md con tablas. Implementado en
  `scripts/auditar-claudemd.js` función `detectarBulletsGigantes`.
- **Marcar bloques de código como bullets gigantes**: igual que tablas
  — el detector entra en modo "code fence" al ver ` ``` ` y no cuenta
  esas líneas. Sin ese filtro un script Bash de 50 líneas en CLAUDE.md
  rompe la auditoría.
- **`refactor` que termina escribiendo el archivo**: el subcomando
  refactor SOLO debe imprimir diff. Si modifica el archivo viola el
  principio "el usuario decide". Cualquier modificación destructiva debe
  ser explícita y confirmada por el usuario.
- **`init-project` sobreescribiendo CLAUDE.md existente**: el usuario
  puede tener un CLAUDE.md curado con valor irrecuperable. NUNCA
  sobreescribir — sugerir refactor.
- **Templates con `[TBD]` que después fallan auditoría**: los templates
  generados por `init-user` y `init-project` usan `<!-- pendiente: ... -->`
  HTML comments en lugar de `[TBD]` para que el auditor no los marque
  como ERROR placeholders. Comments HTML son ignorados por el regex.
- **Aplicar el contrato canónico a CLAUDE.md de subdirectorios**: si el
  proyecto adopta jerarquía (ADR-0007), los CLAUDE.md de subdirectorios
  pueden NO tener todas las secciones canónicas (porque heredan del root).
  Por ahora el auditor aplica el contrato uniforme; si el ADR-0007 se
  acepta, el auditor debe distinguir root vs subdirectorio.
- **Codificar el patrón legacy/malo como ejemplo "correcto" en una regla
  de CLAUDE.md codifica el bug**: una regla cuya prosa enseña el patrón
  correcto pero cuyo *ejemplo* muestra el patrón malo se auto-perpetúa.
  Cada release nuevo copia el ejemplo y replica el problema. Caso real:
  CLAUDE.md v1.3.5 línea 59 decía *"todo mensaje del installer/docs usa
  `npx swl-ses@latest <comando>`"* — pero `npx swl-ses@latest` sin scope
  resuelve al paquete legacy DEPRECATED tras el rebrand 2026-04-30. La
  regla acumuló 152 ocurrencias del patrón malo en 8 releases consecutivos
  hasta v1.3.6. Solución: las reglas DEBEN mostrar el patrón correcto en
  el ejemplo. Si la regla tiene que citar un patrón malo (para
  prohibirlo), envolverlo en bloque "NUNCA" explícito separado del
  ejemplo de uso correcto. Pregunta de auditoría: *si un autor de release
  futuro copia el ejemplo de esta regla literalmente, ¿produce código
  correcto?* Si no, la regla está mal escrita.

## Señales de alerta

Detente y escala si:

- El usuario pide `init-project` en un directorio que ya tiene CLAUDE.md
  con >100 líneas de contenido custom (riesgo: pérdida de información)
- `audit` reporta WARN líneas pero el contenido es legítimamente
  necesario (ej. listas grandes de comandos sin posibilidad de extracción
  útil) — sugerir ajustar `SWL_CLAUDEMD_MAX_LINES`, no extraer por extraer
- El usuario pide `refactor` y propone extracciones que dispersarían
  contexto crítico (ej. mover "Reglas de máxima prioridad") — rechazar
  con explicación del anti-patrón
