The Five-Subsystem Framework
Todo harness se compone de cinco subsistemas. Cada uno resuelve un problema específico en la confiabilidad del agente.
Recipe Shelf
Problema: El agente no sabe por dónde empezar ni qué priorizar.
Solución: Un AGENTS.md corto (~50-100 líneas) como routing layer. Apunta a docs/ detallados. Progressive disclosure.
Componentes: AGENTS.md, CLAUDE.md, docs/ARCHITECTURE.md, docs/DESIGN.md, docs/PLANS.md
Anti-patrón: Un solo archivo de 500+ líneas que el agente ignora parcialmente.
Prep Station
Problema: El agente pierde estado entre sesiones — no sabe qué se ha hecho ni qué falta.
Solución: feature_list.json como fuente única de verdad del progreso. Cada feature tiene id, nombre, dependencias, estado, y evidencia.
Componentes: feature_list.json, progress.md, session-handoff.md
Anti-patrón: Mantener estado solo en la mente del agente o en issues de GitHub no trackeados.
Quality Check Window
Problema: El agente declara "done" sin verificar que el código compile, los tests pasen, o la feature funcione.
Solución: Comandos de verificación explícitos en AGENTS.md. init.sh corre verificación automática. Quality gates antes de marcar "done".
Componentes: test suite, type checks, linting, build verification, e2e tests
Anti-patrón: Confiar en que el agente "sabe" cuando algo está correcto.
Task Boundaries
Problema: El agente hace más de lo debido — refactoriza lo que no debe, cambia archivos no relacionados.
Solución: One-feature-at-a-time policy. Definition of Done checklist. Feature dependencies documentadas.
Componentes: feature dependencies, definition of done, next-task templates, scope tracker
Anti-patrón: "Ya que estoy aquí, arreglo esto también" — el principal causante de regression bugs.
Session Management
Problema: Cada sesión empieza desde cero — no hay init, no hay handoff, no hay cleanup.
Solución: init.sh para bootstrap. Clean-state checklist para terminar. Session handoff template para continuidad.
Componentes: init.sh, clean-state checklist, handoff procedure, benchmark comparison
Anti-patrón: Depender del agente para recordar dónde quedó la sesión anterior.
Design Patterns
Seis patrones de diseño extraídos del harness-creator skill de OpenClaw. Cada uno resuelve un problema recurrente en la construcción de harnesses.
Memory Persistence
Problema: El agente pierde preferencias, contexto, y feedback entre sesiones.
Solución: Jerarquía de 4 niveles (organización > usuario > proyecto > local). Two-step save invariant: escribe contenido completo, luego apunta en índice. Índice acotado (~200 líneas), archivos temáticos bajo demanda.
Golden rule: Local overrides siempre ganan.
Context Engineering
Problema: El contexto del agente es limitado y caro — ¿qué incluir y qué omitir?
Solución: 4 operaciones: Select (relevancia), Compress (resumir), Isolate (separar por tema), Write (persistir). Budget management: decide qué cabe en el contexto actual.
Golden rule: El contexto es un presupuesto, no un vertedero.
Tool Registry & Safety
Problema: Herramientas poderosas pueden ser peligrosas — ¿cómo dar acceso sin perder control?
Solución: Registro fail-closed (todo denegado por defecto). Permisos por llamada con concurrencia controlada. Pipeline de permisos que rastrea denegaciones y transforma modos.
Golden rule: Fail-closed — todo denegado hasta explícitamente permitido.
Multi-Agent Coordination
Problema: Múltiples agentes trabajando en el mismo proyecto se pisan, duplican trabajo, o producen conflictos.
Solución: 3 patrones: Coordinator (un agente orquesta), Fork (agentes paralelos independientes), Swarm (agentes colaboran en misma tarea). Context sharing controlado.
Golden rule: Fork children must not fork — guard recursivo preserva el invariante de un solo nivel.
Lifecycle & Bootstrap
Problema: Sin un ciclo de vida definido, el agente no sabe cuándo inicializar, cuándo terminar, ni cómo manejar errores.
Solución: Sistema de hooks (pre/post para cada fase). Tareas long-running con notificación. Init con orden de dependencias. Extension system con trust all-or-nothing.
Golden rule: Un hook no confiable deshabilita todo el sistema de extensiones.
Harness Assessment
Problema: ¿Cómo saber si un harness es bueno? ¿Dónde mejorarlo primero?
Solución: Evaluación de 5 puntos por subsistema. Identificar el subsistema con puntuación más baja — ese es el bottleneck. Mejorar allí primero.
Golden rule: El subsistema más débil determina la calidad del harness.
12 Gotchas — Trampas que debes conocer
Estos son los modos de fallo no obvios del harness engineering. Violarlos causa bugs difíciles de diagnosticar.