Lección 01 — Los modelos fuertes no significan ejecución fiable

Te considerás alguien con experiencia en IA: suscripción activa, clave de API, los números del leaderboard de SWE-bench memorizados. Un día por fin le entregás un proyecto real a un agente, con toda la confianza del mundo. ¿El resultado? Agrega una función pero rompe los tests, corrige un bug e introduce dos más, corre veinte minutos y declara con orgullo “terminado”. Mirás el código y no es lo que pediste.

El primer instinto suele ser: “este modelo no es suficientemente bueno, hay que actualizar”. Antes de sacar la tarjeta, considerá que quizá el problema no sea el modelo.

Miremos algunos números. A fines de 2025, los agentes de programación más fuertes en SWE-bench Verified logran entre 50% y 60%. Y eso en tareas cuidadosamente seleccionadas, con descripciones claras y tests ya existentes. Llevalo a tu entorno diario —requisitos vagos, sin tests, reglas de negocio implícitas por todas partes— y ese número solo baja.

Detrás de esos números hay una verdad contraintuitiva.

El mismo caballo, destinos distintos

Anthropic corrió un experimento controlado. Mismo prompt (“construí un creador de juegos retro 2D”), mismo modelo (Opus 4.5).

Configuración	Duración	Coste	¿Funcionaban las funciones centrales?
Ejecución desnuda, sin harness	20 min	9 USD	No — las entidades del juego no respondían al input
Tres agentes: planner + generator + evaluator	6 h	200 USD	Sí — el juego era completamente jugable

No cambiaron el modelo. Opus 4.5 seguía siendo Opus 4.5. Lo que cambió fue el equipo de monta.

El artículo de OpenAI sobre harness engineering lo dice sin rodeos: Codex en un repositorio bien harnessed pasa de “poco fiable” a “fiable”. Fijate en el lenguaje: no es “un poco mejor”, es un cambio cualitativo. Como un caballo pura sangre: podés montarlo sin equipo adecuado, pero no vas a llegar lejos, no vas a ir rápido y caerte no va a ser una sorpresa.

El harness es ese conjunto completo de equipamiento: todo lo que existe en la infraestructura de ingeniería fuera de los pesos del modelo.

Dónde se atascan realmente los agentes

flowchart TD
    T["Tarea entregada al agente"] --> C1{"¿La tarea<br/>está bien definida?"}
    C1 -->|No| F1["Fallo: especificación de tarea<br/>El agente adivina qué querías"]
    C1 -->|Sí| C2{"¿El contexto del proyecto<br/>está en el repo?"}
    C2 -->|No| F2["Fallo: provisión de contexto<br/>Viola convenciones que no puede ver"]
    C2 -->|Sí| C3{"¿El entorno<br/>arranca y es reproducible?"}
    C3 -->|No| F3["Fallo: entorno de ejecución<br/>Quema contexto peleando con dependencias"]
    C3 -->|Sí| C4{"¿Hay comandos<br/>de verificación?"}
    C4 -->|No| F4["Fallo: feedback de verificación<br/>Declara victoria sin evidencia"]
    C4 -->|Sí| C5{"¿Persiste el estado<br/>entre sesiones?"}
    C5 -->|No| F5["Fallo: gestión de estado<br/>Rehace trabajo, contradice decisiones"]
    C5 -->|Sí| OK["Trabajo terminado y verificado"]

Vale la pena recorrer cada capa con ejemplos concretos.

Nunca definiste la tarea con claridad. Decís “agregá una función de búsqueda” y la interpretación del agente puede ser completamente distinta de la tuya: ¿buscar qué?, ¿texto completo o datos estructurados?, ¿paginación?, ¿resaltado? Si no lo especificás, el agente adivina. Si acierta, es suerte; si falla, corregirlo cuesta más que haber sido específico desde el principio. Es como entrar a un restaurante y decirle al cocinero “quiero pescado”: si llega hervido, al vapor o en salsa picante queda librado al azar.

El proyecto tiene convenciones implícitas que el agente no conoce. Tu equipo estandarizó SQLAlchemy 2.0, pero el agente escribe código 1.x por defecto. Todos los endpoints deben usar OAuth 2.0, pero esa regla vive en tu cabeza y en un mensaje de Slack de hace tres meses. El agente no puede verla. No es que no quiera cumplirla: literalmente no sabe que existe.

El entorno es una trampa. Entorno de desarrollo incompleto, dependencias faltantes, versiones incorrectas de herramientas. El agente quema una ventana de contexto valiosa en fallos de pip install y discrepancias de versión de Node en lugar de resolver la tarea. Es como contratar a un carpintero experto y olvidarse de darle martillo, clavos y una mesa nivelada.

No hay forma de verificar. No hay tests, no hay lint, o los comandos de verificación nunca se le comunican al agente. Escribe código, lo mira, decide que está bien y dice “terminado”. Anthropic observó además que cuando los agentes sienten que el contexto se agota, se apuran a terminar, saltean la verificación y eligen soluciones simples en vez de óptimas. Lo llaman context anxiety: lo mismo que pasa cuando ves que se acaba el tiempo del examen y empezás a marcar respuestas al azar.

Las tareas largas pierden el hilo. Los descubrimientos de la sesión anterior se pierden y cada sesión nueva vuelve a explorar la estructura del proyecto desde cero. Los agentes sin estado persistente ven la tasa de fallos subir bruscamente en tareas de más de treinta minutos.

Terminología clave

Con estos escenarios en mente, estos conceptos dejan de ser jerga:

• Brecha de capacidad: la distancia entre el rendimiento del modelo en benchmarks y su rendimiento en tareas reales. Un 50-60% en SWE-bench Verified significa que casi la mitad de los issues reales no se resuelven.
• Harness: todo lo que está fuera del modelo — instrucciones, herramientas, entorno, gestión de estado y feedback de verificación. Si no son pesos del modelo, es harness.
• Fallo inducido por harness: el modelo tiene capacidad suficiente, pero el entorno de ejecución tiene defectos estructurales. El experimento controlado de Anthropic ya lo demostró.
• Brecha de verificación: la diferencia entre la confianza del agente en su salida y la corrección real. El agente dice “terminé” cuando no terminó. Es el modo de fallo más común.
• Bucle diagnóstico: ejecutar, observar el fallo, atribuirlo a una capa concreta del harness, corregir esa capa y volver a ejecutar. Es la metodología central del harness engineering.
• Definition of Done: conjunto de condiciones verificables por máquina — tests pasan, lint limpio, type checks pasan. Sin una definición explícita, el agente inventa la suya.

Cuando algo falla, arreglá primero el harness

Principio central: cuando algo falla, no cambies primero el modelo; revisá el harness. Si el mismo modelo funciona en tareas similares y bien estructuradas, asumí que es un problema de harness. Es como un auto que se detiene: no sospechás inmediatamente del motor; primero mirás si tiene nafta.

1. Atribuí cada fallo a una capa específica

No digas “el modelo es malo”. Preguntá: ¿la tarea era poco clara?, ¿faltaba contexto?, ¿no había métodos de verificación? Mapeá cada fallo a una de las cinco capas del diagrama de arriba. Si construís este hábito, vas a ver cada vez menos “el modelo no alcanza” en tus registros.

2. Escribí una Definition of Done explícita para cada tarea

No digas “agregá búsqueda”. Decí:

Criterios de finalización:
- Nuevo endpoint GET /api/search?q=xxx
- Soporta paginación, 20 items por defecto
- Los resultados incluyen fragmentos resaltados
- Todo el código nuevo pasa pytest
- El type checking pasa (mypy --strict)

3. Creá un archivo AGENTS.md

Ponelo en la raíz del repositorio para decirle al agente el stack técnico, las convenciones arquitectónicas y los comandos de verificación. Es el primer paso del harness engineering y uno de los de mayor retorno. Un solo AGENTS.md puede ser más efectivo que actualizar a un modelo más caro; no es una exageración.

4. Construí un bucle diagnóstico

No trates los fallos como “el modelo se volvió a equivocar”. Tratalos como señales de que tu harness tiene un defecto. En cada fallo, identificá la capa, corregila y evitá repetir ese modo de fallo. Después de unas rondas, el harness se fortalece y el rendimiento del agente se estabiliza.

flowchart LR
    E["Ejecutar tarea"] --> O["Observar el fallo"]
    O --> A["Atribuir a una<br/>de las 5 capas"]
    A --> R["Reparar esa capa"]
    R --> V["Registrar el<br/>modo de fallo"]
    V --> E

5. Cuantificá las mejoras

Mantené un registro simple: si cada tarea tuvo éxito o falló, y qué capa causó el fallo. Después de unas rondas vas a ver cuál capa es el cuello de botella; enfocá ahí tu energía.

El experimento del millón de líneas

OpenAI corrió en 2025 un experimento agresivo: usar Codex para construir un producto interno completo desde un repositorio git vacío. Cinco meses después, el repositorio tenía alrededor de un millón de líneas de código —lógica de aplicación, infraestructura, tooling, documentación y herramientas internas—, todo generado por agentes. Tres ingenieros dirigieron Codex, abriendo y fusionando unas 1.500 PRs, con un promedio de 3,5 PRs por persona por día.

La restricción clave: los humanos nunca escriben código directamente. No era un truco; estaba diseñado para obligar al equipo a descubrir qué cambia cuando el trabajo principal del ingeniero deja de ser escribir código y pasa a ser diseñar entornos, expresar intención y construir bucles de feedback.

El progreso inicial fue más lento de lo esperado. No porque Codex no pudiera, sino porque el entorno no estaba completo: al agente le faltaban herramientas, abstracciones y estructuras internas para avanzar hacia objetivos de alto nivel. El trabajo de los ingenieros se convirtió en descomponer metas grandes en bloques pequeños —diseño, código, revisión, test—, dejar que el agente los ensamblara y luego usar esos bloques para desbloquear tareas más complejas. Cuando algo fallaba, la solución casi nunca era “intentá más fuerte”; era “qué capacidad le falta al agente, y cómo la hacemos comprensible y ejecutable”.

Este experimento demuestra directamente la tesis central: el mismo modelo produce resultados fundamentalmente distintos en un entorno desnudo y en uno con harness completo.

Fuente: OpenAI — Harness engineering: leveraging Codex in an agent-first world

Un ejemplo más cotidiano

Un equipo usó Claude Sonnet para agregar un endpoint nuevo a una aplicación web Python mediana (FastAPI + PostgreSQL + Redis, unas 15.000 líneas).

Al principio dieron solo una frase: “agregá endpoints de preferencias de usuario bajo /api/v2/users”. El agente gastó 40% de su ventana de contexto explorando la estructura del repo, produjo código que parecía razonable pero no seguía los patrones de manejo de errores del proyecto, usó sintaxis vieja de SQLAlchemy y declaró finalización aunque el endpoint tenía errores en runtime. La sesión siguiente tuvo que repetir todo el descubrimiento.

Después agregaron AGENTS.md, con arquitectura del proyecto y versiones del stack, comandos de verificación explícitos (pytest tests/api/v2/ && python -m mypy src/) y registros de decisiones arquitectónicas. El mismo modelo tuvo éxito en tres ejecuciones independientes, con alrededor de 60% más eficiencia de contexto.

No cambiaron el modelo. Cambiaron el harness.

Ideas clave

• Capacidad del modelo y fiabilidad de ejecución son cosas distintas. Un pura sangre también necesita buen equipo de monta.
• Cuando algo falla, revisá primero el harness y después el modelo. Cambiar de modelo es la opción más cara y muchas veces ni siquiera es un problema del modelo.
• Cada fallo es una señal: tu harness tiene un defecto estructural. Encontralo y arreglalo.
• Cinco capas defensivas: especificación de tarea, provisión de contexto, entorno de ejecución, feedback de verificación y gestión de estado. Revisalas de forma sistemática.
• Un solo AGENTS.md puede rendir más que actualizar a un modelo más caro.

Ejercicios

1. Registro de atribución: tomá las últimas cinco tareas que le diste a un agente. Para cada una, marcá si tuvo éxito y, si falló, a cuál de las cinco capas pertenece el fallo. Contá la distribución: ahí está tu cuello de botella.
2. Definition of Done: elegí una tarea que le vayas a dar hoy y escribí sus criterios de finalización antes de mandarla. Compará el resultado con lo que obtenías antes.
3. AGENTS.md mínimo: escribí un AGENTS.md de 30 líneas con stack, comandos de arranque y comandos de verificación. Corré la misma tarea antes y después. Registrá la diferencia en el porcentaje de contexto que el agente gasta explorando.

Lecturas adicionales

• OpenAI: Harness Engineering — Leveraging Codex in an Agent-First World
• Anthropic: Effective Harnesses for Long-Running Agents
• HumanLayer: Skill Issue — Harness Engineering for Coding Agents
• SWE-bench Leaderboard
• Thoughtworks Technology Radar: Harness Engineering

---

Siguiente: Lección 02 — Qué significa realmente harness