Qué es harness engineering: cómo convertir un agente de IA en una herramienta útil

Harness engineering en palabras sencillas

Harness engineering es la disciplina que se ocupa de construir alrededor de un modelo de lenguaje un entorno en el que realice trabajo real de forma fiable. La palabra «harness» significa arnés, la pieza con la que se dirige a un animal fuerte. El modelo es potente, pero por sí solo no sabe a dónde ir, qué herramientas usar ni cuándo parar. El harness canaliza esa fuerza.

La formulación más corta es esta:

Agente = Modelo + Harness

El modelo son los pesos y la capacidad de razonar y de escribir texto o código. El harness es todo lo demás: las instrucciones del sistema y archivos como CLAUDE.md o AGENTS.md, el conjunto de herramientas (shell, edición de archivos, servidores MCP), el entorno aislado donde el agente ejecuta comandos, los archivos de estado que sobreviven entre sesiones, y las pruebas, linters y hooks que avisan al agente de sus errores. Si se quita el harness, solo queda un chat que puede responder con texto.

Por qué el agente es «a veces senior, a veces junior»

Es una situación conocida: en un repositorio el agente trabaja como un desarrollador experimentado; en otro se pierde, olvida las decisiones de ayer y declara «listo» una funcionalidad que no funciona. La primera reacción es cambiar a un modelo más nuevo. Normalmente no ayuda, porque el modelo es el mismo en ambos casos. La diferencia está en el entorno.

De ahí parte el cambio de mentalidad principal del harness engineering: el agente no está roto, lo que está roto es lo que lo rodea. El agente no puede ejecutar las pruebas si no tiene acceso a ellas. No recordará lo que ya intentó si eso no está escrito en ningún sitio. No sabrá que una funcionalidad está rota si ninguna comprobación se lo dice. Estos no son «rasgos de carácter» del modelo, sino defectos de diseño, y se pueden corregir de forma sistemática.

Síntomas típicos de un harness deficiente

• Cada sesión nueva empieza reparando el entorno: dependencias incorrectas, la base de datos no arranca, faltan variables.
• El agente repite soluciones que ya se descartaron, porque no recuerda la sesión anterior.
• La regla está escrita explícitamente en las instrucciones, pero el agente la ignora.
• «Las pruebas están en verde», pero la funcionalidad está rota porque las pruebas comprobaban otra cosa.
• El agente se pone con tres tareas a la vez y no termina ninguna.

De qué se compone un harness: cinco subsistemas

Un error frecuente es considerar el harness como un único archivo de prompt. En realidad son cinco mecanismos, y cada uno falla a su manera.

Instrucciones

Las instrucciones responden a la pregunta de si el agente encontrará la regla que necesita. Un buen archivo de entrada es un mapa, no un manual: un índice corto con los comandos de verificación y las restricciones estrictas, y los detalles en documentos aparte que el agente abre cuando los necesita. Las buenas instrucciones enuncian invariantes («todas las consultas SQL están parametrizadas») en lugar de dictar la implementación línea por línea.

Herramientas

El agente solo puede verificar aquello a lo que tiene acceso. Si no puede ejecutar el linter, ninguna regla del tipo «ejecuta el linter antes de cada commit» funcionará. Las herramientas se conectan mediante las capacidades integradas del agente (leer y editar archivos, ejecutar comandos) y mediante MCP, un protocolo que da acceso a bases de datos, navegadores y gestores de tareas.

Entorno

El entorno es el lugar donde el agente ejecuta los comandos. Debe arrancar con un solo comando, ser el mismo de una sesión a otra y limitar el daño de un error: un entorno aislado sin acceso a producción, una rama o copia de trabajo propia y la posibilidad de devolverlo todo a su estado inicial en un minuto.

Estado

Un modelo no tiene memoria entre sesiones: todo lo que no está escrito en el repositorio desaparece junto con la ventana de contexto. Por eso el objetivo, lo hecho, las decisiones tomadas, los callejones sin salida y el siguiente paso deben vivir en archivos. Una prueba sencilla: abra una sesión nueva, diga al agente «continúa» y compruebe si empieza a trabajar o si pregunta qué debe hacer.

Retroalimentación

Los bucles de retroalimentación son el subsistema más importante. Sin ellos, el agente es su único juez y da por buena la tarea con toda honestidad. Las pruebas, la comprobación de tipos, el linter, un hook que se ejecuta tras cada cambio o un escenario E2E en el navegador: todo eso devuelve al agente una señal roja mientras el error todavía es barato de corregir.

El harness es un circuito, no una lista

Los cinco subsistemas funcionan como un circuito cerrado. El modelo recibe instrucciones, actúa mediante herramientas en el entorno, introduce cambios en el repositorio, y la verificación comprueba el resultado. Un resultado rojo vuelve al modelo para corregirlo; uno verde se registra en el estado. A su vez, el estado actualiza las instrucciones para la siguiente sesión.

instrucciones → modelo → herramientas → entorno → cambios
                ↑                              ↓
                └──── rojo ── verificación ────┘
                                     ↓ verde
                                 estado → (siguiente sesión)

Si se quita cualquier flecha, el circuito se rompe en ese punto. Sin verificación, el agente no se entera de sus errores. Sin estado, la siguiente sesión empieza con arqueología en lugar de trabajo. Por eso invertir en un subsistema no compensa un hueco en otro: un AGENTS.md de cinco páginas no sustituye a las pruebas que faltan.

En qué se diferencia el harness engineering del prompt engineering y del context engineering

Estos conceptos están anidados, no compiten entre sí.

El prompt engineering forma parte del subsistema de instrucciones. El context engineering abarca instrucciones y estado: lo que el agente ve en cada momento. El harness engineering añade lo que no cabe en la ventana de contexto: permisos de acceso, el entorno aislado, las pruebas, los hooks y el proceso de trabajo. Un prompt bien escrito no sirve de nada si el agente no puede ejecutar físicamente las pruebas.

Por qué hace falta un harness: la matemática de las tareas largas

Parece intuitivo que un modelo que acierta el 95 % de los pasos sea casi perfecto. Pero una tarea de agente consta de muchos pasos, y los errores se acumulan. Si los pasos son independientes, la probabilidad de superarlos todos sin error es el producto de sus probabilidades:

0.95 ^ 10 ≈ 0.60
0.95 ^ 20 ≈ 0.36
0.95 ^ 50 ≈ 0.08

En el décimo paso solo llega sin ningún error alrededor del 60 % de las ejecuciones; en el quincuagésimo, menos de una de cada diez. Mejorar el modelo hasta el 97 % es caro y no depende de usted. Pero atrapar el error justo en el paso donde se produjo y devolvérselo al agente es tarea del harness. Un bucle de retroalimentación convierte una cadena en la que «un error arrastra al siguiente» en una cadena de pasos cortos y corregibles.

Ejemplo: el mismo agente en dos repositorios

Tarea: añadir a un backend de pagos en FastAPI un descuento mediante código promocional.

Sin harness

El agente lee un par de archivos, escribe una función que calcula el descuento y una prueba unitaria que comprueba esa función de forma aislada. La prueba está en verde y el agente escribe «listo». No sabía que el total final se calcula en otro módulo, y no podía levantar la base de datos ni recorrer el proceso completo de compra. Un día después se descubre que el descuento no se aplica en el carrito.

Con harness

En la raíz hay un AGENTS.md de unas decenas de líneas: cómo preparar el entorno, qué comandos de verificación son obligatorios, dónde está descrita la arquitectura de pagos. El entorno se levanta con docker compose up -d. El repositorio tiene un archivo de plan con un criterio de aceptación: «el escenario E2E de compra con código promocional pasa». Tras cada cambio, un hook ejecuta el linter y la comprobación de tipos, y antes de terminar el agente debe ejecutar la prueba E2E.

# AGENTS.md (fragmento)
## Verificación — obligatoria antes de escribir «listo»
make lint        # ruff + mypy
make test        # pytest, unitarias e integración
make e2e         # escenario de compra

## MUST
- El dinero se calcula en céntimos (int), nunca en float
- Todas las consultas SQL están parametrizadas
- No tocar migraciones ya aplicadas en producción

El modelo es el mismo. Pero ahora el agente encuentra el módulo del total mediante el mapa del proyecto, la prueba E2E falla en el primer intento, el agente ve que el descuento no llega al carrito, lo corrige y solo informa tras una ejecución en verde. La diferencia en el resultado se debe por completo al harness.

Por dónde empezar

1. Describa cómo verifica el agente su propio trabajo: uno a tres comandos que debe ejecutar obligatoriamente. La retroalimentación da el mayor efecto, así que empiece por ahí.
2. Haga que el entorno sea reproducible: arranca con un solo comando y hay una forma rápida de volver atrás.
3. Cree un archivo de estado: el objetivo, lo hecho, las decisiones y los callejones sin salida, el siguiente paso.
4. Reduzca las instrucciones a un mapa: comandos de verificación, restricciones estrictas, enlaces a los documentos detallados.
5. Lleve un registro de los fallos del agente: por cada fallo, anote qué subsistema lo permitió. El registro mostrará qué arreglar después.

Una práctica útil es valorar cada uno de los cinco subsistemas de 1 a 5, dedicar media hora al más débil y ejecutar el mismo conjunto de tareas típicas antes y después. Así las mejoras del harness se miden en lugar de juzgarse «a ojo».

Resumen

El harness engineering se ocupa no del modelo, sino de todo lo que lo rodea: instrucciones, herramientas, entorno, estado y bucles de retroalimentación. La fiabilidad del agente la determina el eslabón más débil de este circuito; por eso cambiar de modelo rara vez cura la inestabilidad, mientras que añadir una prueba o un archivo de plan suele ayudar. Los cinco subsistemas y el ensamblaje del harness completo se trabajan en la práctica en el curso de harness engineering.