1. ¿Por qué los agentes capaces aún fallan?
Los modelos de IA son cada vez más potentes, pero siguen fallando en tareas del mundo real. La razón no es el modelo — es el entorno alrededor del modelo. Un agente sin harness tiene:
- Instrucciones ambiguas — El agente no sabe qué leer primero ni cómo priorizar
- Sin memoria de sesión — Cada sesión empieza desde cero
- Sin verificación — El agente declara victoria sin validar
- Scope infinito — El agente hace más de lo debido
- Sin ciclo de vida — No hay init, no hay handoff, no hay cleanup
Lección clave: Los fallos de agentes son casi siempre fallos de harness, no fallos de modelo.
2. ¿Qué es un Harness?
Un harness es el sistema alrededor del modelo que lo hace confiable. El framework de 5 subsistemas:
- Instructions (Recipe Shelf): AGENTS.md, CLAUDE.md — archivos que le dicen al agente cómo trabajar en este proyecto
- State (Prep Station): feature_list.json, progress.md — estado persistente entre sesiones
- Verification (Quality Check Window): Tests, type checks — evidencia de que el trabajo es correcto
- Scope (Task Boundaries): Una feature a la vez, definition of done — límites que evitan overreach
- Lifecycle (Session Management): init.sh, clean-state — bootstrap y handoff entre sesiones
3. El Repositorio como System of Record
El repo debe ser la fuente única de verdad. No documentación externa, no wikis, no conversaciones de Slack. Todo lo que el agente necesita debe estar versionado en el repo:
- AGENTS.md como entry point de routing
- docs/ con arquitectura, diseño, y specs
- feature_list.json con estado de features
- init.sh con setup verificable
Regla de oro: Si el agente necesita saberlo, debe estar en el repo. Si no está en el repo, el agente no puede confiar en ello.
4. Por qué falla un archivo de instrucciones gigante
Un solo AGENTS.md de 500 líneas no funciona. El agente lo ignora parcialmente porque:
- El contexto es limitado — el agente prioriza lo que ve al final
- La información se diluye — instrucciones importantes se pierden en el ruido
- No hay jerarquía — todo parece igual de importante
Solución: Progressive Disclosure. AGENTS.md corto (~50-100 líneas) como routing layer que apunta a docs/ específicos. El agente carga solo lo que necesita cuando lo necesita.
AGENTS.md debe ser un mapa, no una enciclopedia.
5. Tareas largas y continuidad
Las tareas que cruzan múltiples sesiones pierden continuidad. El agente olvida lo que hizo, suposiciones que hizo, y decisiones que tomó. Solución:
- Session handoff: Template que resume estado actual, progreso, blockers, y próximos pasos
- Progress log: feature_list.json con evidencia de cada feature completada
- Checklist de clean state: Antes de terminar una sesión, el agente debe dejar un camino limpio para retomar
6. Inicialización como fase separada
El startup del agente debe ser una fase explícita con init.sh:
- Instalar dependencias
- Correr type checks
- Ejecutar tests
- Verificar que el build funciona
- Cargar estado de features
Sin init.sh, el agente empieza a codificar sobre un entorno que no ha verificado — y los bugs se acumulan.
7-12. Más lecciones clave
7. Overreach y Under-finish
Los agentes o hacen demasiado (overreach) o se detienen antes de terminar (under-finish). Scope tracking y next-task templates corrigen ambos.
8. Feature Lists
Las feature lists son el primitive fundamental del harness. feature_list.json con id, nombre, dependencias, estado, y evidencia.
9. Declarar Victoria Muy Temprano
Los agentes declaran "done" sin verificar. Clean-state checklists y verification gates previenen esto.
10. E2E Testing
Tests end-to-end cambian los resultados — el agente trabaja mejor cuando sabe que hay verificación automatizada.
11. Observabilidad
La observabilidad debe estar dentro del harness, no fuera. Runtime logs, evaluator rubrics, sprint contracts.
12. Clean State
Cada sesión debe dejar el repositorio en un estado limpio y restartable. Benchmark comparison templates miden mejora.