---
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.1"
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

Las secciones canónicas user-level son DISTINTAS de project-level (Stack y
Comandos no aplican; sí aplican rol, estilo de comunicación y meta-preferencias).
Tabla comparativa completa y template: ver
[plantillas-init](recursos/plantillas-init.md) y el comando `/swl:claudemd`
sección `init-user`.

---

## 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
   - **SWL es tooling (frontera de versionado)** — bloque exacto definido abajo.
     OBLIGATORIO cuando el proyecto destino NO es el repo madre de swl-ses (es
     decir, siempre en `init-project` sobre un proyecto del usuario). Mantiene
     el CLAUDE.md consistente con la sección swl-ses del `.gitignore`.
   - **@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".

### Bloques literales de init-project

Los dos bloques OBLIGATORIOS que toda generación nueva inserta literal viven en
[plantillas-init](recursos/plantillas-init.md) (fuente de verdad de los templates):

- **Bloque SWL-tooling (frontera de versionado)**: documenta en el CLAUDE.md del
  proyecto destino qué archivos son runtime gitignored (gestionado por
  `scripts/lib/gitignore-manifest.js`) vs qué versiona el equipo. Si
  `ENTRADAS_BASE` cambia, el bloque del recurso se actualiza en sync.
- **Bloque Karpathy (4 principios)**: sub-sección compacta en "Reglas de máxima
  prioridad" que referencia `Skill("prevencion-sobreingenieria")` (siempre
  resuelve — se distribuye con cada instalación SWL).

El recurso incluye también el **check Karpathy del auditor** (regex, condiciones
y mensaje WARN — project-level >50 LOC sin mención a los 4 principios).

---

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

`/swl:aprender` **muta** CLAUDE.md; `/swl:claudemd` **prescribe contrato**.
Todo comando SWL que escriba a CLAUDE.md del proyecto (`aprender`,
`adoptar-proyecto`, `nuevo-proyecto`, `claudemd init-project`, futuros) DEBE
ejecutar el auditor síncrono tras escribir (`node scripts/auditar-claudemd.js
--json`), evaluar el veredicto (OK→continuar; WARN→proponer condensar/extraer;
`ERROR placeholders`→**DETENER y revertir**) y re-auditar hasta OK/WARN aceptable.

Doble red: capa síncrona (Paso 6.5 de aprender — proactiva, bloquea el comando)
+ capa async (hook `claudemd-bloat-detector.js` — nudge universal para
escrituras fuera de comandos SWL). NO crear hook nuevo dedicado — duplicaría el
existente.

Detalle completo (gap arquitectural de origen, contrato canónico de 4 pasos,
tabla de capas, reglas duras por comando): ver
[contrato-aprender](recursos/contrato-aprender.md).

---

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

Las reglas de `~/.claude/rules/` se cargan automáticamente en cada sesión;
duplicarlas inline en un CLAUDE.md de proyecto produce bloat, drift al
actualizar la global y erosión del contrato (regla
`reglas/sin-duplicacion-reglas-globales.md`). El auditor lo detecta con el
catálogo declarativo `scripts/lib/reglas-globales-conocidas.json` (6 reglas en
v1.7.0); la capa async es `hooks/claudemd-duplicacion-detector.js` (opt-out
`SWL_CLAUDEMD_DUPLICACION=0`). NO se evalúa user-level ni archivos <20 LOC.

Remediación por hallazgo: **eliminar** (default), **matiz local** ≤3 líneas
referenciando la global, u **override explícito** documentado. Anti-patrón:
"lo dejo por claridad" — la global ya es visible; duplicar solo crea deuda.

Detalle completo (patologías, estructura del catálogo, ejemplos de
remediación): ver
[duplicacion-reglas-globales](recursos/duplicacion-reglas-globales.md).

---

## 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
