# 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. ### `/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:dashboard`** — dashboard histórico de uso (basado en `phuryn/claude-usage`). - **`/swl: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")`.