Ingeniería de Harness para Agentes: Lo que Aprendí en 8 Meses de Producción

11 min read
Artificial Intelligence Software Engineering Programming Software Development Productivity
Ingeniería de Harness para Agentes: Lo que Aprendí en 8 Meses de Producción

Mismo modelo. 36 puntos más en benchmarks. El problema nunca fue el modelo.

Anthropic le dio a Opus 4.5 un prompt de alto nivel para construir una app web de producción. Falló. No porque el modelo fuera malo. Porque intentó hacer todo de una vez (admítelo, tú haces lo mismo), dejó funcionalidades a medias entre ventanas de contexto, y cantó victoria demasiado pronto. Arreglaron la estructura, añadieron seguimiento de progreso y flujos incrementales: el mismo modelo empezó a entregar. Llamaron al artículo "Effective Harnesses for Long-Running Agents."

TL;DR: "Harness > modelo" es correcto pero incompleto. El mecanismo que lo hace funcionar es la revelación progresiva: mostrar al modelo solo lo que necesita, cuando lo necesita. El mismo modelo subió 36 puntos en CORE-Bench solo cambiando a un mejor scaffold. Mi framework después de 8 meses y 5 apps en producción: contratos sobre intuiciones, restricciones sobre herramientas, simplificar cada trimestre. Templates copy-paste incluidos.

Luego la palabra apareció por todas partes. OpenAI publicó "Harness Engineering." LangChain subió su agente de código de 52.8% a 66.5% cambiando solo el harness. Mitchell Hashimoto y Martin Fowler escribieron sobre ello. SWE-bench Pro lo confirmó a escala: mismo modelo, diferente estructura, resultados diferentes.

Miré mi CLAUDE.md, mis contratos de prompts, mis wrappers de CLI, y me di cuenta de que esto es exactamente lo que había estado haciendo durante ocho meses en cinco apps de producción. Solo que nunca tuve la palabra para nombrarlo. Harness. Esa es la palabra.

Así que sí, el harness importa más que el modelo. Esa parte está clara.

Pero saber que "el harness importa" es como saber "come sano y haz ejercicio." Cierto, inútil si no lo haces realmente, y a punto de generar toda una industria de frameworks sobrecomplicados que no entienden el punto.

He pasado ocho meses cometiendo todos los errores del libro. Esto es lo que sobrevivió.

Los tres errores que todos van a cometer

Lo sé porque los cometí todos.

Error 1: Apilar herramientas en lugar de escribir contratos

Cuando empecé a construir OpenClaw, mi agente AI multi-modelo, conecté 12 herramientas MCP. Búsqueda, memoria, verificación de créditos, monitoreo RSS, alertas Discord, estado cron, consultas de usuarios, verificación de backups. Se sentía completo. Se sentía profesional.

El agente pasaba más tiempo decidiendo qué herramienta llamar que resolviendo el problema real.

En una consulta simple de "¿algo necesita mi atención esta mañana?", disparaba 4-5 llamadas de herramientas en secuencia, a veces golpeando el mismo endpoint dos veces con parámetros ligeramente diferentes porque las descripciones eran lo suficientemente vagas como para solaparse. Una mañana llamó check_users, luego check_credits, luego check_users otra vez con un filtro diferente, luego me dio una respuesta que se contradecía entre párrafos.

Eliminé 8 herramientas. Reemplacé 12 con 4 que tenían descripciones precisas escritas como contratos. No "consultar datos de crédito" sino "encontrar usuarios cuyo balance actual de créditos se desvía del esperado en más del 10%, marcar la anomalía con cantidad de desviación, y ordenar por severidad." Mismo código subyacente. Mismo modelo. Lo único que cambió fue la descripción.

40% menos llamadas de herramientas. Los outputs dejaron de contradecirse. La descripción de la herramienta fue el problema todo el tiempo.

Construí el framework completo de contratos de prompts alrededor de este principio y se convirtió en el cambio más impactante de todo mi flujo de trabajo. Ya no compartes código con el agente. Compartes intención, restricciones, y comportamiento esperado. La descripción ES el contrato.

Error 2: Elegir complejidad cuando la simplicidad funciona

47,000 tokens. Eso es lo que Phil Schmid midió como el costo de integrar 6 servidores MCP de la manera estándar. Solo definiciones de esquema. Antes de que tu agente siquiera empiece a pensar en tu problema real, está masticando cuarenta y siete mil tokens de descripciones de herramientas JSON.

Manus resolvió esto exponiendo herramientas MCP a través de un wrapper CLI. Mismas capacidades. Unos 400 tokens.

No conocía esos números cuando construí mi primer servidor MCP a finales de 2025. Todo el mundo los estaba construyendo. El protocolo era nuevo, brillante, se sentía como la abstracción correcta. Así que construí uno también. Flujo OAuth personalizado, manejo de refresh de tokens, agregación de datos multi-fuente, todo.

Dieciséis commits. Cuatro horas debuggeando un token de auth que expiró a mitad de sesión. Estaba en un cuarto de hotel en Cancún con una piscina literalmente a diez metros, viendo logs scrollear en lugar de nadar. Eventualmente lo envié y funciona bien ahora. Pero luego también construí CLIs que hacían lo mismo para otros servicios. El CLI necesitaba un script bash y un output JSON. Funcionó al primer intento.

Genial.

Vercel hizo el mismo experimento a escala. Empezaron con librerías de herramientas comprehensivas, búsqueda, código, archivo, herramientas API. Cada capacidad que querrías. Los agentes se confundían, hacían llamadas redundantes, tomaban pasos innecesarios. Se redujeron a lo esencial, le dieron al agente acceso directo a bash. La tasa de éxito fue al 100%, la velocidad aumentó 3.5x.

Escribí sobre por qué los CLIs vencen a MCP para la mayoría de setups de agentes y la reacción fue salvaje. Resulta que muchos builders sospechaban lo mismo pero se sentían raros diciéndolo mientras todo el ecosistema empujaba MCP como el futuro.

MCP tiene su lugar. Pero el instinto de ir por la solución compleja primero es exactamente cómo los harnesses se hinchan antes de volverse útiles.

Error 3: Nunca quitar nada

Este es traicionero porque se siente irresponsable. Construiste algo que funciona. Está en producción. Quitarlo se siente como quitar una barrera de seguridad en una autopista.

Pero los modelos mejoran. Y tu harness no lo sabe.

El mes pasado quité todo un subsistema de memoria de OpenClaw. Recuperación de contexto externo, búsquedas de embeddings, inyección de historial de conversaciones. Había tomado dos semanas construirlo y cuatro meses mantenerlo. Lo borré un jueves. Para el viernes los números contaron la historia:

La latencia de respuesta bajó 2.3 segundos por consulta. El agente dejó de alucinar contexto "recordado" que era en realidad data obsoleta de tres meses atrás. La satisfacción del usuario en interacciones de soporte subió porque el agente estaba respondiendo a lo que la gente realmente decía en lugar de lo que el sistema de memoria pensaba que era relevante.

El modelo (Kimi K2.5) se había vuelto lo suficientemente bueno manteniendo contexto dentro de sesiones que la capa de memoria externa estaba activamente empeorando las cosas. Estaba pagando por infraestructura que degradaba mi producto.

Manus, probablemente el agente autónomo más probado en batalla en producción ahora mismo, aprendió esto por las malas cinco veces. Reescribieron todo su harness cinco veces en seis meses. No porque los modelos cambiaran. Porque cada reescritura eliminaba complejidad.

Su versión inicial usaba un archivo todo.md que el agente reescribía en cada paso para rastrear progreso. Aproximadamente 30% de todos los tokens iban a actualizar ese archivo. Lo reemplazaron con un sub-agente planificador que devuelve un objeto estructurado y lo inyecta solo cuando es necesario.

Redujeron sus herramientas de docenas de esquemas MCP dinámicos a menos de 20 funciones atómicas: bash, filesystem, ejecución de código. Las herramientas MCP ya ni siquiera están en la ventana de contexto. Se exponen vía CLI que el agente llama a través de bash.

Peak Ji, su Chief Scientist, lo puso sin rodeos: "A medida que los modelos se vuelven más fuertes, no deberíamos estar construyendo más andamiaje, deberíamos quitarnos del camino del modelo."

Anthropic dice lo mismo: "A medida que las capacidades del modelo aumentan, las herramientas que tus modelos una vez necesitaron ahora podrían estar limitándolos."

Si tu harness no se ha encogido en tres meses, probablemente ya es demasiado grande.

El patrón que hace que todo esto funcione

Los tres errores comparten la misma causa raíz: darle al modelo demasiado, demasiado pronto, por demasiado tiempo. Doce herramientas cuando necesitaba cuatro. Overhead de MCP cuando un script bash habría funcionado. Un sistema de memoria inyectando contexto obsoleto que el modelo había superado.

La solución tiene un nombre. Revelación progresiva. Mostrar al modelo solo lo que necesita, cuando lo necesita. Ocultar todo lo demás.

Cursor hace esto agresivamente. Su sistema de descubrimiento de contexto dinámico filtra aproximadamente 47% de los tokens disponibles del modelo en cualquier paso dado. No por accidente, por arquitectura. El modelo ve solo lo que es relevante para esta tarea específica, este momento específico.

Claude Code lo hace con skills. Creas un directorio skills/, Claude ve solo nombres de skills y descripciones cortas al inicio de sesión. Carga el contenido completo solo cuando decide que lo necesita. Lazy loading para LLMs.

Manus lo hace con su espacio de acción en capas. Nivel 1: 20 herramientas atómicas, siempre visibles. Nivel 2: utilidades sandbox llamadas a través de bash, nunca contaminando contexto. Nivel 3: el agente escribe sus propios scripts para cadenas complejas en lugar de hacer tres roundtrips LLM separados.

El impacto en benchmarks es real. Mismo modelo, Claude Opus 4.5, puntuó 42% en CORE-Bench con un scaffold genérico. Con Claude Code como harness, 78%. Eso no es solo revelación progresiva, Claude Code trae mejor gestión de herramientas, configuración de entorno, y compactación. Pero los investigadores que ejecutaron la prueba fueron directos: el scaffold casi duplicó la puntuación. El modelo no cambió.

Los tres pilares de abajo son cómo aplico revelación progresiva en la práctica. Herramientas, configuración, mantenimiento.

El framework: contratos, restricciones, limpieza

No un diagrama de arquitectura de 47 capas. No un repo de GitHub con 41 definiciones de skills y 11 sub-agentes. Tres cosas que realmente sobrevivieron el contacto con producción.

Pilar 1: Contratos sobre intuiciones

Viste lo que pasó con las descripciones de herramientas de OpenClaw. La razón por la que funciona es mecánica: el modelo hace coincidencia de patrones a nivel de token en tu descripción para decidir si una herramienta es relevante para la consulta actual. Descripciones vagas coinciden con todo. Descripciones precisas coinciden solo con lo que quieres.

El template que uso para todas mis definiciones de herramientas ahora, y sugiero que hagas lo mismo para tus tres herramientas más usadas esta noche:

name: [tool_name]
description: [QUÉ específicamente devuelve, no sustantivos vagos 
sino la forma real del output útil]. 
Llama esto cuando [condiciones específicas de activación]. 
NO llames cuando [caso común de mal uso]. 
Output esperado: [formato y campos clave].

La línea "NO llames cuando" es la que cambia todo. Sin ella, el modelo trata cada herramienta como un tal vez. Con ella, el modelo tiene un contrato.

Pilar 2: Restricciones sobre herramientas

Cada vez que pienses "necesito una nueva herramienta para esto," para. Pregunta primero: ¿puede una sola línea en CLAUDE.md resolver esto en su lugar?

En lugar de un servidor MCP linter, una restricción: "Ejecuta tests antes de cada commit." En lugar de un agente verificador de estilo, una restricción: "Sigue las convenciones en CONVENTIONS.md." En lugar de una herramienta de planificación, una restricción: "Siempre escribe plan.md antes de tocar código."

Una restricción en CLAUDE.md cuesta cero tokens en runtime y añade cero superficie de falla. Una herramienta cuesta tokens cada vez que se llama, añade un punto de decisión que el modelo puede equivocar, y necesita mantenimiento. Las matemáticas son obvias una vez que lo ves.

Un CLAUDE.md inicial que realmente uso como base en proyectos. No un monolito, una capa de navegación que apunta a archivos especializados:

## CLAUDE.md

## Rol
Ingeniero senior. Planificas antes de codificar. Testeas antes de pushear.

## Flujo de trabajo
1. Lee este archivo + cualquier progress.md al inicio de sesión
2. Planifica primero. Escribe plan.md antes de implementación.
3. Una funcionalidad a la vez. Commit después de cada una.
4. Ejecuta tests existentes ANTES Y después de cambios
5. Actualiza progress.md antes de que termine la sesión

## Restricciones
- Nunca sobrescribas archivos sin mostrar un diff primero
- Si una tarea necesita más de 3 archivos cambiados, divídela
- Cuando tengas dudas, pregunta. No adivines lógica de negocio.
- Mantén commits pequeños y descriptivos

## Específicos del proyecto
[Tu stack, convenciones, archivos clave aquí]
Ver CONVENTIONS.md para reglas de estilo de código.

Veinte líneas que le dicen al agente cómo trabajar, no qué saber. El propio harness de Anthropic para agentes de larga duración usa un archivo de progreso, una lista de funcionalidades, y commits git estructurados encima de un core similar. El equipo Codex de OpenAI aprendió por las malas que un AGENTS.md gigante falla. Su consejo: "dale a Codex un mapa, no un manual de instrucciones de 1,000 páginas."

La clave es revelación progresiva aplicada a config: un CLAUDE.md corto que apunta a archivos detallados que el agente lee cuando los necesita. No un monolito de 500 líneas que hojea e ignora. No un stub de 10 líneas que no dice nada. Una capa de navegación.

Pilar 3: Limpieza trimestral

Cada tres meses, me siento con mi harness y hago cinco preguntas:

  1. ¿Qué herramientas no ha llamado el agente en 30 días? Borrarlas.
  2. ¿Qué reglas de CLAUDE.md existen porque el modelo viejo era tonto? Quitarlas.
  3. ¿Qué barreras de seguridad ahora las maneja nativamente el modelo? Eliminarlas.
  4. ¿La inyección de contexto sigue siendo necesaria o ha mejorado suficiente la recuperación del modelo? Probar sin ella.
  5. ¿Pueden dos herramientas fusionarse en una con mejor descripción? Hacerlo.

El trimestre pasado en OpenClaw: borré un fallback de reintentar-con-modelo-diferente que no se había activado en 6 semanas (Kimi K2.5 se había vuelto lo suficientemente estable). Quité tres reglas de CLAUDE.md sobre formateo JSON que el modelo ahora maneja nativamente. Fusioné dos herramientas de monitoreo en una con un contrato más específico.

Resultado neto: 30% menos partes móviles. Cero funcionalidad perdida. Respuestas más rápidas. Menos que mantener.

Manus ejecuta este proceso continuamente. La prueba de Peak Ji: ejecuta tu suite de eval de agentes contra un modelo más fuerte. Si el rendimiento no mejora, tu harness lo está limitando. Esa pregunta sola te dice todo sobre si estás construyendo andamiaje o construyendo una jaula.

Qué significa esto para ti esta noche

Quince minutos. Eso es todo lo que necesitas para realmente empezar.

Reescribe las descripciones de tus tres herramientas más usadas. Encuentra las herramientas que tu agente llama más. Abre sus descripciones. Si dicen qué hace la herramienta en lugar de cuándo llamarla y qué esperar, reescríbelas con el template de contrato de arriba. Cinco minutos por herramienta. El impacto es inmediato, el agente deja de adivinar y empieza a seguir instrucciones.

Luego estructura tu CLAUDE.md como una capa de navegación. Si no tienes uno aún, pega el template inicial de arriba y llena los detalles de tu stack. Si ya tienes uno, verifica: ¿es un monolito o un mapa? Mueve reglas detalladas a archivos separados (CONVENTIONS.md, ARCHITECTURE.md) y mantén tu CLAUDE.md alrededor de 20-40 líneas. El agente lee CLAUDE.md cada sesión. Debería encontrar direcciones, no una enciclopedia.

Y borra una cosa. Una herramienta. Una regla de CLAUDE.md. Un hook de middleware. Elige algo que no hayas tocado en un mes. Quítalo. Ejecuta tu flujo de trabajo normal. Si nada se rompe, no tenía razón de estar ahí. Y si algo se rompe, felicidades, acabas de aprender qué realmente importa en tu harness. Eso vale más que cualquier diagrama de arquitectura que alguien posteó en X 💀

Harness engineering está de moda. Dale seis meses. Habrá cursos. Certificaciones. Repos de GitHub con 41 definiciones de skills, 11 sub-agentes, y un README más largo que la mayoría de codebases. Tres mil estrellas, cero deployments de producción.

Mientras tanto, los builders que realmente envían agentes seguirán haciendo lo que estaban haciendo antes de que existiera la palabra. Escribir instrucciones claras. Elegir herramientas simples. Borrar lo que dejó de funcionar.

El harness no es un trabajo nuevo. Es el mismo trabajo con un mejor nombre.

Fuentes:

Si estos patrones te ahorran tiempo de debugging o costos de tokens, escribo sobre estas cosas regularmente. Contratos de prompts, arquitectura de agentes, las decisiones aburridas de infraestructura que hacen que los agentes AI funcionen en producción en lugar de solo en demos. Sígueme si quieres las notas de campo, no el hype.

AI hizo esa imagen de portada. Asigno mi presupuesto de píxeles exclusivamente a ventanas de terminal.