Cuando un agente entrega código inconsistente, la reacción más común es cambiar el prompt o probar un modelo más caro. A veces funciona. Casi nunca resuelve el problema de fondo.
El modelo sólo es una pieza. La calidad también depende de qué puede ver, qué acciones puede ejecutar, qué límites no puede cruzar y qué señales recibe para saber si se equivocó. Ese sistema exterior es el harness.
En abril de 2026, Birgitta Böckeler —Distinguished Engineer de Thoughtworks— publicó Harness engineering for coding agent users en MartinFowler.com. Conviene dejar clara la autoría: el artículo no es de Martin Fowler; forma parte de la conversación técnica que su sitio hospeda y edita.
Su idea central cambia la pregunta:
En lugar de pedirle al agente que “lo haga mejor”, diseña un entorno donde sea más probable acertar y donde pueda detectar sus fallos antes de llegar a una persona.
No es otra palabra para AGENTS.md. Tampoco es un orquestador, un proveedor de modelos o una colección de prompts. Es la disciplina de convertir experiencia, arquitectura y expectativas en guías, sensores y bucles de autocorrección.
Primero: ¿qué parte del harness puedes construir tú?
La palabra se usa con varios alcances. Böckeler los separa como capas concéntricas.
- Modelo. Predice tokens. Sus capacidades importan, pero no conoce por defecto tus reglas, historia ni prioridades.
- Harness del producto. El fabricante del agente aporta system prompt, búsqueda de código, edición, herramientas, aislamiento y orquestación.
- Harness del usuario. Tu repositorio aporta especificaciones, arquitectura, scripts, pruebas, CI, permisos, observabilidad y criterios de escalamiento.
La tercera capa es la que un equipo controla. Dos empresas pueden usar exactamente el mismo modelo y obtener resultados radicalmente distintos porque una tiene un repositorio legible y autocorrectivo, y la otra sólo una carpeta de código y un prompt optimista.
Un harness exterior persigue dos resultados:
- aumentar la probabilidad de que la primera solución sea correcta;
- cerrar un feedback loop para que muchos errores se corrijan antes de consumir atención humana.
La productividad no viene de eliminar revisión a ciegas. Viene de automatizar la detección y reservar juicio para lo que no es computable.
Las dos direcciones: guiar y detectar
El marco usa una distinción tomada de teoría de control.
Guías: feedforward
Anticipan errores y orientan al agente antes de que actúe:
- una spec con aceptación y no-objetivos;
AGENTS.mdcon rutas, comandos y zonas de aprobación;ARCHITECTURE.mdcon dependencias permitidas;- ejemplos canónicos;
- skills y documentación cargable bajo demanda;
- contratos, schemas y tipos;
- generadores, CLIs y codemods.
Una instrucción como “mantén funciones pequeñas” es inferencial: el modelo debe interpretarla. Un generador que sólo produce una estructura válida es computacional: reduce materialmente el espacio de posibilidades.
Sensores: feedback
Observan la salida y devuelven una señal:
- compilador y type checker;
- lint y análisis de complejidad;
- unitarias, integración, contratos y E2E;
- pruebas de arquitectura;
- cobertura y mutation testing;
- SAST, secretos y dependencias;
- navegador, logs, métricas y trazas;
- revisión humana o por otro modelo.
Sólo guías produce un manual sin evidencia. Sólo sensores produce un agente que tropieza con errores evitables y aprende demasiado tarde. El harness combina prevención y corrección.
El segundo eje: computacional frente a inferencial
No toda guía es texto y no todo sensor es una prueba. El segundo eje describe cómo se ejecuta el control.
| Computacional | Inferencial | |
|---|---|---|
| Guía | types, schemas, generadores, APIs, codemods | principios, specs, AGENTS.md, skills |
| Sensor | tests, lint, Semgrep, GitLeaks, structural tests | revisión de diseño, evaluación semántica, LLM como juez |
Los controles computacionales son deterministas, rápidos y baratos. Si el type checker devuelve un error, no depende del humor del modelo. Los inferenciales cubren ambigüedad y semántica, pero cuestan más y pueden discrepar entre ejecuciones.
Una regla práctica:
Usa cómputo para todo lo que puedas expresar con precisión; usa inferencia para lo que requiera contexto y juicio.
No conviertas un LLM evaluator en gate obligatorio para algo que un script puede verificar. Tampoco intentes reducir una decisión de arquitectura a un límite arbitrario de 200 líneas.
El steering loop: cada fallo repetido debe cambiar el sistema
Aquí aparece la parte verdaderamente ingenieril. Cuando el agente falla, existen dos respuestas.
La respuesta local es corregir ese diff. La respuesta sistémica es preguntar:
- ¿faltó información antes de actuar?
- ¿faltó una herramienta?
- ¿faltó un sensor?
- ¿el error del sensor explica cómo autocorregirse?
- ¿hay una contradicción entre controles?
Si el mismo defecto ocurre tres veces y sólo lo corriges en conversación, estás pagando tres veces por la misma experiencia.
El error deja de ser sólo un costo. Se convierte en material para mejorar el entorno que producirá los siguientes cambios.
Esto conecta con la idea de humanos on the loop. En vez de actuar como gatekeeper dentro de cada iteración, la persona diseña el bucle. El post Humans and Agents in Software Engineering Loops lo explica con claridad: la corrección de una salida mejora una salida; la corrección del harness puede mejorar todas las siguientes.
Quality left: la señal debe llegar cuando todavía sirve
Un sensor ejecutado al final de CI descubre problemas cuando el agente ya cerró su razonamiento. Puede corregirlos, pero necesita reconstruir contexto y abrir otro ciclo.
Los controles rápidos deben vivir junto al agente:
- LSP, types y lint durante la edición;
- tests relacionados después de cada incremento;
- arquitectura y secretos antes del commit;
- suite completa en CI limpio;
- mutación, revisión profunda y análisis costoso después de integrar o en jobs programados;
- SLO, errores y trazas en runtime.
Un mensaje de error para agentes debería ser más útil que el clásico “rule failed”:
ARCH-012: src/ui no puede importar src/repository.
Usa el servicio público de src/application.
Referencia: ARCHITECTURE.md#dependency-direction
No añadas una excepción. Si necesitas una nueva frontera, escala la decisión.Es feedback y guía a la vez: detecta el fallo y reinyecta la corrección necesaria en el contexto.
Qué intentas regular: tres harnesses diferentes
“Calidad” es demasiado vaga. Böckeler propone separar al menos tres dimensiones porque cada una tiene distinta harnessability.
1. Harness de mantenibilidad
Regula la facilidad y el riesgo de cambiar el sistema:
- tamaño y complejidad;
- duplicación y código muerto;
- convenciones y tipos;
- límites entre módulos;
- cobertura y calidad de tests;
- dependencia y acoplamiento.
Es la dimensión más fácil de automatizar. Ya existen décadas de compiladores, linters y análisis estático.
En su experimento práctico con sensores, Böckeler usó TypeScript, ESLint, Semgrep, dependency-cruiser, cobertura, mutation testing incremental y GitLeaks. Los mismos controles corrían de nuevo en CI limpio; seguridad, datos, dependencias y modularidad se revisaban con menor frecuencia.
2. Harness de fitness arquitectónico
Regula características que deben conservarse al evolucionar:
- rendimiento;
- seguridad;
- disponibilidad;
- compatibilidad;
- observabilidad;
- dirección de dependencias;
- presupuesto de costo.
Una guía puede decir “todo endpoint debe emitir trazas estructuradas”. El sensor correspondiente verifica campos o ejecuta un flujo y comprueba que la traza exista. Una skill puede explicar el presupuesto de latencia; una prueba de performance mide si el cambio lo empeoró.
Aquí entran las architectural fitness functions: arquitectura expresada como propiedades evaluables, no sólo como un diagrama que envejece en una wiki.
3. Harness de comportamiento
Regula si el sistema hace lo que la gente necesita.
Es la dimensión difícil. Una spec guía; tests, fixtures y QA observan. Pero si el mismo agente interpreta mal el requisito, puede escribir implementación y pruebas coherentemente equivocadas. Todo queda verde.
Böckeler lo llama el elefante en la habitación: cobertura razonable, mutation testing y pruebas generadas no eliminan todavía la necesidad de aceptación independiente y evaluación humana.
Por eso conviene separar el oráculo:
- aceptación revisada antes de implementar;
- fixtures aprobados por alguien que conoce el dominio;
- contratos externos;
- casos de incidentes históricos;
- pruebas adversariales;
- QA manual en flujos críticos.
Un harness no transforma una intención ambigua en verdad. Sólo puede regular aquello que alguien logró expresar.
Sensores útiles también pueden empeorar el sistema
Más controles no equivale automáticamente a más confianza.
En los experimentos de Böckeler, limitar líneas por función hizo que el agente dividiera componentes React, pero empezó a empujar complejidad hacia cadenas de props. Un sensor mejoró su métrica local mientras degradaba otra propiedad del diseño.
También observó:
- agentes que intentaban subir el umbral de complejidad en vez de refactorizar;
- análisis de acoplamiento que marcaba como “god module” un contrato compartido intencional;
- reglas nuevas que descubrían una mezcla de problemas reales y ruido;
- riesgo de sobreingeniería por feedback excesivo.
Estas tensiones exigen política:
- El agente no puede relajar un gate para hacerse pasar.
- Todo sensor necesita propietario y propósito.
- Las excepciones legítimas deben documentarse, no repetirse como ruido.
- Los conflictos se escalan; no se resuelven optimizando una métrica a ciegas.
- Los controles que nunca aportan señal se revisan o retiran.
Siempre verde puede significar código excelente o un sensor inútil. Siempre rojo puede significar mala calidad o un detector demasiado sensible.
Harnessability: algunos repositorios cooperan y otros se resisten
Un sistema tipado ya ofrece un sensor. Módulos con fronteras claras permiten structural tests. Scripts de arranque reproducibles permiten al agente observar la aplicación. Una arquitectura caótica, una instalación tribal y una wiki separada hacen lo contrario.
La autora usa ambient affordances para nombrar propiedades del entorno que lo vuelven legible, navegable y tratable por agentes.
Un repositorio con buena harnessability tiene:
- un comando confiable para instalar, probar y ejecutar;
- errores diagnósticos;
- módulos y contratos visibles;
- documentación versionada junto al código;
- ejemplos canónicos;
- estados reproducibles;
- preview o aplicación observable;
- cambios pequeños y reversibles.
Todo esto también ayuda a una persona recién incorporada. La “arquitectura para agentes” suele ser, en realidad, buena ingeniería que ahora obtiene un consumidor adicional.
El legado presenta la paradoja: necesita más harness justo donde es más difícil construirlo. La salida no es envolver todo de una vez. Empieza por un flujo, crea una costura, añade observabilidad y ensancha la zona gobernable.
La ley de Ashby: reducir opciones puede aumentar autonomía
Un agente puede producir casi cualquier estructura, librería o patrón. Un regulador capaz de verificar “cualquier cosa” sería tan complejo como ese espacio.
La ley de variedad requerida de Ashby, aplicada por Böckeler, sugiere reducir la variedad del sistema que quieres gobernar:
- pocas topologías aprobadas;
- dependencias y capas explícitas;
- plantillas por tipo de servicio;
- stacks conocidos;
- interfaces estables;
- autonomía local dentro de límites centrales.
Una organización no necesita un harness universal. Puede tener uno para APIs CRUD, otro para procesamiento de eventos y otro para dashboards. Cada plantilla conoce sus riesgos y sus señales.
Esto se parece a una plataforma interna bien diseñada: restricciones centrales, libertad dentro de la frontera.
Qué están haciendo equipos reales
El marco no nace sólo de teoría.
OpenAI: repositorio como sistema de registro
Un equipo de OpenAI documentó un producto interno construido con código generado íntegramente por Codex. Su aprendizaje principal no fue “usa un prompt enorme”.
De hecho, el AGENTS.md monolítico falló: consumía contexto, todo parecía prioritario, envejecía rápido y era difícil de verificar. Lo sustituyeron por un archivo corto que funciona como mapa hacia documentación versionada.
También:
- hicieron UI, logs, métricas y trazas accesibles al agente;
- levantaron una aplicación aislada por worktree;
- impusieron capas y dependencias con linters y structural tests;
- diseñaron errores con instrucciones de remediación;
- convirtieron patrones indeseados en reglas mecánicas;
- ejecutaron “garbage collection” recurrente contra drift.
El detalle importante es que el caso fue greenfield, con inversión deliberada y una arquitectura diseñada para agentes. No es evidencia de que un modelo pueda entrar mañana a cualquier legado y repetir el resultado.
Stripe: feedback específico antes del push
Stripe describió sus Minions, agentes que llevan tareas hasta pull request. Böckeler destaca sus hooks que ejecutan linters relevantes y sus blueprints para insertar feedback en el workflow.
Ambos casos convergen: el avance no viene sólo del modelo. Viene de hacer el entorno observable, las reglas ejecutables y el feedback suficientemente temprano.
Cómo empezar sin construir una plataforma
No necesitas un departamento de AI Developer Experience. Puedes construir un primer harness en cuatro capas.
Capa 1: mapa y fuentes de verdad
AGENTS.md
ARCHITECTURE.md
docs/
├── product/
├── engineering/
├── plans/
└── decisions/
scripts/
├── check-fast
├── check-deep
└── check-architectureAGENTS.md apunta. Los documentos especializados explican. Los scripts ejecutan.
Nuestra skill de AGENTS.md como programa ayuda a diseñar esa entrada sin convertirla en una novela.
Capa 2: feedback rápido
Define una interfaz que cualquier agente pueda descubrir:
{
"scripts": {
"check:fast": "npm run typecheck && npm run lint && npm test",
"check:architecture": "dependency-cruiser src",
"check:deep": "npm run check:fast && npm run test:e2e && npm run test:mutation"
}
}Los comandos reales dependen del stack. Lo importante es que local, agente y CI compartan el mismo contrato.
Capa 3: riesgo y atención humana
Clasifica cambios:
| Riesgo | Ejemplos | Autonomía |
|---|---|---|
| Bajo | docs, estilos, refactor mecánico | autocorrección + revisión por muestra |
| Medio | negocio e integraciones reversibles | gates completos + revisión de lógica |
| Alto | auth, dinero, PII, migraciones, concurrencia | aceptación independiente + revisión humana obligatoria |
Un harness dirige atención; no pretende eliminarla.
Capa 4: aprendizaje
Cada incidente recurrente debe producir una nueva guía, un nuevo sensor o una herramienta mejor. Registra además qué sensores fallan, cuánto cuestan y cuántos errores autocorrige el agente.
Publicamos un Harness Engineering Starter Kit con inventario de controles, estructura de repositorio, contrato para AGENTS.md, registro YAML de sensores, ejemplos de errores y un plan de cuatro semanas.
Para gates de pruebas y CI, se complementa con nuestro gauntlet para código producido con IA.
Antipatrones
“Ponlo todo en AGENTS.md”
Un documento enorme compite con la tarea por contexto, pierde prioridad y se pudre. Usa progressive disclosure: mapa corto, fuentes profundas y carga bajo demanda.
“El agente sabe cuándo ejecutar los checks”
Puede saberlo y aun así no hacerlo. Integra los comandos en hooks, scripts de cierre y CI. La intención inferencial no reemplaza el gate computacional.
“Más sensores siempre es mejor”
Demasiadas señales producen ruido, costo y refactors contradictorios. Añade controles ligados a fallos o propiedades que realmente importan.
“Un LLM reviewer es una segunda opinión independiente”
Es otra inferencia y puede compartir sesgos con el autor. Úsalo para semántica, no como sustituto de contratos, ejecución o juicio experto.
“Si las pruebas pasan, el comportamiento es correcto”
Tests generados por el mismo agente pueden codificar la misma interpretación equivocada. Separa aceptación y oráculos en flujos críticos.
“Construyamos el harness universal”
La variedad explota. Empieza con una topología, un flujo y un perfil de riesgo. Generaliza sólo cuando aparezca repetición real.
Cómo saber si funciona
No midas líneas generadas ni número de sensores. Observa:
- porcentaje de fallos autocorregidos antes de revisión;
- defectos que escapan;
- tiempo humano por cambio;
- frecuencia de overrides;
- sensores siempre verdes o siempre rojos;
- costo y duración del loop;
- regresiones de arquitectura;
- tamaño de contexto necesario para un cambio;
- cantidad de archivos tocados para una modificación pequeña.
Un indicador temprano de deterioro es que un cambio trivial empiece a requerir cada vez más archivos o rompa cosas no relacionadas. Agentes y personas sufren el mismo acoplamiento; el agente sólo puede producir el daño más rápido.
Preguntas frecuentes
¿Harness engineering es context engineering?
Context engineering decide qué ve el modelo. Harness engineering usa contexto, herramientas y señales para gobernar un ciclo de trabajo. El contexto es un mecanismo dentro del harness.
¿Es lo mismo que guardrails?
Los guardrails suelen referirse a límites. El harness también incluye capacidades, observación, autocorrección, CI y aprendizaje.
¿Necesito usar un agente específico?
No. El marco es independiente del proveedor. Cambian las interfaces —rules, skills, hooks, MCP—, no la necesidad de guías y sensores.
¿Puede eliminar la revisión humana?
Puede reducir revisión mecánica en cambios de bajo riesgo. No resuelve por sí solo intención ambigua, decisiones de negocio, tradeoffs arquitectónicos o consecuencias de alto impacto.
¿Por dónde empiezo en un legado?
Escoge un flujo frecuente y reversible. Haz reproducible su build, define su frontera, añade aceptación y sensores rápidos. Amplía desde esa isla gobernable.
¿Quién mantiene el harness?
Los equipos que mantienen el sistema, con propietarios claros para controles especializados. También puede existir una plataforma compartida, pero cada regla necesita contexto, responsable y ciclo de revisión.
La tesis: el repositorio se convierte en entorno de control
El aporte de Böckeler es elevar la discusión por encima de prompts, skills o MCPs aislados.
Un agente fiable no es un modelo brillante al que le pedimos cuidado. Es un sistema donde:
- la intención puede encontrarse;
- las opciones peligrosas están limitadas;
- las propiedades importantes son observables;
- el error llega a tiempo;
- la autocorrección es barata;
- el juicio humano aparece donde aporta más;
- cada fallo repetido mejora el siguiente ciclo.
En la entrada sobre los pioneros y el código con IA concluimos que confianza no significa leer volumen, sino poder explicar la evidencia. Harness engineering es la práctica que convierte esa frase en infraestructura.
El modelo genera. El harness convierte velocidad en confianza acumulativa.
Fuentes y lecturas
- Birgitta Böckeler: Harness Engineering for Coding Agent Users
- Birgitta Böckeler: Maintainability Sensors for Coding Agents
- Birgitta Böckeler: Context Engineering for Coding Agents
- Humans and Agents in Software Engineering Loops
- OpenAI: Harness Engineering — Leveraging Codex in an Agent-First World
- Stripe: Minions — One-Shot, End-to-End Coding Agents
- Thoughtworks: Architectural Fitness Function