El mapa de piezas: qué va en cada lugar

El CLAUDE.md del repositorio cobra-api empezó con quince líneas. Hoy tiene más de trescientas: convención de commits, procedimiento para emitir un CFDI, revisión de endpoints de pagos, cómo consultar staging y un "nunca hagas commit de .env". Daniela, la líder técnica de Cobra Fácil, nota que Claude a veces ignora reglas y que cada sesión arranca con el contexto ya cargado.

El problema no es que falten instrucciones, sino que todo está en el mismo lugar. Claude Code tiene siete piezas y cada una carga en un momento distinto, cuesta distinto y garantiza cosas distintas.

Al terminar podrás:

• explicar qué resuelve cada pieza y cuándo entra al contexto;
• distinguir lo que es una petición a Claude de lo que es una garantía;
• usar una tabla de decisión para ubicar cualquier instrucción;
• reorganizar un CLAUDE.md saturado en las piezas correctas.

Las siete piezas

CLAUDE.md. Contexto persistente que Claude lee al inicio de cada sesión, completo. Sirve para hechos y reglas que importan siempre: comandos de build, estructura del proyecto, convenciones básicas. La documentación recomienda mantenerlo por debajo de 200 líneas y mover el material de referencia a otras piezas.

Skills. Instrucciones, conocimiento o flujos en un archivo SKILL.md. Al inicio Claude solo ve el nombre y la descripción; el contenido completo entra cuando tú la invocas con /nombre o cuando Claude decide que es relevante. Pueden ser material de referencia o un procedimiento.

Comandos. Los comandos de .claude/commands/ se fusionaron con las skills: .claude/commands/deploy.md y .claude/skills/deploy/SKILL.md crean el mismo /deploy. Los archivos viejos siguen funcionando; si existen ambos, gana la skill.

Subagentes. Trabajadores con su propia ventana de contexto, prompt de sistema y herramientas. Hacen el trabajo pesado aparte y devuelven solo un resumen a tu conversación.

Hooks. Comandos, peticiones HTTP, llamadas MCP, prompts o subagentes que Claude Code ejecuta en eventos del ciclo de vida, como antes de usar una herramienta (PreToolUse) o después de editar (PostToolUse). Se disparan siempre que ocurre el evento y no consumen contexto salvo que devuelvan salida.

MCP. Conexiones a sistemas externos: bases de datos, navegadores, Slack. Al inicio se cargan los nombres de las herramientas; los esquemas completos esperan hasta que Claude los necesita.

Plugins. La capa de empaquetado: skills, subagentes, hooks y servidores MCP en una unidad instalable, con nombres prefijados (como /cobra-kit:validar-cfdi). Se distribuyen desde un marketplace.

Cuándo carga cada pieza y qué garantiza

Esta tabla es la que conviene tener a la mano. Resume lo que dice la documentación oficial sobre carga y costo de contexto:

La columna de la derecha es la más importante. Una frase como "nunca edites .env" en CLAUDE.md o en una skill es una petición. Un hook PreToolUse que bloquea la edición es una garantía. Si una regla debe cumplirse siempre, va en un hook.

La tabla de decisión

Cuando tengas una instrucción y no sepas dónde ponerla, recorre estas preguntas en orden. La primera respuesta "sí" te da la pieza.

Dos matices que evitan errores frecuentes:

• Skill o subagente. Una skill agrega contenido a tu ventana actual; un subagente trabaja en una ventana aparte. Si quieres que Claude sepa algo mientras trabaja contigo, es una skill. Si quieres que alguien lea cincuenta archivos y te devuelva cinco líneas, es un subagente.
• Skill o hook. Si el paso requiere criterio ("¿el mensaje describe bien el cambio?"), es una skill. Si es mecánico ("rechaza si no empieza con un tipo válido"), es un hook.

Caso práctico: desarmar el CLAUDE.md de Cobra Fácil

Este es un fragmento del CLAUDE.md actual de cobra-api:

# cobra-api

## Comandos
- Instalar: uv sync
- Pruebas: uv run pytest
- Servidor local: uv run fastapi dev app/main.py

## Reglas
- Montos siempre con Decimal, nunca float.
- Nunca hagas commit de .env ni de certificados .cer/.key del SAT.
- Commits: <tipo>(<alcance>): <resumen>. Tipos: agrega, corrige, cambia,
  elimina, docs, pruebas, mant. Resumen en minúsculas, máximo 72 caracteres.

## Cómo emitir un CFDI
1. Arma el XML con app/facturacion/builder.py.
2. Revisa RFC de emisor y receptor, régimen fiscal y código postal.
3. Revisa que la suma de conceptos cuadre con SubTotal y que Total cuadre
   con impuestos trasladados y retenidos.
4. Si MetodoPago es PPD, FormaPago debe ser 99.
... (60 líneas más con catálogos del SAT)

## Revisión de pagos
Antes de aprobar cambios en app/pagos/, revisa: verificación de firma
de webhooks, llaves de idempotencia, autenticación de cada ruta,
que no se registren CLABE ni datos de tarjeta en logs...
(40 líneas más)

## Consultar staging
Pide la cadena de conexión a Iván y usa psql con...

Con la tabla de decisión, cada sección encuentra su lugar:

El resultado en disco queda así:

cobra-api/
├── CLAUDE.md                      # 25 líneas: comandos y reglas breves
└── .claude/
    ├── settings.json              # hooks y permisos
    ├── hooks/
    │   └── validar_commit.py
    ├── skills/
    │   ├── convenciones-commits/
    │   │   └── SKILL.md
    │   └── validar-cfdi/
    │       ├── SKILL.md
    │       ├── references/
    │       └── scripts/
    └── agents/
        └── revisor-pagos.md

Y el CLAUDE.md nuevo cabe en una pantalla:

# cobra-api

API de cobranza de Cobra Fácil. Python 3.12, FastAPI, PostgreSQL.

## Comandos
- Instalar: uv sync
- Pruebas: uv run pytest
- Servidor local: uv run fastapi dev app/main.py

## Reglas
- Montos siempre con Decimal, nunca float.
- Facturación: usa la skill validar-cfdi antes de timbrar.
- Cambios en app/pagos/: pide revisión al subagente revisor-pagos.

Las dos últimas líneas no repiten el procedimiento: solo le recuerdan a Claude que existe la pieza adecuada. A lo largo del curso construyes cada una de esas piezas.

Combinaciones que vas a usar

Las piezas se combinan. La documentación describe patrones como skill + MCP (el servidor da la conexión, la skill documenta el esquema y las consultas), skill + subagente (una skill lanza subagentes o corre en uno con context: fork) y CLAUDE.md + skills (CLAUDE.md dice "sigue nuestras convenciones", la skill tiene la guía completa). A eso suma hook + skill: el hook garantiza lo mecánico y la skill explica cómo corregir lo que el hook rechaza.

Práctica

1. Abre el CLAUDE.md de un proyecto tuyo, cuenta sus líneas y mide con /context cuánto ocupa la memoria en una sesión nueva.
2. Pasa cada sección por la tabla de decisión y arma una tabla como la del caso práctico: sección, pieza, por qué.
3. Marca las reglas que Claude incumple a veces y decide si deberían ser hooks.
4. Identifica el procedimiento más largo de tu CLAUDE.md. Será tu candidato para la skill de la lección 1.2.
5. Identifica una tarea que llena tu contexto con salida que no vuelves a leer. Será tu candidato para el subagente del módulo 2.
6. Guarda tu tabla en notas/mapa-de-piezas.md. La vas a usar durante todo el curso.

Resumen

• Claude Code tiene siete piezas: CLAUDE.md, skills, comandos (ya fusionados con skills), subagentes, hooks, MCP y plugins.
• Cada pieza carga en un momento distinto: CLAUDE.md siempre, skills al usarse, subagentes en su propia ventana, hooks fuera del contexto.
• Solo los hooks garantizan que algo ocurra; lo demás son instrucciones que Claude interpreta.
• La tabla de decisión ordena las preguntas: siempre, sistema externo, cada sesión, a veces, mucha salida, otro repositorio.
• Un CLAUDE.md corto que apunta a skills y subagentes funciona mejor que uno largo que lo contiene todo.

Quiz