---
name: harness-claude-code
description: >
  Disciplina operacional del harness de Claude Code para reducir consumo de
  tokens y proteger el cache de prompt. Cubre las 4 causas raíz de quemar
  cuota antes de tiempo (cache misses, context bloat, modelo/effort
  incorrecto, formato de input ineficiente), 5 session moves (compact,
  clear, rewind, sub-agentes, skills as agents), variables de entorno
  recomendadas, tag files con @, /effort per-prompt y route-out a OpenRouter.
  Cargar cuando el usuario reporte "se acabó la cuota", se prepare una
  sesión Opus larga (>2h), se planifique adopción de MCP servers, o se
  detecte context-rot recurrente.
version: "1.0.1"
evolved: false
herramientasPermitidas: [Read]
exclusiones:
  - "No cargar para teoría general de context-rot y compactación — usar `compactacion-contexto`. Este skill cubre operación day-to-day del harness Claude Code; aquel cubre principios de gestión de contexto independientes de la herramienta."
  - "No cargar para diseño/escritura de skills SWL — usar `meta-skills-estandar` y `reglas/skills-estandar.md`. Este skill cubre uso eficiente de skills, no su construcción."
  - "No cargar para resolución de errores específicos del runtime (CLI no arranca, MCP no conecta) — esos son problemas técnicos del CLI, no del harness operacional."
  - "No cargar para análisis de costo histórico o dashboards — usar `swl-dashboard` o `/swl:status metricas`. Este skill cubre PREVENCIÓN del gasto excesivo, no el reporte post-hoc."
evolvable: true
---

# Harness Claude Code — disciplina operacional

Origen: artículo "Claude Code's Limits Are Generous. The Problem Is Your
Harness." más experiencia operativa SWL.

Tesis: los límites de Claude Code Max son generosos. Si te quedaste sin
cuota antes de tiempo, no es Anthropic — es tu harness (configuración +
sesión + tools + modelo + formato de input). Cuatro causas raíz, todas
del lado del usuario.

## Cuándo cargar

- El usuario reporta "se acabó la cuota antes de tiempo".
- Se diagnostica una sesión con context-rot recurrente o alertas críticas
  falsas/persistentes.
- Se prepara una sesión Opus larga (>2h) o adopción de MCP servers nuevos.
- Se va a ejecutar un workflow agéntico complejo y se quiere protección
  proactiva del cache.

## Cuándo NO cargar

- La tarea es entender principios generales de compactación de contexto
  independientes del tool — usar `compactacion-contexto`.
- Se va a escribir un skill SWL nuevo — usar `meta-skills-estandar`.
- El problema es un error del runtime (CLI no inicia, MCP no responde) —
  ese es problema técnico, no operacional.
- Se quiere ver costo histórico — usar `swl-dashboard` o `/swl:status metricas`.

---

## Las 4 causas raíz

### 1. Cache misses

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

| Operación | Costo |
|-----------|-------|
| Cache read | 0.1× (90% descuento) |
| Cache write 5min | 1.25× |
| Cache write 1h | 2× (solo API) |
| Cache refresh on hit | gratis |

Cada hit resetea el TTL sin costo. El prefijo se mantiene caliente mientras
no cambie. **Hit rate sano: ~90% en 5-min default.**

**Reglas operacionales** (detalle completo en
[disciplina-harness-regla](recursos/disciplina-harness-regla.md) — ex-regla
`reglas/harness-claude-code.md`, absorbida aquí porque su propio texto decía
"no es de carga obligatoria global" y este skill es su canal bajo demanda):

- NO agregar/quitar MCP servers mid-session
- NO usar `/model` mid-session
- NO modificar tools permitidos mid-session
- Si necesitas cambio: `/clear` y reinicia

Si el hit rate cae bajo 80%, algo en el harness está invalidando el prefijo
entre turnos. Investigar antes de seguir trabajando.

### 2. Context bloat

Para Opus 4.7 el default es 1M context. Es caro y rara vez necesario.

**Variables de entorno recomendadas** para sesiones largas:

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

NO son universales — solo si el codebase no requiere 1M y se ve context
bloat real. Para sesiones que sí necesitan 1M (análisis de codebase
masivo), dejar el default.

### 3. Modelo y effort incorrectos

**3 dials separados**: modelo de sesión, modelo de delegación, effort por prompt.

**Modelo de sesión** (lock al inicio):
- Sonnet session: barato; sin acceso a Opus en padre. Bueno si todo cabe en Sonnet.
- Opus session + delegate: padre con Opus para planning/tradeoffs; sub-agentes
  Sonnet/Haiku para tactical work. Default para trabajo mixto.

**`/effort` per-prompt** (no per-session):

| Level | Cuándo |
|-------|--------|
| `/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 Opus 4.7 |
| `/effort max` | diminishing returns; raramente vale 2× costo extra |

### 4. Formato de input ineficiente

| Input | Costo bruto | Solución |
|-------|-------------|----------|
| PDF directo via Read tool | Carga como imagen, ~10× tokens | `pdftotext` o `markitdown` ANTES |
| Página web dinámica | Playwright + screenshots | `agent-browser` (~82% menos tokens) |
| Codebase grande (>500 archivos) | Re-lectura completa cada review | `code-review-graph` pip (6.8-49× menos tokens) |
| Vague prompt | Múltiples turnos para clarificar | Spec prompt: rutas, componentes, I/O, restricciones |

---

## Las 5 session moves

### Move 1 — `/compact` proactivo al 50% o tras cada tarea grande

NO esperes al auto-compact. El auto dispara tarde, empuja el contexto
sobre el threshold y obliga a recargar prefijo.

### Move 2 — `/clear` entre tareas no relacionadas

Sesión nueva = prefijo fresco. Si pasas de frontend a backend, abre nueva.

### Move 3 — `/rewind` cuando un turno salió mal

Más barato que pelear con contexto contaminado. Especialmente útil tras
una respuesta del modelo que tomó dirección incorrecta.

### Move 4 — Sub-agentes para trabajo paralelizable o bulk

Bloque a copiar en CLAUDE.md del proyecto:

```markdown
## Task Delegation

Spawn sub-agentes para aislar contexto, paralelizar trabajo
independiente o procesar tareas bulk-mecánicas. NO spawnear cuando el
padre necesita el razonamiento, cuando la síntesis requiere mantener
todo junto, o cuando el spawn overhead domina.

Modelo más barato que pueda hacer la subtarea bien:
- Haiku: bulk mecánico, sin juicio
- Sonnet: research scoped, exploración de código, síntesis in-scope
- Opus: subtareas con planning real o tradeoffs

Si un sub-agente detecta que necesita un tier más alto que el suyo,
regresa al padre. El padre es dueño del output final y la síntesis
cross-spawn.
```

### Move 5 — Skills as agents (`agent: true` + `model:`)

Patrón Anthropic nativo: agregar `agent: true` y `model:` al frontmatter
de un SKILL.md y el skill se ejecuta en su propio sub-agente con su
propio modelo.

Ejemplo: skill `tldr-pdf` con `agent: true, model: sonnet`. El padre le
pasa una ruta de PDF; el skill extrae con `pdftotext`, lee el output,
devuelve 200 palabras al padre. El PDF completo nunca toca el contexto
del padre.

Útil para: procesamiento de archivos grandes, búsqueda en codebase,
extracción de bullets de docs largos. Ver detalles en
`Skill("meta-skills-estandar")` sección "Skills as agents".

---

## Tag files con `@`

En lugar de pedirle a Claude que busque, dale la ruta directamente:
`@ docs/diseno.md ¿qué cambios hace falta para X?` evita tool calls de
Glob/Grep — es 1 sola lectura.

---

## Route in vs route out

### Route in — modelo del padre en CLAUDE.md

Documenta delegación explícita en CLAUDE.md del proyecto. Opus 4.7
delega menos por defecto que 4.6, hay que pedirlo de forma explícita
(ver bloque de Task Delegation arriba).

### Route out — usar otro provider

Si llegas al límite de Pro/Max/Team pero quieres mantener la interfaz de
Claude Code:

```jsonc
// .claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "{API-KEY}",
    "ANTHROPIC_API_KEY": ""
  },
  "model": "z-ai/glm-5.1"
}
```

GLM-5.1 ≈ Opus a ~1/12× del costo. Trade-off: cambias de modelo, sí o
sí pierdes el cache cuando vuelves a Anthropic.

---

## Watch the number — cómo medir

| Necesidad | Herramienta |
|-----------|-------------|
| Histórico Pro/Max/Team | `/swl:status dashboard` (basado en `phuryn/claude-usage`) |
| Tokens/costo de la sesión actual | `/swl:status metricas` |
| Porcentaje de contexto usado en vivo | `hooks/linea-estado.js` (status bar) |
| Alertas cuando contexto se llena | `hooks/monitor-contexto.js` (WARNING ≥65%, CRITICAL ≥75%) |
| Hit rate de cache (API users) | `platform.claude.com/usage/cache` |

Sin observar la métrica, no puedes optimizarla.

---

## Carga lean — qué desactivar

- MCP servers que no se usan en el proyecto actual.
- Skills oficiales de Anthropic que no aplican al stack.
- Tools permitidos: solo los necesarios. Cada tool extra alarga el
  system prompt y reduce el ratio cache hit.
- Reglas largas en CLAUDE.md → mover a skills (progressive disclosure
  SWL ya lo hace por defecto).

---

## Anti-patrones

- **Invocar Claude Code y luego decidir el modelo**: invalida cache.
- **MCP server "temporal" agregado durante la sesión**: el costo de
  invalidar el prefijo supera lo que el server aporta.
- **`/effort max` por reflejo**: 2× costo sin mejora observable salvo
  en tareas de razonamiento profundo.
- **PDFs vía Read sin pre-procesar**: ~10× tokens vs `markitdown`.
- **Pedir a Claude que busque archivos que ya conoces**: gasta tool
  calls innecesarios. Usa `@ ruta.md`.
- **No usar `/compact`** y esperar al auto-compact: dispara tarde y caro.
- **Cambiar de modelo a media sesión**: invalida cache + pierde
  contexto coherente.

---

## Gotchas / Errores comunes no obvios

- **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1` aplicado por default a todos los proyectos**: causa truncado de contexto en sesiones que sí requieren 1M (análisis masivo de codebase, refactor cross-module). Causa: tomar la recomendación del artículo como universal. Solución: aplicar SOLO en proyectos donde se observe context bloat real. Para análisis profundos, dejar el default 1M.
- **Sub-agentes Sonnet/Haiku que delegan al padre Opus pidiendo "más razonamiento"**: el padre acaba haciendo el trabajo que se quería offloadear. Causa: spec del sub-agente vaga. Solución: el padre debe hacer una spec clara con criterios de aceptación; sub-agentes solo escalan si encuentran tradeoff arquitectónico explícito, no por dificultad genérica.
- **`/clear` mid-session destruye el plan en curso**: usuario pierde el roadmap acumulado. Causa: confundir `/clear` con `/compact`. Solución: `/compact` resume manteniendo conocimiento; `/clear` empieza desde cero. Antes de `/clear`, escribir un handoff a `.planning/COMPACTACION.md` con `/swl:compactar`.
- **Tag files con `@` apuntando a archivos enormes**: Claude carga el archivo completo en contexto aunque solo necesite una sección. Causa: usar `@` con archivos >500 líneas. Solución: para archivos grandes, citar sección específica en el prompt (`@ src/auth.py líneas 100-150`) o pre-extraer con `Read offset/limit`.
- **`/effort high` que se queda activo en prompts simples**: el siguiente prompt trivial gasta 2× tokens innecesarios. Causa: el effort se interpreta como "session-wide" cuando es per-prompt. Solución: explícito `/effort medium` (o lo que aplique) en el siguiente prompt si la complejidad bajó.
- **`child_process.spawn(cmd, args, { env: {} })` REEMPLAZA el env del padre con vacío, NO hereda** [CONFIRMADO 2026-05-18]: el cliente MCP de Claude Code (y el de Cursor) lee `mcpServers.X.env` del config JSON y lo pasa literal al spawn. Si la config tiene `"env": {}` explícito, el binario hijo arranca SIN ninguna variable de entorno del padre — rompe la herencia de apiKeys que viven en HKCU/registry. Síntoma: MCP server da `40101 Authorization required` aunque `setx OBSIDIAN_API_KEY` esté correcto en HKCU y curl con esa key responda HTTP 200 al plugin. Causa: Node `child_process.spawn` con `env: {}` ≠ sin `env` option. Solución: **OMITIR la clave `env` por completo en el JSON** (no dejarla vacía). Verificado empíricamente con `spawn(binario, [], { /* sin env */ })` → binario heredó `OBSIDIAN_API_KEY`; `spawn(binario, [], { env: {} })` → binario sin env. El patch SWL para Python (`scripts/lib/mcp_config.py::build_stdio_env`) merge `os.environ + overrides` para corregir el mismo síntoma en el lado Python.
- **MCP server devuelve auth error con apiKey correcta en disco → el proceso vivo arrancó con apiKey vieja** [CONFIRMADO 2026-05-18]: aunque `~/.cursor/mcp.json` y `~/.claude/settings.json` tengan la apiKey actual del plugin, los procesos del binario MCP (ej. `mcp-obsidian.exe`) que ya están corriendo retuvieron la apiKey del momento de su spawn. Síntoma: actualizar JSONs no soluciona 40101. Solución: `taskkill /F /IM mcp-obsidian.exe /T` (Windows) o `pkill mcp-obsidian` (Unix) + **quit total del cliente parent** (Cursor.exe / claude.exe) — no basta reload de ventana. Al reabrir, el cliente respawnea el binario con env actual. Verificar con `ps -W | grep mcp-obsidian` que solo haya procesos con timestamp posterior al reinicio.
- **Cursor y Claude Code CLI dentro de Cursor son clientes MCP DISTINTOS con procesos independientes** [CONFIRMADO 2026-05-18]: cuando se ejecuta Claude Code CLI en una terminal embebida de Cursor, hay DOS procesos del binario MCP corriendo simultáneamente — uno por cliente. Cada uno lee SU PROPIA config: Cursor lee `~/.cursor/mcp.json`, Claude Code CLI lee `~/.claude/settings.json` + `<proyecto>/.claude/settings.local.json`. Una apiKey actualizada en uno no propaga al otro. Síntoma observado: el agente AI de Cursor responde MCP OK pero Claude Code CLI da 40101 (o viceversa). Solución: usar variable de entorno persistente del SO (`setx OBSIDIAN_API_KEY` → HKCU\Environment) como single source of truth y dejar configs JSON sin clave `env` para heredar del padre. Cada regeneración de apiKey requiere un solo `setx` + reiniciar Cursor (que reinicia ambos clientes).

---

## Integración con SWL

Componentes SWL que cubren necesidades de harness: `/swl:compactar`,
`/swl:checkpoint`, `/swl:status dashboard`, `/swl:status metricas`, `/swl:modelo`,
`/swl:contexto`, hooks `linea-estado.js` + `monitor-contexto.js`,
`/swl:revisar-impacto` (meta-grafo del sistema SWL) y `code-review-graph`
pip (opt-in para codebase del usuario, ver `MANUAL_USO.md`).

Cargar este skill cuando esos componentes no son suficientes y hace falta
el modelo mental completo del harness.

---

## Checklist antes de iniciar sesión Opus larga

- [ ] `.claude/settings.json` con todos los MCP necesarios YA configurados
- [ ] Modelo elegido y bloqueado (no se cambiará durante la sesión)
- [ ] Tools permitidos definidos antes de iniciar
- [ ] `CLAUDE_CODE_DISABLE_1M_CONTEXT` y `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`
      configurados si la sesión es larga sin necesidad de 1M
- [ ] Plan de delegación claro (qué se manda a sub-agente, qué se mantiene
      en el padre)
- [ ] PDFs/Office docs pre-procesados con `markitdown`
- [ ] Para repos grandes: `code-review-graph` instalado y `build` ejecutado
- [ ] CLAUDE.md del proyecto con bloque de Task Delegation
- [ ] Saber dónde ver métricas durante la sesión (`/swl:status metricas`)
