Harness Engineering para agentes IA en producción
La diferencia entre una demo de IA y un agente que llega a producción
La mayoría de los agentes de IA de coding pueden escribir demos impresionantes. Pocos pueden enviar código a producción sin romper todo lo que los rodea. La diferencia es el harness engineering: la disciplina de diseñar los sistemas, guardrails y feedback loops que hacen a los agentes de IA confiables en producción.
En este artículo te cuento cómo lo usé para enviar más de 100 PRs al mes en Amazon.
Identifica dónde y cómo aplicar IA desde hoy con el GPT Arquitecto IA completamente gratis.
Para los suscriptores recibiendo esto por email, tenéis el link aquí
Soy Fran. Soy ingeniero de software en Amazon de día y escribo y experimento con IA de noche.
Quiero contarte el momento en que me di cuenta de que solo hacer prompts nunca funcionaría para agentes de IA en producción.
Estaba trabajando en un proyecto de automatización en Amazon. El objetivo era simple: actualizar archivos de configuración JSON grandes automáticamente basándose en requisitos. Estas configs tenían miles de líneas, y las actualizaciones seguían patrones predecibles.
Un trabajo perfecto para un agente de IA, ¿verdad? Eso es lo que todos pensaban. Los ingenieros del equipo abrían su IDE o CLI con IA, escribían sus prompts para modificar los JSONs, y veían al LLM esforzarse para modificar el nodo objetivo correctamente.
Fallaba al implementar los cambios correctamente. Cada vez.
El modelo no estaba roto. Estábamos usando Opus 4.6 con una context window de un millón de tokens.
La context window era el problema. Cuando le das a un LLM múltiples archivos JSON de 10,000 líneas, el modelo pierde el rastro de la estructura circundante. Edita lo que le pides que edite, pero silenciosamente rompe todo lo que lo rodea. Sin mensaje de error. Sin advertencia. Solo un archivo estructuralmente inválido que parece correcto a simple vista pero falla en producción.
Este no es un problema de calidad del modelo. Es un problema de entorno. Y la solución no es un mejor prompt.
Puede que pienses que la solución es que Anthropic lance una context window de 10M, pero sabemos que una context window más grande igual se degrada después de 100k o 200k tokens.
La solución real es un harness.
El harness engineering es la disciplina que convirtió mi prototipo roto en Amazon en un sistema que ahora envía más de 100 PRs al mes. Completamente autónomo.
Escribí una guía de 10 pasos para construir ese agente en mi artículo anterior
Si quieres ver el proceso completo detrás de este agente, lee la guía paso a paso para construir un agente de IA en producción:
En este artículo aprenderás
Qué es el harness engineering y cómo se diferencia del prompt engineering, context engineering y agent engineering
Por qué los agentes de IA fallan en archivos estructurados grandes como JSON, y cómo arreglarlo con scripts deterministas
Los cuatro pilares de un harness de IA en producción: gestión del estado, arquitectura de contexto, guardrails y gestión de la entropía
Cómo construí un harness en Amazon que envía más de 100 PRs al mes sin intervención humana
El cambio de mentalidad que separa a los ingenieros que hacen demos de IA de los que la despliegan en producción
¿Por qué los agentes de IA fallan en archivos JSON grandes?
La mayoría de los ingenieros hoy interactúan con herramientas de IA de coding de la misma manera: abren un IDE, escriben un prompt, revisan el output, repiten. Para archivos pequeños y tareas aisladas, esto funciona muy bien. Pero en el momento en que el problema involucra una gran cantidad de archivos, todo el enfoque se desmorona.
Los Large Language Models son motores probabilísticos. Predicen el siguiente token basándose en patrones dentro de su context window. Cuando la context window se llena con miles de líneas de datos estructurados, la atención del modelo se diluye. Identifica correctamente el nodo que quieres modificar, pero pierde el rastro de las claves adyacentes, los corchetes anidados y la integridad estructural. El resultado es un archivo que parece correcto en el punto del cambio pero está roto en otro lugar.
Tenemos que entender que la Context Window no es lo mismo que la Atención al Contexto. Como humano, puedo guardar cientos de objetos en un trastero, pero solo recordaré una fracción de lo que hay ahí.
Lo mismo pasa con los LLMs. El rendimiento se degrada a medida que la context window se llena (y también los costos).
¿Sabías que cada mensaje que envías está enviando toda la conversación anterior en una llamada a la API? Sí, también te cobran por esos mensajes pasados. Los servidores en la nube no guardan ningún estado, solo tienen una caché.
Cuando el modelo falla al hacer una actualización, el instinto es escribir un mejor prompt.
Añadir más restricciones.
Decirle al modelo que “preserva la estructura circundante.”
“No cometas errores.”
Pero eso es como pedirle a alguien que haga malabares con los ojos vendados y luego darle instrucciones más detalladas sobre la posición de las manos. El problema no son las instrucciones. El problema es la venda.
La propia context window se convierte en un obstáculo cuando está llena con miles de líneas de estructura repetitiva. Ningún prompt puede arreglar eso.
Para entender mejor por qué el contexto degrada el comportamiento del modelo, esta guía explica cómo diseñar el contexto para trabajar mejor con IA:
¿Qué es el harness engineering?
El harness engineering es la disciplina de diseñar los sistemas, restricciones arquitectónicas, entornos de ejecución y feedback loops automatizados que envuelven a los agentes de IA para hacerlos confiables en producción.
El término fue acuñado el 5 de febrero de 2026 por Mitchell Hashimoto, fundador de HashiCorp y creador de Terraform, en un post de blog que rápidamente se convirtió en un debate en toda la industria. La metáfora viene de la equitación. Piensa en el LLM como un caballo poderoso. Tiene energía bruta, velocidad y fuerza. Pero sin riendas, una silla de montar y un freno, esa energía no tiene dirección y puede ser destructiva (el caballo te da una coz, el LLM ejecuta un rm -rf, y no sé cuál es peor). El harness permite al jinete dirigir el poder del caballo de forma productiva.
Para entender dónde encaja el harness engineering, así es como se relaciona con las otras disciplinas que probablemente ya conoces:
Prompt Engineering (2022–2024) → Una sola interacción para diseñar el mejor input al modelo (interacción única de petición-respuesta).
Context Engineering (2025) → Controla lo que el modelo ve durante toda una sesión (múltiples interacciones hasta limpiar el contexto).
Harness Engineering (2026) → Diseña el entorno, herramientas, guardrails y feedback loops (múltiples sesiones).
Agent Engineering → Diseña el bucle de razonamiento interno del agente (define agentes especializados).
Platform Engineering → Infraestructura para gestionar el despliegue, escalado y operaciones en la nube (donde los agentes pueden ejecutarse).
El prompt engineering trata de lo que le dices al modelo.
El context engineering trata de lo que el modelo ve.
El harness engineering trata del mundo entero en el que opera el modelo. Incluye las herramientas que el agente puede llamar, las restricciones que no puede violar, la estructura de documentación que lee, y los feedback loops automatizados que atrapan sus errores antes de que lleguen a producción.
¿Cómo se ve el harness engineering en producción? Mi experiencia personal
Déjame mostrarte el problema específico que resolví, porque hablar de agentes de forma abstracta solo se vuelve útil cuando los ves aplicados a una restricción real.
El problema: Teníamos archivos de configuración JSON grandes que necesitaban actualizaciones automatizadas y repetitivas. Estos archivos eran demasiado grandes para la context window del LLM. Cada actualización manual era tediosa, propensa a errores y consumía mucho tiempo.
Lo que todos los demás intentaron: Los ingenieros del equipo abrían sus IDEs y empezaban a hacer prompts. El LLM modificaba correctamente el nodo objetivo, pero no identificaba qué otros archivos había que actualizar, y no mantenía la estructura JSON correcta. No había conciencia de la integridad estructural del JSON como una restricción rígida. Cada ejecución era un lanzamiento de moneda. A veces funcionaba. La mayoría de las veces fallaba. No puedes confiar en una IA así.
El enfoque del harness: En lugar de intentar mejorar el prompt, reduje el problema a una operación específica: cómo leer y escribir en nuestros archivos JSON. No intentaba construir un agente de propósito general. Construí uno con alcance definido. Escribí scripts deterministas en Python para manejar la cirugía real del JSON: leer el archivo, aplicar una modificación precisa, validar la estructura, escribirlo de vuelta. El único trabajo del agente era proporcionar la intención, el qué y el dónde. El script proporcionaba la garantía de ejecución.
La clave fue esta: el agente llama al script como una herramienta. No genera JSON directamente. Le dice al script qué cambiar, y el script lo cambia con cero ambigüedad. Esto significa que la IA es el cerebro que elige qué pasos dar, como un CEO que indica la dirección. La IA no tuvo que hacer el trabajo operativo ella misma.
Luego añadí un paso de validación estructural como guardrail. Si el JSON resultante está malformado, el agente no puede continuar. Físicamente no puede enviar una configuración rota. Esto proporciona un feedback loop, que es algo que los managers y ejecutivos también quieren cuando delegan a humanos.
El resultado: Más de 100 PRs al mes. Cero corrupción estructural. Completamente autónomo. El sistema lleva meses funcionando, y después de unas pocas semanas ajustando casos límite en los scripts deterministas, el agente clava las actualizaciones.
En algún momento, nos dimos cuenta de que la única razón por la que un PR se rechaza es que el requisito estaba mal, no porque la IA no ejecutara el requisito.
Eso es cuando sabes que estás en algo bueno.
Esto es lo que parece el harness engineering en la práctica. Dejas de pedirle al modelo que haga cosas en las que es malo. Le das las herramientas para las partes que requieren precisión, dejas que el agente maneje las partes que requieren juicio, y le instruyes que no salte a hacer el trabajo por sí mismo.
¿Cuáles son los cuatro pilares del harness engineering?
Mi proyecto de automatización JSON me enseñó el patrón para construir un buen agente de IA, pero el enfoque es genérico. Después de estudiar cómo OpenAI, Anthropic y otros equipos han construido sus propios harnesses, identifiqué cuatro pilares que todo harness en producción necesita.
1. Gestión del estado
Los agentes de IA son stateless por defecto. Cada llamada a la API empieza con una pizarra en blanco. Para una tarea que dura cinco minutos, esto está bien. Para una tarea que abarca horas o requiere seguir las actualizaciones de decenas de archivos, ser stateless es malo. El agente olvida lo que hizo 20 pasos atrás. Repite el mismo error en un bucle. Pierde el rastro de la arquitectura general. Esta “amnesia de IA” es el modo de fallo más común en tareas de agentes de larga duración, y es por eso que Openclaw se volvió muy popular.
Un harness resuelve esto serializando snapshots de contexto y restaurándolos entre sesiones. Piénsalo como puntos de guardado en un videojuego. El agente hace trabajo, el harness guarda un snapshot, y si el agente se cae o alcanza un límite de rate, el harness restaura el snapshot y retoma exactamente donde lo dejó.
Las implementaciones avanzadas usan objetos de estado estructurados que persisten entre ejecuciones. Hay dos estrategias principales:
Compactación de contexto, donde el harness resume continuamente el historial del agente a medida que se acerca al límite de tokens.
Reinicio de contexto, donde el harness limpia la ventana por completo y arranca un agente nuevo con una transferencia estructurada de artefactos.
Ambas funcionan. La elección correcta depende de la duración de tu tarea y los requisitos de coherencia.
2. Arquitectura de contexto (Exposición progresiva)
Los primeros codebases aptos para agentes que vi producían archivos AGENTS.md gigantescos. Este enfoque falla por la misma razón que un manual de empleado de 500 páginas falla el primer día de alguien. El agente se confunde, pierde reglas críticas y sigue instrucciones desactualizadas que nunca se limpiaron.
El mejor enfoque es la exposición progresiva. Dale al agente una tabla de contenidos corta que apunte a un directorio docs/ estructurado. El agente lee primero la tabla de contenidos, luego navega al documento específico que necesita para la tarea en cuestión.
Este es el mismo patrón introducido con el estándar de Agent Skills. En lugar de las primeras implementaciones de MCP que cargaban todas las definiciones antes del primer prompt del usuario, deja que el agente las encuentre cuando las necesite.
El agente obtiene un mapa, no una enciclopedia.
Una cosa más que es fácil olvidar: cualquier cosa a la que el agente no pueda acceder en contexto no existe para él. Tus hilos de Slack, Google Docs y acuerdos verbales en reuniones... Nada de eso es real para el agente a menos que se le proporcione o se le instruya para que los busque.
3. Guardrails deterministas
Aquí es donde el harness engineering diverge más marcadamente del prompt engineering. El prompt engineering pide al agente que escriba código limpio o que no cometa errores. El harness engineering lo impone mecánicamente.
Necesitarías linters personalizados, tests estructurales y trabajos de CI que validen la arquitectura antes del merge.
El agente no está “desanimado” ni “instruido en contra” de saltarse esos pasos. El agente está bloqueado.
Si un archivo supera un límite de tamaño, el linter lo rechaza.
Si una dependencia fluye en la dirección incorrecta, el test estructural falla.
Si el output JSON está malformado, el script de validación impide hacer merge del PR.
Los mensajes de error en tus lints y validaciones personalizadas deben incluir instrucciones de remediación. Cuando el agente choca con un error de linter, el propio mensaje de error le dice exactamente cómo arreglar el problema. Ese mensaje de error se inyecta directamente en el contexto del agente, creando un feedback loop cerrado que requiere cero intervención humana.
Esta fue una realización de mis primeros intentos en el agente que modifica JSONs. Estaba usando comandos JQ en lugar de scripts Python. JQ terminaba todos los posibles fallos con un código de salida 0 o 1. Esos outputs están pensados para terminales, no para que los LLMs se recuperen de ellos.
Una cosa más que vale la pena destacar: un codebase “aburrido” es mejor para los agentes. Las APIs estables, los patrones predecibles y las arquitecturas simples son mucho más fáciles de modelar para los agentes que las abstracciones inteligentes. Cada capa de complejidad que añades a tu codebase es una capa que el agente tiene que navegar.
Mantenlo simple.
4. Gestión de la entropía (Garbage collection)
Esto es algo que la mayoría de la gente se salta. Los agentes de IA replican patrones, incluyendo los malos. Con el tiempo, tu codebase acumula “AI slop”: lógica redundante, implementaciones verbosas, variables sutilmente alucinadas que el modelo sigue copiando porque existen en el contexto.
Sin control, esta entropía degrada todo el codebase. A esto se le llama context poisoning.
Algunas personas usan esto como argumento de que la IA es mala. Pero cada vez que me enfrento a un output de IA malo, en lugar de juzgar si la IA es buena o mala para esta tarea, me pregunto: ¿cómo podemos hacer que la IA funcione aquí? La respuesta suele ser añadir otro harness.
Podemos tener un agente de limpieza recurrente. Piénsalo como garbage collection para tu repositorio. Para cualquier tarea de implementación, ten un agente separado que escanee el codebase, busque desviaciones de tus principios fundamentales y arregle las cosas antes de abrir el PR. También puedes ejecutar este tipo de agente de forma programada. Porque ya has diseñado otros harnesses, como tener tests unitarios y linters, puedes permitir que la IA refactorice código con confianza.
Es el mismo concepto que un agente de “doc-gardening” que escanea la documentación obsoleta y la actualiza. La deuda técnica se llama así porque funciona como la deuda de dinero. Si la pagas a diario, te mantienes solvente. Si dejas que se acumule, acabas gastando mucho tiempo después.
El harness debe incluir la gestión de la entropía desde el primer día, no como una idea de última hora.
Para saber dónde aplicar los harnesses, cubrí un framework de 3 niveles para el coding asistido por IA en este artículo anterior:
Si quieres convertir prompts sueltos en especificaciones que una IA pueda ejecutar con menos ambigüedad, esta guía sobre prompt engineering y spec-driven development encaja justo después:
¿Cuáles son los errores más comunes al implementar harness engineering con IA?
1. Poner todas las reglas en un solo archivo AGENTS.md gigante.
El agente no lo lee entero. Usa exposición progresiva: una tabla de contenidos corta que apunte a docs específicos.
2. Usar el LLM para la cirugía de archivos estructurados.
Si el agente edita JSON directamente, el riesgo de corrupción estructural es alto. Los scripts deterministas hacen ese trabajo; el agente solo da la intención.
3. No incluir instrucciones de remediación en los mensajes de error.
Si el linter falla con “error: estructura inválida”, el agente no sabe cómo continuar. El mensaje de error debe decirle exactamente qué corregir.
4. Construir un harness de propósito general en lugar de uno con alcance definido.
Un harness que hace todo hace todo mal. Empieza con una operación específica y expándelo cuando funcione.
5. Olvidar la gestión de la entropía.
Sin un agente de limpieza recurrente, el codebase acumula AI slop — patrones erróneos que el modelo sigue replicando porque existen en contexto.
¿Cómo cambia el harness engineering el trabajo del ingeniero de software?
El mayor cambio que requiere el harness engineering no es técnico. Es mental.
Dejas de escribir prompts. Empiezas a diseñar entornos. Tu trabajo no es ni escribir código ni escribir los prompts detallados. Es hacer el codebase legible para el agente. Cada nombre de archivo, cada estructura de directorio, cada convención de nomenclatura, cada pieza de documentación existe no solo para los desarrolladores humanos sino para los agentes autónomos que leerán, modificarán y extenderán el codebase a velocidad de máquina.
Las restricciones dejan de ser limitaciones y se convierten en multiplicadores. Un linter personalizado que escribes una vez se aplica a cada línea de código que escribe el agente, de forma determinista, y para siempre. Un test estructural que construyes hoy detecta automáticamente cada futura violación. Inviertes una vez, y el retorno se compone con cada ejecución del agente. Ese es el apalancamiento que los ingenieros tenían para los humanos, y lo necesitamos para los agentes de IA.
Los ingenieros que más código están enviando ahora mismo llegaron a esto de forma independiente. Compañeros míos y yo hemos llegado a la misma conclusión internamente, y al leer blogs de otras empresas, todos coincidimos:
El equipo interno de OpenAI envió un millón de líneas de código y 1,500 PRs en cinco meses usando este enfoque.
LangChain publicó en febrero de 2026 el resultado más directo: sin cambiar el modelo, solo optimizando el harness, su agente de coding subió 13.7 puntos en Terminal Bench 2.0 — de 52.8 a 66.5.
Stripe fusiona más de 1,300 PRs por semana escritos íntegramente por sus agentes “Minions”, un sistema diseñado con exactamente el mismo principio: tareas con alcance definido, linters hardcodeados, y el agente solo interviene donde se necesita juicio.
El equipo de ingeniería de Anthropic documentó el tradeoff en números concretos: un agente solo construyó una app en 20 minutos por $9, pero el output estaba roto. El mismo proyecto con un harness multi-agente costó $200 y 6 horas, pero el producto funcionaba.
Mi equipo en Amazon envía más de 100 PRs al mes con el mismo patrón.
Los patrones son los mismos: reduce el problema, usa scripts deterministas en el límite de ejecución, impone restricciones mecánicamente, y el codebase se vuelve legible para el agente.
Para recapitular:
¿Qué es el harness engineering en IA?
El harness engineering es la disciplina de diseñar los sistemas, restricciones, entornos de ejecución y feedback loops que envuelven a los agentes de IA para hacerlos confiables en producción. A diferencia del prompt engineering, que se enfoca en una sola interacción con el modelo, el harness engineering gobierna todo el ciclo de vida del agente, desde la gestión del estado hasta la validación automatizada.
¿En qué se diferencia el harness engineering del prompt engineering?
El prompt engineering diseña el input al modelo en una sola interacción. El harness engineering diseña el entorno completo en el que opera el agente: herramientas, guardrails, estructura de documentación y feedback loops automatizados. El objetivo es un comportamiento confiable en miles de ejecuciones, no solo en una.
¿Por qué los agentes de IA fallan en archivos estructurados grandes como JSON?
Los archivos JSON grandes superan o saturan la context window del modelo, lo que hace que el agente pierda el rastro de la estructura circundante. Puede modificar correctamente el nodo objetivo pero corromper las claves adyacentes, produciendo un archivo roto. La solución es un script determinista que maneja la cirugía del archivo, con el agente proporcionando solo la intención.
¿Cómo construyes un harness simple para un agente de IA?
Empieza reduciendo el problema a una operación. Escribe scripts deterministas para el paso de ejecución. Conecta el agente para que llame a esos scripts como herramientas en lugar de generar el output directamente. Añade un paso de validación que el agente no pueda saltarse (¡incrústalo en los scripts si es necesario!). Este bucle de tres partes — intención a ejecución determinista a validación — es el harness mínimo viable.
¿Qué herramientas soportan el harness engineering?
Claude Code, Cursor y Codex son los entornos más usados para aplicar harness engineering hoy. Claude Code tiene soporte nativo para CLAUDE.md y un sistema de permisos integrado. Cursor permite configurar reglas por modelo via .cursorrules. Lo que diferencia a estas herramientas no es el modelo que usan, sino la calidad del harness que construyes sobre ellas.
¿Cuándo necesito un harness y cuándo no?
Un harness es necesario cuando el agente trabaja con archivos grandes o estructurados, cuando la tarea abarca múltiples sesiones o decenas de archivos, o cuando el costo de un error silencioso es alto. Para tareas aisladas y de corta duración — un script pequeño, una refactorización puntual — un buen prompt es suficiente. El harness es la inversión correcta cuando el agente va a ejecutar la misma clase de tarea cientos de veces.
¿Qué es un archivo AGENTS.md y por qué importa?
AGENTS.md es un archivo en tu repositorio que le dice a un agente de IA las reglas, convenciones y restricciones arquitectónicas de tu codebase. Actúa como el contexto estático del agente, inyectado al inicio, para que conozca las normas de tu equipo sin tener que repetirlas en cada prompt. Mantenlo corto (menos de 100 líneas) y úsalo como tabla de contenidos que apunte a documentación más profunda.
Conclusión: El harness engineering ES el producto
El modelo es la parte fácil. Todos tienen acceso a los mismos modelos base. GPT, Claude, o Gemini, todos son notablemente capaces. El harness es la parte difícil. El harness es lo que separa una demo que impresiona a tu manager de un sistema en producción que envía código real cada día sin romper cosas.
Esto es lo que quiero que te lleves de este artículo:
Reduce el problema antes de construir el agente. Un agente con alcance definido que hace una cosa bien supera a un agente de propósito general que hace todo mal.
Usa scripts deterministas en el límite de ejecución. Deja que el agente proporcione la intención. Deja que el script proporcione la garantía.
Impone restricciones mecánicamente, no verbalmente. Si una regla importa, conviértela en un linter, un test o un paso de validación. No la pongas en un prompt y esperes lo mejor.
Haz el codebase legible para el agente, no solo para humanos. Exposición progresiva, documentación estructurada, y el repositorio como el único sistema de registro.
Los ingenieros que descubran esto primero tendrán una enorme ventaja. No porque tengan mejores modelos, sino porque tienen mejores harnesses.
Si leíste hasta aquí, sígueme en la newsletter y luego sigue leyendo este otro artículo
Si quieres ver qué problemas pueden causar degradación de tu AI agent sin ser culpa tuya, revisa este artículo: