CLAUDE.md: las reglas se quedan, los procedimientos se van a los comandos

[polmarza]

¿Qué se hizo?

CLAUDE.md pasa de 516 a 370 líneas (-28%) sin perder una sola regla. Lo que se va son los cómo, que ya vivían duplicados en los comandos y ahora viven solo allí.

Motivación

Un compañero comentó que CLAUDE.md se le hacía largo. Tenía razón a medias, pero el diagnóstico era otro: el problema no es el tamaño, es que había dos tipos de contenido mezclados y solo uno se gana estar siempre en contexto.

• Regla — el agente puede incumplirla sin que nadie saque el tema. "La clave real nunca se escribe en .mcp.json." Se queda.
• Procedimiento — solo hace falta cuando estás haciendo esa cosa concreta, y entonces se invoca el comando, que lo trae. claude mcp add --transport http <nombre> --scope project <url>. Se va.

Tenerlos juntos significa pagar el coste del procedimiento en cada sesión para obtener el beneficio de la regla.

Y la duplicación era literal, no teórica: el formato del changelog estaba en CLAUDE.md, en changelog/README.md y en /changelog. La regla de la tercera columna, en CLAUDE.md, en docs/features/README.md y en /feature. Tres copias de lo mismo es una garantía de que acaban divergiendo.

Sección	Antes	Después	El procedimiento vive en
Protocolo de MCPs	94	30	/mcp-setup
Protocolo de cambios + de PRs	~98	42	changelog/README.md, /changelog, plantilla de PR
Ciclo de trabajo de una feature	54	31	/feature, docs/features/README.md

El coste en tokens nunca fue el argumento. 6.400 tokens son un 3% de la ventana de contexto. El argumento es la atención: una regla en la línea 400, rodeada de trescientas líneas de procedimiento que el agente no necesita en esa sesión, compite con todo lo demás.

Requisitos que cierra

Ninguno. Este repositorio es el andamiaje: no tiene PRD con requisitos propios.

Tipo de cambio

• Feature
• Fix
• Refactor
• Migración
• Documentación
• Configuración

Evidencia

1. Antes de cortar nada, se comprobó que el destino lo tuviera. Dos cosas existían solo en CLAUDE.md y se movieron primero, en commits del propio PR:

• La tabla de alcances (user / project / local) y la sintaxis de expansión ${VAR} de .mcp.json → /mcp-setup
• El razonamiento de que la verificación es estructural y no semántica → docs/features/README.md

2. Auditoría de trece reglas del documento original contra todo el repositorio:

  OK  no instales por tu cuenta       → CLAUDE.md
  OK  fuente oficial                  → CLAUDE.md, /mcp-setup
  OK  enseña el comando antes         → CLAUDE.md
  OK  clave nunca en .mcp.json        → CLAUDE.md, /mcp-setup
  OK  documentar MCP en architecture  → CLAUDE.md, /mcp-setup, docs/architecture.md, /doctor
  OK  changelog en .template          → CLAUDE.md
  OK  formato del changelog           → /changelog, changelog/README.md
  OK  security-review                 → CLAUDE.md, plantilla de PR
  OK  tercera columna                 → CLAUDE.md:302, /feature, docs/features/README.md
  OK  no verificable por interfaz     → CLAUDE.md, /feature, docs/features/README.md
  OK  tests después de implementar    → docs/testing.md, docs/features/README.md
  OK  pega la salida real             → CLAUDE.md, plantilla de PR
  OK  marca solo lo verificado        → CLAUDE.md, plantilla de PR

Las trece siguen presentes. La de "tercera columna" dio un falso negativo en el grep automático porque el texto está partido por un salto de línea; verificada a mano en CLAUDE.md:302.

3. Integridad estructural tras el recorte:

$ python3 <comprobación de separadores y secciones huérfanas>
  sin problemas

$ <comandos referenciados en CLAUDE.md>
  OK /changelog  OK /doctor  OK /feature
  OK /init-proyecto  OK /mcp-setup  OK /mejora
  nativo /security-review

De paso salió una referencia muerta: CLAUDE.md mandaba usar /autopilot para el flujo completo, y ese comando no existe en este repositorio. Eliminada.

4. La verificación de cobertura sigue limpia:

$ node scripts/verificar-cobertura.mjs
Sin fichas de feature todavía: nada que verificar.
$ echo $?
0

Verificación de los requisitos:

No aplica: este PR no cierra ningún requisito de PRD. Lo verificable era que ninguna regla se perdiera, y está en el punto 2.

Checklist

• Los documentos afectados en docs/ están actualizados — docs/features/README.md recibe el razonamiento que se movió
• La ficha de docs/features/ está en estado Verificada — no aplica: este repositorio es el andamiaje y no tiene fichas propias
• Hay una entrada en changelog/ con este cambio — en .template/changelog/
• La sección "Evidencia" contiene salida real de comandos, no una descripción de lo que pasaría
• Se ha ejecutado /security-review si hay cambios sensibles — no se ha ejecutado: no hay código, ni workflows, ni permisos. Es reorganización de documentación

---

Lo que se pierde, y conviene decirlo antes de mergear. Lo que está en CLAUDE.md está en contexto garantizado; lo que está en un comando se carga solo si alguien lo invoca, y lo que está en docs/features/README.md, solo si el agente abre el archivo. Cada línea que sale se debilita un poco.

Por eso la frontera se puso donde se puso: nadie ejecuta claude mcp add por accidente, pero sí puede escribir una clave real en un archivo que se commitea sin haber invocado /mcp-setup en toda la sesión. Lo primero es procedimiento; lo segundo es regla y se queda.

Si en algún momento notas que una de las reglas movidas deja de cumplirse, el arreglo es traerla de vuelta, no reescribir el comando.