# Regla: Harness de Claude Code — disciplina operacional

Esta regla aplica al uso operativo de Claude Code (CLI / Desktop / IDE).
Define las prácticas que protegen la economía de tokens, el cache de prompt y
la calidad de las respuestas. Origen: artículo "Claude Code's Limits Are
Generous. The Problem Is Your Harness." más experiencia operativa SWL.

El harness es el conjunto de configuración + sesión + tools + modelo que
rodea a Claude. Anthropic provee el modelo; el harness lo provees tú. Una
mala disciplina del harness convierte una suscripción Max generosa en
"se acabó la cuota en 2 días".

---

## Disciplina del cache de prompt

El prompt cache es la palanca económica más grande de Claude Code:

- **Cache read**: 0.1× del precio de input (90% de descuento).
- **Cache write 5min TTL**: 1.25×.
- **Cache write 1h TTL**: 2× (solo API, no incluido en Pro/Max/Team).
- **Cache refresh on hit**: gratis (se cobra al precio read).

Cada hit en un prefijo cacheado resetea su TTL sin costo. Una sesión larga
con uso constante de tools mantiene el prefijo caliente indefinidamente
**siempre que el prefijo no cambie**.

### Reglas de cache discipline

- **NUNCA agregues o quites MCP servers a mitad de sesión.** Modifica
  `.claude/settings.json` antes de iniciar Claude Code, no durante.
- **NUNCA uses `/model` a mitad de sesión.** Cambiar de modelo invalida
  el prefijo cacheado y fuerza una re-lectura completa.
- **NUNCA modifiques la lista de tools permitidos a mitad de sesión.**
  Agregar o quitar tools cambia el prefijo del system prompt.
- **Lock-at-session-start**: define configuración, modelo, MCP servers y
  tools permitidos antes de iniciar. Si necesitas cambiar algo, abre una
  sesión nueva con `/clear` o cierra y reinicia.
- **Hit rate sano**: ~90% en el TTL de 5 minutos por defecto. Si el hit
  rate cae por debajo del 80%, hay algo en el harness que invalida el
  prefijo entre turnos.

### Cuándo SÍ es OK abrir nueva sesión

- Cambio de proyecto / repo.
- Cambio entre tareas no relacionadas (frontend vs. backend).
- Tras un turno que salió mal y quiere descartarse (`/rewind` o `/clear`).
- Cada 30+ turnos en sesiones de exploración para evitar context-rot.

---

## Manejo de contexto

### Variables de entorno opt-in (recomendadas para sesiones largas)

```jsonc
// .claude/settings.json (sección env)
{
  "env": {
    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1",        // forzar 200K en lugar de 1M
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80"       // disparar auto-compact al 80%
  }
}
```

- **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`** desactiva la variante 1M de Opus
  4.7 y vuelve al techo histórico de 200K. Útil cuando el codebase del
  usuario no requiere 1M y se quiere reducir costo de tokens. **NO se
  recomienda como default universal** — solo si el usuario detecta
  context bloat real.
- **`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80`** ajusta el umbral del
  auto-compact. Disparar al 80% en lugar del default permite que la
  compactación ocurra antes de que el contexto sature.

### Cinco movimientos de sesión

- **`/compact` al 50% de uso o tras cada tarea grande.** No esperes al
  auto. La compactación tardía empuja el contexto encima del threshold y
  obliga a recargar prefijo.
- **`/clear` entre tareas no relacionadas.** Sesión nueva = prefijo
  fresco, sin lastre acumulado.
- **`/rewind` cuando un turno salió mal.** Más barato que pelear con
  contexto contaminado.
- **Sub-agentes** para trabajo bulk-mecánico, búsqueda en codebase, o
  procesamiento de archivos grandes (PDF→TLDR). El padre conserva
  contexto limpio.
- **Tag files con `@`**: en lugar de pedirle a Claude que busque, pásale
  la ruta directamente. `@docs/diseno.md` evita un round-trip de grep.

---

## Routing de modelos y effort

### Escoger el modelo al inicio (no a media sesión)

- **Sonnet session**: más barato, sin acceso a Opus en el padre. Bueno
  cuando se sabe que el trabajo cabe en Sonnet.
- **Opus session + delegate**: pagar Opus solo en el padre (planning,
  tradeoffs); delegar trabajo táctico a sub-agentes Sonnet/Haiku. Default
  para trabajo mixto.
- Cambiar de modelo a media sesión invalida el cache (regla de cache
  discipline arriba). Si necesitas otro modelo, abre nueva sesión.

### Knobs nativos para sub-agentes y teams (env vars del harness)

Claude Code expone variables de entorno que controlan el routing de
modelos y el costo de sesiones con múltiples agentes. Son del **harness
Anthropic**, no de swl-ses — complementan, no reemplazan, el Model-Tier
por frontmatter (`model:` en cada agente) ni el `budget-enforcer.js`.

```bash
# Forzar el modelo de TODOS los sub-agentes/teammates a uno más barato.
# Útil en sesiones ad-hoc donde no quieres routing granular por agente.
# El líder mantiene el modelo de la sesión (Opus); los teammates bajan a Sonnet.
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-6"

# Habilitar Agent Teams nativo (experimental): un líder coordina teammates
# que se comunican entre sí vía task list compartida. swl-ses NO lo usa por
# defecto — su patrón es orquestador-swl + Agent tool. Activar solo para
# experimentar con coordinación teammate-to-teammate.
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
```

```bash
# Cap de costo nativo por sesión headless/team. Aborta la sesión completa
# al alcanzar el límite, sin importar cuántos agentes estén activos.
claude -p "build the auth system" --max-budget-usd 15.00
```

**Relación con la infra de swl-ses:**

| Knob nativo | Equivalente swl-ses | Cuándo usar el nativo |
|-------------|---------------------|------------------------|
| `CLAUDE_CODE_SUBAGENT_MODEL` | `model:` en frontmatter de cada agente (Model-Tier) | El frontmatter es **superior** (granular por agente). El env var solo para sesiones ad-hoc sin SWL o como override global temporal |
| `--max-budget-usd` | `scripts/lib/budget-enforcer.js` (4 niveles + idempotency) + `hooks/tracking-costos.js` | El `budget-enforcer` es **superior** (warning/approval/backpressure/hard). El flag nativo es un cap duro complementario para sesiones de orquestador con muchos sub-agentes en paralelo |
| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | `orquestador-swl` + Agent tool | swl-ses prefiere su patrón. El nativo solo para experimentación — su modelo teammate-to-teammate no está integrado con los hooks de gobernanza SWL |

**Anti-patrón**: usar `CLAUDE_CODE_SUBAGENT_MODEL` como reemplazo del
Model-Tier por frontmatter. Pierde la granularidad (revisor-seguridad
necesita Opus aunque sea teammate). Usar solo como override de sesión,
nunca persistente en `.bashrc` si trabajas con swl-ses.

### `/effort` per-prompt (no per-session)

```
/effort low      # fixes rápidos, tareas mecánicas
/effort medium   # la mayoría de prompts (gran ahorro vs default)
/effort high     # razonamiento exigente
/effort xhigh    # default para coding agéntico (4.7)
/effort max      # diminishing returns, raramente vale el ~2× costo extra
```

El effort se aplica al **prompt** que lo necesita, no al resto de la
sesión. Subir a `max` por reflejo en cada turno duplica el costo sin
mejora observable.

---

## Disciplina de input format

Algunos formatos consumen muchos más tokens de los necesarios:

- **PDFs**: usar `pdftotext` o `markitdown` ANTES, no el Read tool con
  PDF directo (Read carga PDF como imágenes). Ver `reglas/markitdown.md`.
- **Páginas web dinámicas**: `agent-browser` (vía accessibility tree)
  reduce ~82% tokens vs Playwright MCP / screenshots.
- **Repos grandes (>500 archivos)**: considerar `code-review-graph` pip
  (opt-in) que reduce 6.8-49× tokens por review al leer solo blast
  radius. Documentado en `MANUAL_USO.md` sección "Dependencias externas".
- **Spec prompts > vague prompts**: incluir rutas de archivo, componentes
  esperados, I/O y restricciones. Vago = más turnos = más tokens.

---

## Carga lean de componentes

- Desactivar MCP servers no usados en `.claude/settings.json`.
- Mover reglas largas de CLAUDE.md a skills cargados bajo demanda
  (progressive disclosure SWL ya hace esto).
- Comandos slash `/swl:*` que no usas no cuestan tokens si no se invocan.
- Skills oficiales de Anthropic: solo agregar los que aplican al
  proyecto (Office docs solo si trabajas con Office, etc.).

---

## Anti-patrones

- **Invocar Claude Code y luego decidir el modelo**: invalida cache cada
  vez que cambias de opinión.
- **Agregar un MCP server "temporal" durante la sesión**: el costo de
  invalidar el prefijo cacheado supera lo que el server agrega.
- **Re-leer manualmente archivos que ya están en contexto**: si Claude
  ya leyó X, pedirle que lo lea de nuevo es token waste.
- **No usar `/compact` y esperar al auto-compact**: el auto dispara
  TARDE. Compactar proactivamente al 50% es siempre más eficiente.
- **`/effort max` por reflejo**: 2× costo de xhigh con mejora marginal
  fuera de tareas que requieran razonamiento profundo.
- **PDFs vía Read tool sin extraer texto antes**: 10× más tokens que
  pasar por `markitdown` o `pdftotext`.

---

## Observabilidad — watch the number

SWL incluye:

- **`/swl:status dashboard`** — dashboard histórico de uso (basado en
  `phuryn/claude-usage`).
- **`/swl:status metricas`** — métricas de la sesión actual (tokens, costo
  estimado, modelos usados).
- **`hooks/linea-estado.js`** — barra de estado con porcentaje de
  contexto consumido (con detección dinámica del techo según modelo —
  ver fix v5.12.4).
- **`hooks/monitor-contexto.js`** — alertas WARNING (≥65%) y CRITICAL
  (≥75%) cuando el contexto se llena.

Si no ves el hit rate de cache, no puedes optimizarlo. Para uso intenso
considera dashboard externo en `platform.claude.com/usage/cache` (solo
API users).

---

## Checklist de harness antes de empezar una sesión larga

- [ ] `.claude/settings.json` con MCP servers necesarios YA configurado
- [ ] Modelo elegido y bloqueado (no se cambiará durante la sesión)
- [ ] Tools permitidos definidos en `.claude/settings.json`, no se
      modificarán mid-session
- [ ] Variables de entorno (`CLAUDE_CODE_DISABLE_1M_CONTEXT`,
      `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`) configuradas si es sesión larga
- [ ] CLAUDE.md del proyecto referencia archivos clave para que Claude
      no haga grep innecesario
- [ ] Para repos grandes: `code-review-graph` instalado (opt-in)
- [ ] Estrategia de delegación clara: qué se manda a sub-agente y qué
      se mantiene en el padre
- [ ] PDFs / Office docs serán pre-procesados con `markitdown` antes de
      Read

---

## Cómo cargar esta regla

Esta regla no es de carga obligatoria global. Cargar cuando:

- El usuario reporta "se acabó la cuota antes de tiempo".
- Se diagnostica context-rot u alertas críticas falsas/persistentes.
- Se prepara una sesión de trabajo larga (>2h) con Opus.
- Se planifica adopción de MCP servers nuevos en un proyecto.

Para detalles operacionales adicionales (workflow de las 5 session moves,
cuándo usar cada effort level, integración con SWL), cargar también
`Skill("harness-claude-code")`.
