Agent harness en Claude Code: la capa que decide tu agente

TL;DR: Un agent harness es todo lo que rodea al modelo dentro de un agente de código: el system prompt, las herramientas, la orquestación, la memoria y las verificaciones. La fórmula que resume 2026 es Agente = Modelo + Harness. En esta guía verás qué es un agent harness, por qué Claude Code y Codex dependen de él más que del modelo, y cómo diseñar el tuyo con hooks, skills y un patrón de planificar, ejecutar y verificar.

El problema: el modelo ya no es el cuello de botella

La distancia entre los modelos punteros en los leaderboards estáticos se está cerrando. Y sin embargo, dos personas con el mismo Opus 4.8 obtienen resultados muy distintos en la misma tarea. La diferencia no está en el modelo, está en lo que lo envuelve.

El dato que lo deja claro: en el Terminal-Bench, el mismo modelo de Anthropic corriendo dentro de Claude Code puntúa muy por debajo de ese modelo corriendo en otros harnesses. LangChain documentó cómo subieron su agente del Top 30 al Top 5 de Terminal-Bench 2.0 cambiando solo el harness, sin tocar el modelo. Esa es la señal del momento: esta semana han aparecido a la vez varios "meta-harnesses" sobre Claude Code y Codex con decenas de miles de estrellas en GitHub, justo cuando todos chocan con el mismo muro.

El muro tiene nombre. Los agentes de largo recorrido fallan por una razón simple: cada nueva ventana de contexto es amnesia. El modelo se descarrila tras cincuenta pasos, se detiene antes de terminar o "completa" una tarea que no pasa los tests. El harness es la disciplina que evita justo eso.

¿Qué es un agent harness?

Un agent harness es todo lo que forma parte de un agente excepto el modelo: el system prompt, el mecanismo de recuperación de código, las herramientas, los hooks, la memoria persistente y la orquestación de subagentes. El término viene de los tests de software, donde el harness es el andamiaje que permite probar un componente de forma aislada.

Birgitta Böckeler lo formalizó en Martin Fowler (02/04/2026) con una ecuación limpia: Agente = Modelo + Harness. Philipp Schmid (05/01/2026) lo lleva más lejos con una analogía útil: el harness es el sistema operativo y el agente es la aplicación que corre encima. El modelo aporta la inteligencia; el harness es el sistema que hace esa inteligencia fiable y reutilizable.

Inner harness vs outer harness

Conviene separar dos capas, porque solo controlas una:

Inner harness (el que viene de fábrica): system prompt, herramientas nativas, retrieval de código y la orquestación interna. Lo trae Claude Code o Codex y no lo tocas.
Outer harness (el que construyes tú): tus reglas, tu CLAUDE.md, tus hooks, tus skills y tu memoria de proyecto. Aquí es donde un desarrollador gana o pierde la partida.

Construir el outer harness es una forma concreta de ingeniería de contexto. Si gestionar ese contexto entre sesiones te resulta caótico, la disciplina de las tres capas de memoria que evitan el vertedero de contexto es el primer ladrillo del harness.

El patrón clave: planificar, ejecutar, verificar

El patrón de harness más estudiado de 2026 es el diseño de tres agentes de Anthropic, presentado en abril de 2026 para tareas autónomas de varias horas. Separa el trabajo en tres roles distintos:

Planificación: un agente produce una especificación (un spec en JSON, por ejemplo) que un humano revisa antes de tocar código.
Generación: otro agente implementa contra ese plan, avanzando commit a commit.
Evaluación: un tercer agente verifica el resultado contra el plan y contra criterios de calidad externos.

¿Por qué separarlos en lugar de pedirle al mismo agente que se autoevalúe? Porque los modelos puntúan en positivo cuando corrigen su propio trabajo. Addy Osmani lo resume bien: separar generación de evaluación es "GANs para prosa". El humano revisa en las fronteras entre agentes, no vigilando cada token. Es el principio clásico de separación de responsabilidades aplicado a agentes: un rol planea, otro ejecuta, otro juzga.

Este patrón también se conoce como Plan-Execute-Verify (PEV), y su diferencia con el clásico "genera y comprueba" es arquitectónica: PEV impone barreras con puertas en cada transición, no tests pegados al final.

Hooks: la capa que convierte intención en regla

Hay una frase que captura el valor del harness: los hooks son lo que separa "le dije al agente que hiciera X" de "el sistema obliga a que se haga X". Un hook que corre tu suite de tests tras cada paso y devuelve el error al modelo crea un bucle de autocorrección que no depende de la buena voluntad del agente. Si quieres montar estos controles sin tocar tu flujo, los patrones de configuración sobre tu CLAUDE.md son el punto de partida.

Los meta-harnesses: cuando alguien envuelve el wrapper

Aquí está la novedad de la semana. Han aparecido proyectos que empaquetan todo este andamiaje para que no lo reinventes en cada repo. Dos lideran la conversación:

Meta-harness	Enfoque	Piezas clave	Plataformas
ruflo (ruvnet, antes Claude Flow)	Swarms coordinados con "hive mind" y un agente reina que reparte trabajo	Memoria auto-aprendida, federación entre máquinas, servidor MCP, metodología SPARC	Claude Code, Codex
oh-my-openagent (omo)	Agentes de disciplina, orquestación paralela y "verified completion"	Skills, hooks, routing multi-modelo, `/init-deep` para memoria jerárquica, palabra mágica `ultrawork`	OpenCode, Codex (vía LazyCodex)

ruflo trae la metodología SPARC (Specification, Pseudocode, Architecture, Refinement, Completion): el swarm sabe en qué fase está y cómo pasar el trabajo a la siguiente, justo para el problema de "le pedí una feature y se fue por las ramas". omo, por su parte, ataca codebases grandes generando un AGENTS.md jerárquico con /init-deep que deja "landmarks" cerca del código que importa, y exige que la tarea pase una QA antes de darse por hecha. La instalación es de una línea:

# Instala el harness de ruflo sobre tu proyecto (añade .claude/, .claude-flow/ y CLAUDE.md)
npx ruflo@latest init

# Empaqueta omo como harness de Codex con memoria de proyecto y verified completion
npx lazycodex-ai install

Un aviso honesto: muchos de estos harnesses son jóvenes y se mueven rápido (omo iba por la v4.5.1 el 26/05/2026, con un refactor a "Multi-Harness Agent OS" en curso). En escenarios reales conviene quedarse con los patrones reutilizables (swarms, PEV, memoria jerárquica, verified completion) antes que casarte con una dependencia que cambia cada semana.

Caso práctico: cuándo te compensa montar un harness

El harness no siempre vale la pena. La regla práctica que uso: cuanto más larga y menos determinista es la tarea, más harness necesitas.

Tarea corta y mecánica (renombrar, un fix puntual): el inner harness de Claude Code sobra. Montar swarms aquí es overhead.
Refactor de varias horas sobre un repo grande: aquí el outer harness paga solo. Un agente que planifica el spec, otro que ejecuta commit a commit y un hook que corre los tests evita que el modelo "termine" algo roto.
Equipo con varios servicios: es donde encajan la federación y la memoria compartida de un meta-harness, para que los agentes de un repo conozcan los contratos de otro.

La decisión de modelo es secundaria a esto. De hecho, con un buen harness puedes bajar a un modelo más barato para la fase de generación y reservar el caro para planificar. Si todavía calibras eso a ojo, esta guía sobre cuándo subir el effort y cuándo no en Claude Code se complementa bien con el enfoque de harness.

En Producción

Lo que cambia entre el tutorial y un harness que aguanta trabajo real:

Coste: un harness de tres agentes multiplica las llamadas. Planificar, generar y evaluar por separado puede triplicar el consumo de tokens frente a un único agente. Para proyectos pequeños y medianos, presupuesta el outer harness con cabeza: un flujo con swarms agresivos se va con facilidad de 10 a 40 euros al mes en API si lo dejas suelto.
Latencia: los swarms paralelos van más rápido en wall-clock, pero las barreras del patrón PEV (esperar a que termine la planificación antes de generar) añaden tiempo. No metas barreras donde no necesitas el resultado completo de la fase anterior.
Manejo de errores: el valor del harness está en el bucle de verificación. Un hook que corre tests y devuelve el error al modelo convierte fallos anecdóticos en regresiones detectables. Sin ese bucle, solo tienes más agentes equivocándose en paralelo.
Seguridad y trazabilidad: interponer un meta-harness afecta a la caché de prompts y a las trazas. Mide antes y después: más coordinación no equivale a mejor resultado si pierdes visibilidad de qué hizo cada agente.
Curación del contexto: inyectar demasiada memoria o demasiadas herramientas degrada las respuestas antes de que el agente empiece. Las skills, como primitiva del harness, resuelven esto con divulgación progresiva: cargan solo el front-matter al inicio y el resto bajo demanda.

Errores comunes y depuración

Error: el agente "completa" la tarea pero el código no pasa los tests. Causa: el harness deja que el mismo agente se autoevalúe y se da el aprobado. Solución: separa generación de evaluación en agentes distintos y mete un hook que corra la suite de verdad.
Error: el agente se enrosca horas sin cerrar el prompt. Causa: no hay plan explícito ni puertas entre fases, así que itera sin criterio de "hecho". Solución: aplica PEV con un spec escrito y una condición de done antes de generar.
Error: respuestas peores justo después de instalar un meta-harness. Causa: demasiadas herramientas y memoria cargadas en el contexto inicial (context rot). Solución: usa skills con carga diferida y curar qué se persiste; menos es más.
Error: regresiones raras al actualizar el harness o cambiar una tool. Causa: el modelo está post-entrenado con un harness concreto y se sobreajusta a primitivas como str_replace o apply_patch. Solución: valida cambios de harness con tareas pequeñas antes de adoptarlos en serio.

Preguntas frecuentes

¿Cuál es la diferencia entre un agent harness y un framework de agentes?

Un framework como LangGraph o CrewAI te da bloques para construir un agente desde cero. Un agent harness es la capa de andamiaje que envuelve a un agente ya existente como Claude Code o Codex: prompts, hooks, memoria y orquestación que hacen su comportamiento predecible. Puedes usar un meta-harness sin escribir un framework propio.

¿Necesito ruflo u omo para tener un harness?

No. Tu CLAUDE.md, tus reglas, tus hooks y una skill bien hecha ya son un outer harness funcional. ruflo y omo solo empaquetan patrones avanzados (swarms, federación, verified completion) para que no los montes a mano. Empieza por lo simple y escala cuando la tarea lo pida.

¿Por qué el mismo modelo rinde distinto en Claude Code y en otro harness?

Porque los modelos actuales se post-entrenan junto al harness, en un bucle de co-entrenamiento. El modelo se vuelve mejor en las acciones que su harness considera importantes (operaciones de filesystem, bash, planificación). Cambiar el harness, o incluso una tool, puede mover varios puestos en un benchmark sin tocar el modelo.

Conclusión

Hemos visto que el modelo dejó de ser el factor decisivo y que el harness (todo lo que lo envuelve) es donde se gana la fiabilidad. La fórmula Agente = Modelo + Harness explica por qué el mismo Opus puntúa distinto según dónde corra, y el patrón de planificar, ejecutar y verificar con roles separados es la pieza que evita que tu agente se descarrile en tareas largas. Los meta-harnesses como ruflo y omo empaquetan esos patrones, pero lo que de verdad importa es quedarte con la idea, no con la dependencia: define el spec, separa quién genera de quién juzga, y deja que los hooks impongan la regla.

¿Has montado tu propio outer harness sobre Claude Code o Codex, o ya estás probando uno de estos meta-harnesses? Cuéntame qué patrones te funcionan en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo desmonto el patrón de swarms con agente reina y cuándo compensa frente a un único agente bien dirigido.