Harnesses efectivos para agentes de larga duración

1 de mayo de 2026 Por: Artiko

agentesclaudearquitecturalong-runningharnessanthropic

Harnesses efectivos para agentes de larga duración

Basado en el artículo de ingeniería de Anthropic: Effective Harnesses for Long-Running Agents por Justin Young (noviembre 2025).

El problema fundamental

Los agentes de IA operan en sesiones discretas sin memoria entre ellas. Cada vez que un agente inicia, parte de cero — sin recordar qué hizo en la sesión anterior, qué archivos modificó, qué falló o qué quedó pendiente.

Es como tener un equipo de ingenieros que trabaja por turnos pero ninguno le deja notas al siguiente. El turno nuevo no sabe en qué estado quedó el sistema, qué decisiones se tomaron, ni qué queda por hacer.

Para tareas cortas esto no importa. Pero cuando una tarea requiere horas o días de trabajo — implementar 200+ features, auditar un codebase entero, migrar una base de datos — la falta de continuidad entre sesiones se convierte en el obstáculo principal.

Patrones de fallo comunes

Antes de la solución, conviene entender por qué fallan los agentes sin harness:

Sobre-ambición al inicio

El agente intenta implementar todo de una vez. A mitad de la implementación, agota el context window. El resultado: código a medio terminar, sin tests, sin commit. La siguiente sesión no sabe que el trabajo comenzó.

Victoria prematura

El agente implementa algunas features, ve progreso, y declara la tarea completada. No tiene forma de saber cuánto falta ni si lo que implementó realmente funciona.

Entorno desconocido

Sin instrucciones explícitas, cada sesión nueva tiene que redescubrir cómo iniciar el servidor, qué scripts existen, qué convenciones sigue el proyecto. Esto consume contexto y tiempo antes de poder hacer trabajo real.

Regresiones silenciosas

Al implementar feature B, el agente rompe feature A. Sin un mecanismo de tracking, no hay forma de detectarlo hasta que alguien lo prueba manualmente.

La solución: arquitectura de dos agentes

La investigación de Anthropic Engineering propone separar la responsabilidad en dos agentes especializados:

flowchart LR
    A[Agente\nInicializador] -->|"crea infraestructura\nen sesión inicial"| B[Harness]
    B --> C[feature-list.json]
    B --> D[claude-progress.txt]
    B --> E[init.sh]
    B --> F[Git con commits]
    G[Agente\nCodificador] -->|"lee harness\nen cada sesión"| B
    G -->|"una feature\npor sesión"| H[Código producción-ready]

Agente Inicializador

Se ejecuta una sola vez al inicio del proyecto. Su trabajo es construir toda la infraestructura de soporte que el agente codificador usará en cada sesión posterior:

Crear init.sh — script que levanta el entorno de desarrollo
Generar feature-list.json — lista exhaustiva de todas las características
Crear claude-progress.txt — registro de actividades y decisiones
Hacer el commit inicial de Git documentando qué archivos creó

La calidad de este trabajo inicial determina qué tan efectivas serán todas las sesiones posteriores.

Agente Codificador

Se ejecuta en cada sesión de trabajo. Su protocolo de inicio es siempre el mismo:

Verificar ubicación con pwd
Leer git log para entender qué se hizo en sesiones previas
Leer claude-progress.txt para contexto adicional
Leer feature-list.json para seleccionar la siguiente tarea
Ejecutar init.sh para levantar el entorno
Correr tests básicos de extremo a extremo
Implementar una sola feature
Hacer commit con mensaje descriptivo
Actualizar claude-progress.txt

Componentes del harness en detalle

feature-list.json

El archivo de features es el corazón del harness. Contiene una descripción estructurada de cada característica del sistema, con pasos de verificación y estado actual:

[
  {
    "category": "functional",
    "description": "El botón 'Nueva conversación' crea una sesión limpia",
    "steps": [
      "Navegar a la interfaz principal",
      "Hacer click en el botón 'Nueva conversación'",
      "Verificar que se creó una nueva conversación",
      "Comprobar que el área de chat muestra estado de bienvenida",
      "Verificar que la conversación aparece en el sidebar"
    ],
    "passes": false
  },
  {
    "category": "visual",
    "description": "Los mensajes del usuario se alinean a la derecha con fondo azul",
    "steps": [
      "Enviar un mensaje cualquiera",
      "Verificar alineación derecha del bubble",
      "Verificar color de fondo #3B82F6",
      "Verificar que el texto es legible (contraste suficiente)"
    ],
    "passes": true
  }
]

Regla crítica: el agente nunca puede eliminar ni modificar tests existentes. Solo puede cambiar passes de false a true cuando implementa correctamente la feature. Remover tests equivale a ignorar funcionalidad rota.

El formato JSON es preferible a Markdown para este archivo: el agente tiene menos tendencia a modificar campos inadecuadamente con JSON que con Markdown.

claude-progress.txt

Archivo de log donde el agente documenta su trabajo en cada sesión:

[2026-04-28 14:32] Sesión 1
- Implementé feature: botón nueva conversación (functional/01)
- El sidebar no actualizaba en tiempo real — usé useEffect con dependencia en conversations
- Problema: el botón no visible en mobile < 380px → agregué breakpoint adicional
- Siguiente: implementar historial de conversaciones

[2026-04-28 17:15] Sesión 2
- Intenté implementar feature de búsqueda — bloqueado por falta de endpoint
- Salté a features visuales: alineación de mensajes (visual/03, visual/04, visual/05)
- Todas pasan tests
- Pendiente: revisar contraste en modo oscuro

Este archivo sirve como memoria persistente entre sesiones. La nueva sesión no recuerda qué hizo la anterior, pero puede leer este archivo y reconstruir el estado del trabajo.

init.sh

Script que el agente ejecuta al inicio de cada sesión para levantar el entorno:

#!/bin/bash
set -e

# Instalar dependencias si hay cambios
if [ package.json -nt node_modules/.package-lock.json ] 2>/dev/null; then
  npm install
fi

# Variables de entorno de desarrollo
export NODE_ENV=development
export API_URL=http://localhost:3001

# Iniciar backend en background
npm run start:api &
API_PID=$!

# Esperar a que el backend esté listo
until curl -s http://localhost:3001/health > /dev/null 2>&1; do
  sleep 1
done

# Iniciar frontend
npm run dev &

echo "Entorno listo. API PID: $API_PID"
echo "Frontend: http://localhost:5173"
echo "API: http://localhost:3001"

Sin este script, cada sesión consume tokens descubriendo cómo levantar el entorno. Con él, el agente puede ejecutar bash init.sh y estar listo en segundos.

Testing con automatización de navegador

Un harness efectivo no solo trackea features — también verifica que funcionan. La investigación de Anthropic muestra que usar Puppeteer MCP (automatización de navegador) mejora significativamente la detección de bugs visuales que no serían detectables solo con código.

El agente codificador debe:

Levantar el servidor con init.sh
Usar Puppeteer para navegar la UI como lo haría un usuario
Verificar cada step de la feature que está implementando
Hacer screenshot si algo se ve incorrecto
Corregir antes de declarar la feature como passes: true

Limitación conocida: los agentes no pueden ver diálogos nativos del navegador (alert, confirm, prompt). Las features que dependen de estos diálogos son difíciles de verificar automáticamente.

Anti-patterns y sus soluciones

Problema	Sin harness	Con harness
Contexto agotado a mitad de implementación	Código a medias, sin commit	Feature definida atomicamente — o completa o no se empieza
Victoria prematura	El agente cree que terminó	Lee feature-list.json: hay 180 features con `passes: false`
Entorno desconocido	30% del contexto en redescubrimiento	`bash init.sh` — listo en 5 segundos
Regresiones silenciosas	Nadie lo sabe hasta QA	Re-run de todos los tests en git log
Pérdida de decisiones de diseño	La siguiente sesión hace lo mismo diferente	`claude-progress.txt` documenta el razonamiento

Principios de diseño del harness

Una feature por sesión

El agente elige una sola feature de la lista, la implementa completamente, la verifica, la commitea, y actualiza la lista. Esto garantiza:

Commits atómicos y reversibles con git revert
Contexto enfocado en una sola tarea
Estado siempre limpio al final de la sesión
Fácil identificación de qué commit introdujo qué regresión

Estado producción-ready al terminar

Antes de cerrar la sesión, el agente verifica que el código compila, los tests pasan, y el servidor inicia correctamente. No deja trabajo a medias. La siguiente sesión siempre parte de un estado estable.

Git como fuente de verdad

El historial de Git es la memoria más confiable. El agente lee git log --oneline -20 al inicio de cada sesión para entender el estado reciente del proyecto. Los mensajes de commit deben ser descriptivos:

feat: implementar botón nueva conversación con actualización de sidebar en tiempo real
fix: corregir alineación de mensajes en viewports < 380px
test: verificar historial de conversaciones con 50+ items (paginación)

JSON > Markdown para estado

Para archivos que el agente modifica frecuentemente (como la feature list), JSON es más seguro que Markdown. El modelo tiene menor tendencia a reformatear, reordenar o editar contenido colateral en JSON estructurado.

Extensiones de la arquitectura

La investigación sugiere varias evoluciones del patrón básico:

Multi-agente especializado

En lugar de un único agente codificador, múltiples agentes con roles distintos:

flowchart TD
    H[Harness] --> A[Agente\nImplementador]
    H --> B[Agente\nQA]
    H --> C[Agente\nRevisor de código]
    A -->|"feature implementada"| H
    B -->|"tests pasando"| H
    C -->|"código aprobado"| H

Implementador: escribe el código
QA: verifica con automatización de browser
Revisor: evalúa calidad, performance, accesibilidad

Generalización a otros dominios

El patrón harness no es exclusivo del desarrollo de software. La misma arquitectura aplica a:

Investigación científica: lista de hipótesis a verificar, progreso de experimentos
Análisis financiero: lista de métricas a calcular, estado de cada modelo
Auditoría de código: lista de áreas a revisar, hallazgos por sección

Implementación mínima viable

Para empezar con harnesses en tu propio proyecto:

mi-proyecto/
├── .agent/
│   ├── feature-list.json     # Lista de features con passes: bool
│   ├── claude-progress.txt   # Log de sesiones
│   └── init.sh               # Script de setup del entorno
├── src/
└── ...

System prompt del agente codificador (estructura base):

Eres un agente de implementación incremental. Al inicio de cada sesión:

1. Ejecuta: pwd
2. Ejecuta: git log --oneline -10
3. Lee: .agent/claude-progress.txt
4. Lee: .agent/feature-list.json
5. Ejecuta: bash .agent/init.sh
6. Selecciona UNA feature con passes: false
7. Impleméntala completamente
8. Verifica que funciona (usa browser automation si está disponible)
9. Cambia passes a true en feature-list.json
10. Haz commit con mensaje descriptivo
11. Actualiza claude-progress.txt con lo que hiciste y cualquier decisión de diseño

Reglas:
- Trabaja en una sola feature por sesión
- Nunca elimines ni modifiques tests existentes
- El código debe compilar y los tests deben pasar antes de cerrar
- Deja el entorno en estado producción-ready

Conclusión

Los agentes de larga duración fallan no por falta de capacidad sino por falta de infraestructura. Un harness efectivo resuelve los tres problemas fundamentales:

Continuidad: git log + progress file reemplazan la memoria entre sesiones
Scope: feature list garantiza trabajo incremental y medible
Entorno: init.sh elimina el redescubrimiento en cada sesión

El insight clave de la investigación de Anthropic: las prácticas de ingeniería humana son el modelo correcto para agentes de larga duración. Los turnos de guardia en ingeniería tienen handoff notes, runbooks, y listas de incidentes. Los agentes necesitan exactamente lo mismo.

Fuente: Effective Harnesses for Long-Running Agents — Anthropic Engineering Blog, Justin Young, noviembre 2025.