@saulwade/swl-ses 1.4.1 → 1.5.0

package/reglas/harness-claude-code.md

@@ -1,213 +1,213 @@
-# 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")`.
+# 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")`.