---
name: swl:claudemd
description: Audita, refactoriza, valida o inicializa archivos CLAUDE.md según best practices Anthropic (ADR-0016). Subcomandos audit (analiza calidad), refactor (sugiere extracciones), check (verifica secciones canónicas), init-user (crea ~/.claude/CLAUDE.md template), init-project (genera CLAUDE.md raíz del proyecto).
allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
evolved: true
evolved-from: "1.6.9"
evolved-at: "2026-05-22"
evolved-by: "aprender"
evolved-note: "Audit dimensión 7 — duplicación de reglas globales (cataloga 6 reglas de ~/.claude/rules/ que NO deben duplicarse inline). Refactor propone reemplazo canónico. Aplica regla nueva sin-duplicacion-reglas-globales.md."
---

# /swl:claudemd — Tratamiento profesional de CLAUDE.md

Comando para auditar, refactorizar y mantener `CLAUDE.md` siguiendo las
cinco recomendaciones del video oficial Anthropic *"The CLAUDE.md file"*:

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

**Carga**: `Skill("swl-claudemd")` — contiene la lógica de auditoría, las
secciones canónicas, los umbrales de inflación y los templates de
generación. Delega análisis y criterios al skill.

## Subcomandos

| Subcomando | Propósito |
|---|---|
| `/swl:claudemd audit` | Audita el CLAUDE.md actual (líneas, bullets gigantes, secciones canónicas, @references, placeholders) |
| `/swl:claudemd check` | Como audit pero exit 1 si hay WARN — útil en pre-commit/CI |
| `/swl:claudemd refactor` | Sugiere extracciones a archivos `@`-referenciados (no modifica, solo propone diff) |
| `/swl:claudemd init-user` | Crea `~/.claude/CLAUDE.md` con template de preferencias personales si no existe |
| `/swl:claudemd init-project` | Genera CLAUDE.md raíz del proyecto detectando el stack actual |

Sin subcomando: equivale a `audit`.

## Cuándo usar

- Después de modificar manualmente CLAUDE.md (verifica calidad)
- Al inicio de un proyecto que no tenía CLAUDE.md (init-project)
- Al cambiar de máquina y querer transportar preferencias (init-user)
- En pre-commit hook si el proyecto trackea CLAUDE.md (check)
- Cuando el hook `claudemd-bloat-detector` emite nudge

## Ejecución de cada subcomando

### audit / check

```bash
npx -y @saulwade/swl-ses@latest audit-claudemd            # output legible
npx -y @saulwade/swl-ses@latest audit-claudemd --json     # output JSON estructurado
npx -y @saulwade/swl-ses@latest audit-claudemd --strict   # exit 1 si WARN (modo check)
```

El subcomando `audit-claudemd` del CLI funciona con cualquier modo de instalación
(global vía `npm i -g`, npx puntual o local dev) porque resuelve el script via
el paquete npm, no via path relativo al CWD. Es independiente del proyecto desde
donde se invoque.

El veredicto puede ser:

- **OK** — cumple best practices, sin hallazgos
- **WARN** — tiene oportunidades de mejora (líneas excesivas, bullets
  gigantes, secciones ausentes, sin @references)
- **ERROR** — no existe, tiene placeholders sin reemplazar, faltan
  secciones críticas

### refactor

Lee el CLAUDE.md actual, identifica candidatos a extracción (bullets
monolíticos, secciones largas, contenido duplicable a `@references`) y
imprime el diff propuesto. **NO modifica el archivo** — el usuario
revisa y aplica manualmente o con `git apply`.

Patrones de extracción típicos:

| Si el bullet/sección contiene… | Mover a… |
|---|---|
| Variables de entorno opt-in | `docs/variables-entorno.md` |
| Reglas de gobernanza extensas | `docs/gobernanza.md` |
| Catálogo de comandos completo | `COMANDOS.md` (referenciar) |
| Mapa de propagación detallado | `docs/mapa-propagacion.md` |
| Convenciones de cada capa | `docs/convenciones-{capa}.md` |

### init-user

Verifica si existe `~/.claude/CLAUDE.md` (en Windows:
`%USERPROFILE%\.claude\CLAUDE.md`). Si no existe, genera template
mínimo:

```markdown
# CLAUDE.md (preferencias personales transversales)

> Este archivo aplica a TODOS mis proyectos. Las reglas específicas de
> proyecto van en el CLAUDE.md de la raíz del proyecto, no aquí.

## Mi rol y stack preferido

- Rol: [ej. ingeniero senior backend]
- Stack preferido: [ej. Python + FastAPI, TypeScript + Next.js]
- Herramientas habituales: [ej. Neovim, ripgrep, fd, gh CLI]

## Estilo de comunicación

- Idioma: español
- Formato preferido para respuestas: [breve / detallado / con tablas]
- Cuándo prefiero ver alternativas vs. una sola recomendación

## Patrones que aplico siempre

- [ej. "Antes de implementar, mostrar el plan"]
- [ej. "Tests para todo código nuevo, sin excepción"]
- [ej. "Commits atómicos en español, formato conventional"]
```

Si ya existe, NO lo sobreescribe — sugiere añadir secciones faltantes.

### init-project

Detecta el stack del proyecto actual con `scripts/lib/detectar-stack-detallado.js`
y genera `./CLAUDE.md` mínimo con:

- Sección **Reglas obligatorias** que **DEBE** incluir como primera línea
  bajo el encabezado:
  ```markdown
  ## Reglas obligatorias

  @reglas/usar-sistema-swl.md
  ```
  Esta referencia es obligatoria — fuerza que el agente cargue la matriz
  operacional de uso del sistema SWL al inicio de cada sesión. Si el proyecto
  tiene otras reglas locales (`@reglas/seguridad.md`, `@reglas/arquitectura.md`,
  etc.), agregarlas debajo.
- Sección **Reglas de máxima prioridad** con sub-sección obligatoria
  **Cuatro principios de implementación (Karpathy)**:
  ```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`.
  ```
  Esta sub-sección es estándar SWL y cubre los gaps cognitivos más
  frecuentes del agente sin agregar reglas específicas del proyecto.
- Sección **Stack** poblada (lenguaje, framework, ORM, package manager)
- Sección **Comandos** poblada (npm scripts detectados o comandos típicos)
- Sección **Code style** vacía con placeholders
- Sección **Conventions** vacía con placeholders
- Sección **@references** apuntando a `.planning/PROYECTO.md`,
  `README.md`, etc. si existen

Si CLAUDE.md ya existe, **NO lo sobreescribe**. Sugiere correr
`/swl:claudemd refactor` para mejorar el actual. Si detecta que el CLAUDE.md
existente NO incluye `@reglas/usar-sistema-swl.md` o NO menciona los cuatro
principios Karpathy (o `prevencion-sobreingenieria`), emitir hallazgo WARN
recomendando agregarlo manualmente.

### Validación síncrona post-generación

Tras `init-project` generar el archivo nuevo, ejecutar inmediatamente
`audit` sobre el resultado:

```bash
node scripts/auditar-claudemd.js --json
```

Veredicto esperado: `OK` (el template debe respetar el contrato por
construcción). Cualquier WARN/ERROR es bug del template — reportar al
usuario y abrir issue para corrección. Este check es parte del contrato
cruzado con `/swl:aprender` documentado en `@docs/contrato-aprender-claudemd.md`.

### audit — checks específicos sobre Karpathy

El subcomando `audit` verifica además de las dimensiones estándar:

- ¿El CLAUDE.md menciona los cuatro principios Karpathy (texto literal
  "Karpathy" o nombres de los 4 principios) o referencia
  `prevencion-sobreingenieria` con `Skill(...)` o `@reglas/`?

Si NO los menciona y el archivo tiene >50 líneas: emitir hallazgo WARN
recomendando agregar la sub-sección compacta (4 líneas) como guía de
implementación. NO emite WARN para CLAUDE.md mínimos (<50 LOC) ni para
archivos `~/.claude/CLAUDE.md` user-level (esos siguen otro contrato).

### audit — checks específicos sobre duplicación de reglas globales

El subcomando `audit` también detecta (dimensión 7) si CLAUDE.md duplica
reglas que ya viven en `~/.claude/rules/` y se cargan globalmente.
Consume el catálogo declarativo
`scripts/lib/reglas-globales-conocidas.json` que cataloga 6 reglas
conocidas:

- `brevedad-output.md` § Idioma obligatorio: español de México
- `brevedad-output.md` § Brevedad y eficiencia de output
- `git-coauthor.md` § Sin co-autores en commits
- `arreglar-al-detectar.md` § Detectar → Informar → Arreglar
- `debatir-antes-de-aceptar.md`
- `usar-context7.md`

Si detecta duplicación: emite hallazgo `duplicacion-reglas-globales`
severidad WARN con línea aproximada y remediación específica. NO bloquea
el comando — sirve como nudge para limpiar el CLAUDE.md.

NO aplica a `~/.claude/CLAUDE.md` user-level (ahí sí pueden declararse
preferencias personales que parafrasean reglas globales).

Aplica regla `reglas/sin-duplicacion-reglas-globales.md`.

### refactor — propuestas para duplicaciones de reglas globales

Cuando `audit` detecta duplicaciones, el subcomando `refactor` propone
el reemplazo concreto usando `construirSugerenciaRefactor()` del
detector. Cada propuesta incluye:

- **Bloque a eliminar** (línea aproximada en CLAUDE.md)
- **Regla global afectada** (archivo + sección canónica)
- **Reemplazo sugerido** (3 opciones):
  1. Eliminar el bloque — la regla global YA aplica automáticamente
  2. Reescribir como matiz local en ≤3 líneas referenciando la regla
  3. Documentar override explícito con justificación

El refactor SOLO imprime el diff propuesto. El usuario decide aplicar.

## Variables de entorno

Ver `@docs/variables-entorno.md` sección "Calidad de CLAUDE.md":

- `SWL_CLAUDEMD_BLOAT` (on/off) — activa hook `claudemd-bloat-detector`
- `SWL_CLAUDEMD_MAX_LINES` (default 200) — umbral de líneas totales
- `SWL_CLAUDEMD_MAX_BULLET_CHARS` (default 1000) — umbral de bullet/párrafo

## Exit codes

- `0` — OK o WARN (consultivo)
- `1` — ERROR o `--strict` + WARN
