Harness engineering: qué es y cómo se diseña

TL;DR

• Un harness es todo el software que rodea al modelo: el bucle de control, las tools, la memoria, el sandbox, la gestión de contexto, los permisos y la observabilidad. La fórmula que se ha impuesto es agente = modelo + harness.
• El término lo popularizó Mitchell Hashimoto el 5 de febrero de 2026, en un artículo donde describe seis etapas de adopción de IA. La quinta es "Engineer the Harness": cada vez que el agente comete un error, se arregla el entorno para que ese error no vuelva a ser posible.
• El modelo aporta la capacidad. El harness decide si esa capacidad se convierte en trabajo terminado o en un resultado que parece correcto y no lo es.
• Anthropic midió la diferencia en una misma tarea: una ejecución sin harness costó 9 USD y 20 minutos y entregó un juego que no funcionaba; la misma tarea con harness completo costó 200 USD y 6 horas y entregó un juego jugable.
• Harness engineering es el trabajo iterativo de diseñar, medir y mejorar ese sistema. No es montarlo una vez: es ejecutar tareas, revisar trazas, encontrar el fallo repetido, ajustar y volver a medir.

Qué es un harness

Un modelo de lenguaje recibe texto y devuelve texto. Eso es todo lo que hace. No abre archivos, no ejecuta comandos, no recuerda la llamada anterior y no sabe si su último cambio rompió un test.

Sin embargo, cuando abres Claude Code, Codex o Cursor y pides un cambio, ves otra cosa: el agente busca archivos, los lee, escribe código, ejecuta la suite de tests y corrige lo que falla. Todo ese trabajo lo hace un segundo componente.

Ese componente es el harness: el sistema de software que rodea al modelo y convierte lo que escribe en trabajo terminado. Arma lo que el modelo va a leer, interpreta lo que responde, ejecuta las acciones que pide, guarda el estado entre llamadas y decide cuándo la tarea está hecha.

Dicho corto: todo lo que no es el modelo, es el harness.

La división de responsabilidades es siempre la misma:

El modelo nunca hace nada: pide. El harness busca, abre, edita, ejecuta y le devuelve lo que ocurrió para que el modelo decida lo siguiente.

Cuando esas dos piezas funcionan juntas dentro de un ciclo, persiguiendo un objetivo, eso es un agente. Por eso LangChain lo resume así:

agente = modelo + harness

El agente no es una tercera pieza. Es el nombre del sistema completo funcionando.

De dónde viene el término

La idea no es nueva. En software se lleva décadas llamando test harness al código que rodea a una pieza que quieres probar: la ejecuta, le pasa entradas, observa lo que devuelve y comprueba si está bien. En inglés, harness es el arnés, y to harness es dirigir una fuerza que ya existe hacia donde te sirve. Las dos acepciones describen bien lo que hace el sistema.

Lo nuevo es el nombre aplicado a agentes, y su fecha es concreta.

El 5 de febrero de 2026, Mitchell Hashimoto —cofundador de HashiCorp y autor de Terraform y Ghostty— publicó My AI Adoption Journey, donde describe seis etapas por las que pasó trabajando con agentes:

1. Drop the Chatbot
2. Reproduce Your Own Work
3. End-of-Day Agents
4. Outsource the Slam Dunks
5. Engineer the Harness
6. Always Have an Agent Running

Su definición de la quinta etapa es la que dio nombre al campo:

"The idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again."

Hashimoto pone su propio AGENTS.md de Ghostty como ejemplo: "cada línea de ese archivo viene de un mal comportamiento del agente, y los resolvió casi todos". Los arreglos son de dos tipos: documentación que corrige el prompting implícito, y herramientas programadas —scripts de capturas, ejecuciones filtradas de tests— que eliminan el error de raíz.

En las semanas siguientes, los tres laboratorios publicaron trabajo en la misma dirección:

• OpenAI construyó un producto interno completo con un harness propio: alrededor de un millón de líneas de código y 1.500 pull requests, sin que ningún humano escribiera código directamente. Llegaron al punto de reescribir los mensajes de error de sus linters pensando en que quien los iba a leer era un agente.
• LangChain subió su agente de coding del puesto 30 al top 5 de Terminal Bench 2.0 sin cambiar de modelo: solo cambiando el harness.
• Anthropic documentó que el mismo modelo, en configuraciones distintas, entrega una aplicación que se ve bien pero no funciona, o una que sí.

Ninguno de los tres lo consiguió cambiando el modelo. Los tres invirtieron en el sistema que lo rodea.

Las nueve piezas de un harness

Conviene separarlas en dos grupos, porque resuelven problemas distintos. Seis piezas son lo que el harness le da al modelo, para que pueda trabajar. Tres son lo que el harness te da a ti, para que puedas confiar en el resultado.

Lo que el harness le da al modelo

1. Tools, para que pueda actuar

Una tool es una función que el harness ofrece al modelo: tiene nombre, descripción, parámetros y un resultado. El harness pasa la lista de tools disponibles y el formato exacto en el que hay que pedirlas.

buscar_codigo(texto)
leer_archivo(ruta)
editar_archivo(ruta, texto_viejo, texto_nuevo)
ejecutar_tests()

El modelo no las ejecuta. Solo escribe cuál quiere usar y con qué parámetros. Eso sigue siendo texto, pero con una forma que el harness reconoce, ejecuta y responde.

El diseño de la tool cambia el comportamiento del agente. No es lo mismo que editar_archivo falle devolviendo error, que falle devolviendo "no encontré ese texto en Post.tsx, pero hay una coincidencia parecida en la línea 42 con distinta indentación". Con lo primero el modelo adivina; con lo segundo ya sabe dónde corregir.

2. Un bucle, para encadenar pasos

Una tarea real necesita varios pasos, y ninguno se puede planificar de antemano porque cada uno depende del resultado del anterior. No sabes qué archivo abrir hasta que la búsqueda devuelve nombres, ni qué código escribir hasta leer el archivo, ni si funcionó hasta ejecutar los tests.

Por eso el harness no llama al modelo una vez. Lo llama muchas, y en cada llamada le cuenta cómo salió la anterior:

mientras la tarea no esté terminada:
    respuesta = llamar_modelo(el objetivo + todo lo que pasó hasta ahora)
    resultado = ejecutar(la tool que pidió)

Este patrón se conoce como ReAct: razonar, actuar, observar y volver a razonar. Cada vuelta arranca sabiendo más que la anterior, y por eso el agente llega más lejos que en un solo intento.

La versión extrema de esta pieza es repetir el mismo prompt hasta que la tarea está verificablemente hecha, que es lo que hace la técnica Ralph Wiggum.

3. Memoria, para que recuerde lo que hizo

Cada llamada al modelo es independiente. No queda nada guardado entre una y la siguiente. Lo que en un chat parece memoria es el harness reenviando el historial completo en cada turno.

En un agente, lo que se reenvía no es una conversación sino el registro del trabajo:

Objetivo: agregar "me gusta" a los posts.
Archivos revisados: Post.tsx, useUserData.ts.
Cambio aplicado: botón agregado en Post.tsx.
Pendiente: persistir la preferencia y verificar la UI.
Último error: falta agregar likePost al mock de useUserData.

Ese estado vive en el harness, no en el modelo. En tareas largas hace falta además continuidad entre sesiones: un archivo de progreso y commits claros, para que la sesión siguiente lea qué se hizo y siga desde ahí.

4. Contexto, para elegir qué ve en cada llamada

Cada llamada tiene que entrar en la ventana de contexto. Las ventanas actuales son enormes —del orden del millón de tokens—, pero un repositorio real puede superarlas, y aunque entrara habría un problema peor: más contexto no es mejor contexto. Si mandas el proyecto completo para añadir un botón, lo relevante queda enterrado entre miles de líneas que no tienen que ver con la tarea.

El harness elige con dos movimientos. Primero, dar un mapa del proyecto en vez del proyecto: unas pocas líneas que dicen dónde vive cada cosa. Segundo, traer el resto solo cuando hace falta, mediante búsqueda. Eso es retrieval dentro de un agente, y la forma de trabajar —empezar con poco y traer lo demás sobre la marcha— se llama progressive disclosure.

Elegir mal sale caro en los dos sentidos: si manda de más, quema ventana y añade ruido; si resume de más, el modelo pierde decisiones y repite trabajo. Hay un coste adicional que se olvida: como el proveedor cachea el prefijo ya procesado, cada vez que el harness reescribe algo que ya estaba, el caché se pierde de ahí en adelante. Ese cálculo es el mismo que hay detrás del coste en contexto de cada skill instalada.

Cuando la conversación deja de entrar hay dos salidas: compaction —resumir lo viejo ahí mismo— o cortar y arrancar sesión nueva con una nota de en qué punto quedó.

A todo esto (qué mandar, cuándo traerlo, qué resumir, qué descartar) se le llama context engineering. Es la pieza de la que más se habla, y a veces se trata como si fuera el problema entero. Es una pieza del harness, igual que el prompt engineering.

5. Un entorno donde trabajar

Todo lo que el agente hace ocurre sobre archivos reales, en una máquina real. La pregunta es cuál. Si es la tuya, cada error del agente es un error en tu sistema.

La alternativa es darle una copia aislada. A ese lugar se le llama entorno; cuando está aislado, sandbox. Protege de tres cosas concretas:

1. Un comando destructivo que se escapa del proyecto.
2. Una conexión de red que nadie pidió: con la red apagada, el agente no puede exfiltrar código ni descargar nada.
3. Instrucciones escondidas en el material que el agente lee —un archivo, una dependencia, una página web—. Si el modelo se las cree, el sandbox limita hasta dónde llegan.

El sandbox es una capa más, no una garantía. Si habilitas la red para instalar dependencias, uno de esos candados se abre.

Armar el entorno también es trabajo del harness: qué archivos hay dentro, qué dependencias están instaladas, si hay base de datos de prueba, si hay navegador.

6. Un objetivo verificable

"Añade un botón de me gusta" parece un pedido concreto hasta que intentas implementarlo. ¿Se puede pulsar una sola vez? ¿Hay contador? ¿El estado sobrevive a un refresco? Si el harness manda el pedido tal cual, el modelo rellena esos huecos por su cuenta.

Los huecos se cierran escribiendo criterios de aceptación, y hay dos formas de escribirlos: tú, en el pedido o en un archivo del repositorio que el agente lee al arrancar —AGENTS.md, CLAUDE.md—, o el propio harness, con una llamada previa que convierte tu pedido de dos líneas en una especificación completa. Anthropic usa la segunda: un agente planificador que convierte prompts de 1 a 4 frases en una especificación con 10-16 funcionalidades.

Objetivo:
Agregar un botón de "me gusta" en cada post.

Restricciones:
Mantener el diseño actual de la lista.
Usar el sistema existente de preferencias del usuario.

Criterios de aceptación:
- El botón aparece en cada post.
- Cambia de estado al pulsarlo.
- El estado persiste al recargar.
- Los tests existentes siguen pasando.

Los criterios importan porque se convierten en el checklist de verificación. En algún momento el modelo dirá "listo, el botón ya funciona", y esa frase describe lo que el modelo cree que pasó, no lo que pasó. La verificación busca evidencia fuera del modelo: una suite de tests, una captura, una respuesta de la API, una consulta a la base de datos.

Anthropic separa los dos roles en agentes distintos: un generator implementa y un evaluator recibe los criterios, inspecciona el resultado con Playwright y busca problemas. Puede ser el mismo modelo en ambos papeles; lo que cambia es el contexto y el objetivo. Su motivo para separarlos está medido: cuando un agente evalúa su propio trabajo, "responde alabándolo con confianza, incluso cuando para un observador humano la calidad es obviamente mediocre".

Lo que el harness te da a ti

7. Permisos y límites

Un agente que puede buscar, editar, ejecutar comandos y sostener una tarea durante horas también puede borrar lo que no debía o ejecutar algo contra la base de datos equivocada.

El sandbox limita hasta dónde llega el daño. Los permisos son otra cosa: definen qué puede pedir el modelo y qué te tiene que consultar antes. En la práctica, tres decisiones:

• Qué tools existen. Si no hay tool para borrar archivos, el modelo no puede borrar uno por mucho que lo pida.
• Cuáles se ejecutan solas. Buscar código o leer un archivo no necesitan aprobación.
• Cuáles preguntan primero. Editar, instalar una dependencia, tocar una base de datos.

La idea que más importa: los límites serios viven en el sistema de permisos, no en las instrucciones. "No borres nada importante" depende de que el modelo interprete bien en cada momento. Si la tool no existe, no hay nada que interpretar.

Después hacen falta techos: cuántos reintentos, cuánto tiempo, cuánto coste. Un test que falla por un nombre mal escrito es exactamente el caso en el que quieres que reintente. Cinco intentos fallidos seguidos sobre el mismo test ya no son corrección: el harness corta, te muestra qué intentó en cada vuelta y te devuelve la decisión. A eso se le llama human in the loop.

En Claude Code esto son los modos de permiso y los hooks; están todos en el cheatsheet de Claude Code.

8. Observabilidad

Cuando una tarea sale mal, la respuesta final del agente dice muy poco. Para entender el problema hay que reconstruir la ejecución: qué contexto recibió el modelo, qué tool eligió, con qué parámetros, qué resultado obtuvo y en qué paso cambió de dirección.

Esas trazas mueven el diagnóstico del sitio equivocado al correcto. Sin observabilidad todo parece "falló el modelo". Con observabilidad se ve que el modelo nunca recibió un archivo clave, que la descripción de una tool era ambigua o que el error más útil quedó fuera del contexto.

9. Evals

Después de cambiar una pieza del harness hace falta saber si el sistema quedó mejor, o si arreglaste una cosa y rompiste otra. Las evals son eso: un conjunto estable de tareas, ejecutado antes y después, medido con criterios definidos.

El ejemplo típico: cambias cómo se arma el contexto y ahora, además del archivo que el modelo pidió, mandas los de alrededor. En tareas complejas que tocan varios archivos mejora mucho. En tareas simples empeora, porque el modelo recibe archivos que no necesitaba y a veces edita el equivocado. Eso no se ve probando una tarea suelta.

Cuánto cambia esto en la práctica

Anthropic publicó los números de un experimento que compara la misma tarea con y sin harness. Sirven para dimensionar el efecto y también el coste:

Dos lecturas, y las dos importan.

La primera: el harness es lo que separa "se ve bien" de "funciona". La segunda: un harness completo cuesta más de veinte veces lo que cuesta una ejecución suelta. No toda tarea lo justifica. Para un cambio de dos archivos, el agente solo es la opción correcta.

Hay un tercer dato en el mismo trabajo que conviene retener: con la mejora del modelo, parte del andamiaje anterior pasó a ser "overhead". El harness depende del modelo que tiene dentro. Una regla necesaria hoy puede estorbar mañana.

Dónde encajan skills, MCP y subagentes

Las piezas que más se nombran hoy no son mecanismos nuevos. Son extensiones de las nueve anteriores:

• Skills. Empaquetan instrucciones, criterios y recursos para un tipo de tarea. El harness las carga cuando hacen falta en vez de tenerlas siempre en contexto: progressive disclosure aplicado a instrucciones en vez de a código. Son la pieza 4.
• MCP. Estandariza cómo un agente descubre y usa herramientas o fuentes externas —GitHub, una base de datos, documentación interna, un sistema de tickets— a través de una interfaz común. Es la pieza 1, con un protocolo encima.
• Subagentes. Repartir una tarea grande entre ejecuciones con contextos y objetivos distintos: uno investiga, otro implementa, otro verifica. La ventaja no aparece por sumar modelos: aparece cuando la división reduce contexto, separa responsabilidades o permite revisar el trabajo de forma independiente. Son varios bucles coordinados, la pieza 2. Y una vez dividido así, puedes usar un modelo barato para lo simple y uno caro para lo difícil: eso es model routing.
• Memoria de largo plazo. El estado mantiene el hilo de una tarea; la memoria de largo plazo reutiliza información entre tareas —decisiones de arquitectura, convenciones del equipo, errores recurrentes—. Es la pieza 3, sobreviviendo a la tarea.

Qué agentes leen cada uno de estos formatos está en la lista de agentes compatibles.

Cómo empezar a hacer harness engineering

No hace falta construir un harness desde cero: Claude Code, Codex y el resto ya traen los nueve componentes. El trabajo es afinarlos sobre tu repositorio, en este orden:

1. Escribe el AGENTS.md a partir de errores reales. Una línea por cada cosa que el agente hizo mal. No escribas reglas preventivas para problemas que no has visto: ocupan contexto y no arreglan nada.
2. Convierte en tool lo que se repite. Si el agente ejecuta mal la suite de tests tres veces, el arreglo no es una frase en el prompt; es un script que la ejecuta bien.
3. Escribe criterios de aceptación antes de arrancar. Cuatro líneas verificables. Son el único antídoto contra el "listo" prematuro.
4. Decide qué se ejecuta sin preguntar y qué no. Lectura y búsqueda, automáticas. Escritura, red y base de datos, con confirmación.
5. Guarda las trazas de las ejecuciones que fallen. Sin ellas no sabrás qué pieza arreglar.
6. Junta cinco o diez tareas representativas y ejecútalas antes y después de cada cambio. Es la versión mínima de una eval, y ya detecta regresiones.

Si quieres probar las piezas sin montar nada, se puede armar un agente funcional con herramientas gratuitas, y comparar dos harnesses sobre el mismo modelo es justamente lo que hace OpenCode frente a Claude Code.

Preguntas frecuentes

¿Harness engineering sustituye al prompt engineering? No. Lo contiene. El system prompt es una pieza del harness, igual que el contexto, las tools y los permisos. Lo que cambia es que el prompt deja de ser la única palanca disponible.

¿Es lo mismo que context engineering? No. El context engineering es la pieza 4 de nueve: decide qué entra en cada llamada. El harness engineering incluye además las tools, el bucle, el estado, el entorno, la verificación, los permisos, la observabilidad y las evals.

¿El harness nativo de un modelo es siempre el mejor? No necesariamente. Los modelos se post-entrenan junto a un harness, así que se acostumbran a sus formas concretas y cambiar la lógica de una tool puede bajar el rendimiento aunque la tool nueva sea igual de razonable. Pero LangChain midió Opus 4.6 dentro de Claude Code contra el mismo modelo en otros harnesses, y en Claude Code puntuó bastante más bajo en Terminal Bench 2.0.

¿Necesito un harness completo para cualquier tarea? No. Los números de Anthropic dan más de veinte veces de diferencia de coste entre una ejecución suelta y un harness completo. El harness completo se justifica en tareas largas, con muchos archivos y criterios de calidad; para un cambio acotado es gasto puro.

¿Cuál es la primera pieza que conviene mejorar? La verificación. Es la que evita el fallo más caro —dar por terminado algo que no funciona— y la que hace útiles a todas las demás: sin criterios verificables no hay forma de medir si un cambio en el harness mejoró algo.

En resumen

Harness engineering es el trabajo de diseñar, medir y mejorar el sistema que permite a un modelo completar tareas reales. Las nueve piezas existen porque sin cada una fallaba algo concreto: el modelo no podía actuar, no sabía dónde mirar, olvidaba lo hecho, rompía lo que no debía, decía "listo" sin comprobar, o fallaba sin dejar rastro.

Y es engineering, no montaje. El ciclo es siempre el mismo:

ejecutar tareas
→ revisar trazas y resultados
→ encontrar un fallo repetido
→ ajustar el harness
→ volver a correr las evals

El modelo aporta la capacidad. El harness crea las condiciones para usarla bien.

Fuentes

• Mitchell Hashimoto, My AI Adoption Journey (5 de febrero de 2026) — origen del término.
• OpenAI, Harness Engineering.
• Anthropic, Harness design for long-running application development — los números de coste y el patrón generator/evaluator.
• Anthropic, Effective context engineering for AI agents.
• Anthropic, Effective harnesses for long-running agents.
• LangChain, The anatomy of an agent harness.
• Walking Labs, Learn Harness Engineering — curso abierto en español, con plantillas de AGENTS.md y feature_list.json.