Lección 02 — Qué significa realmente harness

La palabra “harness” se usa mucho en los círculos de agentes de programación, pero la mayoría de la gente quiere decir “un archivo de prompt” cuando dice harness. Eso no es un harness. Es como abrir un restaurante con nada más que ingredientes: sin cocina, sin cuchillos, sin recetas, sin flujo de emplatado. Eso no es un restaurante, es una heladera.

Esta lección da una definición precisa y práctica. No una abstracción académica, sino un marco que podés usar hoy: un harness consiste en cinco subsistemas, cada uno con responsabilidades claras y criterios de evaluación.

Empecemos con una analogía

Imaginate que sos un ingeniero recién contratado que llega a un proyecto sin documentación. Sin README, sin comentarios, nadie te dice cómo correr los tests, la configuración de CI está enterrada en algún lado. ¿Podés escribir buen código? Tal vez, si sos suficientemente inteligente y paciente. Pero vas a pasar mucho tiempo en “averiguar de qué trata este proyecto” en lugar de “resolver el problema”.

Un agente enfrenta exactamente la misma situación, y peor: vos al menos podés preguntarle a un compañero. El agente solo puede ver los archivos que le pongas delante y los comandos que pueda ejecutar. No puede tocarle el hombro a nadie y preguntar “che, ¿qué versión del ORM usa este proyecto?”.

OpenAI enmarca el principio central como “el repositorio ES la especificación”: todo el contexto necesario debería estar en el repositorio, entregado a través de archivos de instrucciones estructurados, comandos de verificación explícitos y una organización clara de directorios. La documentación de Anthropic sobre agentes de larga duración enfatiza la persistencia del estado, las rutas de recuperación explícitas y el seguimiento estructurado del progreso. Las dos empresas se enfocan en aspectos diferentes, pero dicen lo mismo: todo en la infraestructura de ingeniería fuera del modelo determina cuánta de la capacidad del modelo se realiza realmente.

Herramientas que ya conocés, vistas como harness

Claude Code encarna el pensamiento de harness. Lee CLAUDE.md de tu repositorio (la estantería de recetas), ejecuta comandos de shell (el estante de cuchillos), corre en tu entorno local (la cocina), mantiene el historial de sesión (la mesa de preparación) y puede ejecutar tests y ver resultados (la ventana de control de calidad). Pero si no le decís cómo correr los tests, la ventana de control de calidad está rota: nadie sabe si el plato está cocido.

Cursor sigue una lógica similar. Su archivo de reglas es la estantería de recetas, la terminal es el estante de cuchillos, lee la estructura del proyecto y la configuración de lint como cocina. Pero su gestión de estado es relativamente débil: cerrás el IDE y lo volvés a abrir, y el contexto anterior desapareció.

Codex usa git worktrees para aislar el entorno de ejecución de cada tarea, junto con una pila de observabilidad local (logs, métricas, trazas), para que cada cambio se verifique en un entorno independiente. En repositorios con AGENTS.md y comandos de verificación claros, se desempeña mucho mejor que en repositorios “desnudos”.

AutoGPT es el cuento de advertencia. La falta de gestión estructurada del estado lleva a la acumulación de contexto en tareas largas, y la falta de mecanismos precisos de retroalimentación hace que el agente entre en bucle. Mucha gente dice que AutoGPT “no funciona”; en realidad es el harness de AutoGPT el que no funciona.

Conceptos clave

• Qué es un harness: todo en la infraestructura de ingeniería fuera de los pesos del modelo. OpenAI destila el trabajo central del ingeniero en tres cosas: diseñar entornos, expresar intenciones y construir ciclos de retroalimentación. Anthropic llama a su Claude Agent SDK un “agent harness de propósito general”.
• El repositorio es la única fuente de verdad: cualquier cosa que el agente no pueda ver, a efectos prácticos, no existe.
• Dá un mapa, no un manual: AGENTS.md debería ser una página de directorio, no una enciclopedia. Alrededor de 100 líneas alcanza. Si no entra, dividilo en docs/ y dejá que el agente lea bajo demanda.
• Restringí, no microgestiones: un buen harness usa reglas ejecutables para restringir al agente en lugar de enumerar instrucciones una por una. OpenAI lo dice como “hacé cumplir invariantes, no microgestiones la implementación”. Anthropic descubrió que los agentes elogian con seguridad su propio trabajo, y la solución es separar a quien hace el trabajo de quien lo revisa.
• Eliminá componentes de a uno: para cuantificar la contribución marginal de cada componente del harness, quitalos uno por vez y observá cuál eliminación causa la mayor caída de rendimiento.

El modelo de harness de cinco subsistemas

flowchart TB
    subgraph H["Harness"]
        I["1. Instrucciones<br/>AGENTS.md, docs temáticos<br/>«qué es y qué no se toca»"]
        T["2. Herramientas<br/>shell, MCP, subagentes<br/>«con qué puede operar»"]
        E["3. Entorno<br/>lockfiles, Docker, versiones<br/>«dónde corre y se reproduce»"]
        S["4. Estado<br/>PROGRESS.md, feature list, git<br/>«qué pasó antes»"]
        F["5. Retroalimentación<br/>tests, lint, types, E2E<br/>«cómo sé que está bien»"]
    end
    M["Modelo<br/>(pesos)"] --> H
    H --> R["Trabajo terminado<br/>y verificado"]
    F -.corrección.-> M

Subsistema de instrucciones (estantería de recetas). Creá AGENTS.md (o CLAUDE.md) con resumen y propósito del proyecto en una frase, stack tecnológico y versiones (Python 3.11, FastAPI 0.100+, PostgreSQL 15), comandos de primera ejecución (make setup, make test), restricciones fijas innegociables (“todas las APIs deben usar OAuth 2.0”) y enlaces a documentación más detallada.

Subsistema de herramientas (estante de cuchillos). Asegurate de que el agente tenga acceso suficiente. No desactives el shell “por seguridad”: si el agente no puede ni ejecutar pip install, ¿cómo se supone que trabaje? Pero tampoco abras todo: seguí el principio de mínimo privilegio.

Subsistema de entorno (la cocina). Hacé que el estado del entorno se describa a sí mismo. pyproject.toml o package.json para bloquear dependencias, .nvmrc o .python-version para versiones de runtime, Docker o devcontainers para reproducibilidad.

Subsistema de estado (mesa de preparación). Las tareas largas necesitan seguimiento del progreso. Un PROGRESS.md simple que registre qué está hecho, qué está en progreso y qué está bloqueado. Se actualiza antes de que termine cada sesión y se lee cuando empieza la siguiente.

Subsistema de retroalimentación (ventana de control de calidad). Este es el subsistema de mayor retorno sobre la inversión. Listá explícitamente los comandos de verificación en AGENTS.md:

Comandos de verificación:
- Tests:        pytest tests/ -x
- Type check:   mypy src/ --strict
- Lint:         ruff check src/
- Verificación completa: make check (incluye todo lo anterior)

Que falte cualquier subsistema es como que falte un área funcional en la cocina: todavía podés cocinar, pero siempre va a ser incómodo.

Cuantificar el valor de cada componente: la ablación

Usá una ablación con el mismo modelo fijo. Mantené el modelo constante, eliminá subsistemas de a uno y medí cuál eliminación causa la mayor caída de rendimiento.

flowchart LR
    B["Baseline<br/>harness completo"] --> A1["Sin instrucciones"]
    B --> A2["Sin retroalimentación"]
    B --> A3["Sin estado"]
    B --> A4["Sin aislamiento<br/>de entorno"]
    A1 --> C["Comparar tasa de éxito<br/>en el mismo set de tareas"]
    A2 --> C
    A3 --> C
    A4 --> C
    C --> D["Ranking de<br/>contribución marginal"]

Cuidado con la interpretación. La mayor caída identifica el componente con mayor contribución marginal en esa tarea; no identifica automáticamente el cuello de botella. Una caída casi nula también necesita interpretación: el componente puede ser redundante, estar mal diseñado o simplemente no haber sido ejercitado por esa tarea. Para diagnosticar cuellos de botella usá primero registros de fallos y atribución (lección 01), y la ablación como evidencia de apoyo.

Anthropic usó este método y descubrió algo importante: a medida que los modelos se vuelven más fuertes, algunos componentes dejan de ser críticos. Pero siempre surgen nuevos. Volvemos sobre esto en la lección 12, cuando hablemos de simplificar el harness.

La historia real de un equipo

Un equipo usó GPT-4o en una aplicación frontend de TypeScript + React (~20.000 líneas). Pasaron por cuatro etapas, agregando equipamiento de cocina pieza por pieza:

Etapa	Qué agregaron	Tasa de éxito	Fallos restantes
1 — Cocina vacía	Solo una descripción básica en el README	20% (1 de 5)	Gestor de paquetes equivocado, convenciones de nombres, no podía correr tests
2 — Estantería de recetas	AGENTS.md con stack, convenciones y decisiones de arquitectura	60%	Problemas de entorno y verificación faltante
3 — Ventana de control de calidad	Comandos de verificación: yarn test && yarn lint && yarn build	80%	Pérdida de contexto entre sesiones
4 — Mesa de preparación	Plantillas de archivo de progreso por ejecución	80-100%	—

Cuatro iteraciones, el modelo no cambió en absoluto, la tasa de éxito pasó de 20% a casi 100%. No compraron ingredientes más caros: organizaron la cocina.

Ideas clave

• Harness = Instrucciones + Herramientas + Entorno + Estado + Retroalimentación. Cinco subsistemas, todos esenciales.
• Si no son pesos del modelo, es harness. Tu harness determina cuánta capacidad del modelo se realiza.
• Entre los cinco, el subsistema de retroalimentación suele tener la menor inversión y el mayor retorno. Configurá bien tus comandos de verificación primero.
• Usá ablación con el mismo modelo para cuantificar contribución marginal; usá registros de fallos y atribución, no solo ablación, para localizar el cuello de botella real.
• El harness se degrada como el código. Auditá con regularidad y pagá la deuda de harness como pagás la deuda técnica.

Ejercicios

1. Auditoría de los cinco subsistemas: tomá un proyecto donde uses un agente y calificá cada subsistema del 1 al 5. Encontrá el más bajo, dedicale 30 minutos y observá el cambio en el rendimiento.
2. Ablación con el mismo modelo: elegí un modelo y una tarea desafiante. Eliminá secuencialmente instrucciones (borrá AGENTS.md), retroalimentación (no des comandos de verificación) y estado (sin archivos de progreso) —uno por vez— y medí la caída. Usá los resultados para rankear el valor marginal.
3. Análisis de affordances: encontrá un escenario donde el agente “quiere hacer algo pero no puede” (por ejemplo, sabe que debería usar consultas parametrizadas pero no conoce los patrones ORM del proyecto). Determiná si es un Gulf of Execution (no sabe cómo) o un Gulf of Evaluation (no sabe si está bien), y diseñá la mejora de harness que cierre esa brecha.

Lecturas adicionales

• OpenAI: Harness Engineering
• Anthropic: Effective Harnesses for Long-Running Agents
• HumanLayer: Harness Engineering for Coding Agents
• SWE-agent: Agent-Computer Interfaces
• Thoughtworks: Harness Engineering on Technology Radar

---

Anterior: Lección 01 — Los modelos fuertes no significan ejecución fiable · Siguiente: Lección 03 — El repositorio como fuente única de verdad