Harness engineering de agentes en la práctica: del issue al PR

Un agent harness es el código alrededor de un agente de IA que decide qué tarea toma, cuándo el trabajo cuenta como terminado y quién lo revisa. Harness engineering es construirlo. El modelo solo hace el trabajo. Un agente de IA que escribe código es barato. Lo caro es un agente cuyos pull requests sus séniores pueden fusionar sin rehacerlos, y el harness cierra esa distancia.

Ejecutamos un bucle así cada día en nuestros propios repositorios. La IA escribe la mayor parte de nuestro código. Un sénior revisa cada cambio y responde de lo que llega a producción. A continuación: cómo funciona el bucle, las líneas de código que lo sostienen y lo que se rompió por el camino.

¿Qué es un agent harness?

Un agent harness es todo lo que rodea al modelo y dentro de lo que trabaja el agente: las reglas y el contexto que carga, las herramientas que puede llamar, el bucle que lo ejecuta, las comprobaciones de su resultado y el momento en que se detiene y pregunta a una persona. Claude Code, por ejemplo, es un modelo envuelto en un harness que le da archivos, comandos y un bucle. Su propio harness va encima: lo que ve el agente, lo que puede tocar y lo que cuenta como terminado.

Tres términos se confunden a menudo:

• Framework. Una librería con la que se construye un agente, como un SDK de agentes. Le da piezas, no decisiones.
• Scaffold. El cableado de prompt y herramientas alrededor de una llamada al modelo o de una ejecución de benchmark.
• Harness. Todo el entorno de trabajo en producción, comprobaciones y entrega a una persona incluidas. Aquí viven las reglas de su equipo.

Dos equipos con el mismo modelo obtienen resultados distintos porque sus harnesses son distintos. El modelo lo alquila. El harness es suyo.

¿Qué significa harness engineering en la práctica?

Un agente es un modelo más su harness. El modelo lo alquila. El harness es suyo: reglas, contexto, comprobaciones, límites y la entrega a una persona.

Nuestra única regla de diseño está al principio del script del dispatcher:

# Deterministic on purpose: code decides WHAT to take and WHEN it is done, models only do the work.

De ella se derivan tres cosas:

• El código elige el trabajo. Un dispatcher en bash elige las tareas por prioridad. Ningún modelo decide qué empezar.
• Primero, una comprobación automática. Typecheck, lint, tests y nuestra propia puerta se ejecutan antes de que ningún modelo opine.
• Quien hizo el trabajo nunca lo evalúa. Una llamada nueva al modelo, con herramientas de solo lectura, revisa el resultado.

¿Qué hace un desarrollador cuando el código lo escribe el agente?

Para nosotros empezó con una tarea más pequeña que el agente llevó hasta el merge. Eso nos hizo pensar en qué hace realmente hoy un desarrollador.

La IA escribe la mayor parte de nuestro código. Nosotros nos aseguramos de que el resultado funciona de verdad. Y asumimos los problemas más grandes, con perspectiva, no línea a línea.

En la práctica son cuatro pasos:

¿Cómo lleva nuestro bucle un issue hasta un PR?

Un issue por ejecución: un git worktree, una rama, una sesión de Claude Code, un pull request.

1. READY. Una llamada al modelo de solo lectura comprueba el issue contra el código antes de empezar. ¿Se sostiene la premisa, con archivo y línea? ¿Qué tipo de tarea es? ¿Qué demuestra que está terminada: un test, o solo una persona que lo mire? Si falta una decisión, el agente pregunta en el issue y se detiene.
2. BUILD. Una sesión de Claude Code en segundo plano hace el trabajo en su propio worktree. En el caso del código, primero escribe un test que falla con el código sin cambiar y después implementa.
3. VERIFY. Dos capas. Primero gate.sh, bash sencillo con códigos de salida. Después un revisor nuevo cuyo único trabajo es intentar refutar el trabajo. Sus hallazgos vuelven a la misma sesión de BUILD.
4. CI. El CI del propio repositorio tiene que pasar en el commit enviado. Una comprobación que también falla en la rama principal se marca como preexistente y no se atribuye a la rama.
5. HANDOFF. El PR se marca como listo, se pide a una persona como revisor y un comentario lleva las pruebas.

Solo hay dos salidas: review (terminado, con pruebas) o blocked (una pregunta en GitHub). Cuando una persona responde y quita blocked, la misma sesión continúa con todo su contexto.

¿Qué líneas de código sostienen el bucle?

Tres piezas cortas hacen la mayor parte del trabajo.

Cada llamada al modelo devuelve una respuesta JSON tipada. Sin respuesta significa fallo, nunca un valor por defecto. Abreviado:

# one read-only model call with a typed answer; no object back = failure, never a default
ask() {
    ( cd "$tree" && claude -p "$prompt" --tools "Read,Grep,Glob" \
        --json-schema "$(cat "$schema")" --output-format json ) > "$out.raw"
    jq -e 'select(.subtype == "success") | .structured_output // empty' "$out.raw" > "$out" && [ -s "$out" ]
}

Una comprobación automática en rojo nunca se puede convertir en verde a base de argumentos:

verdict=$(jq -r .verdict "$R/verify-$round.json")
[ "$mrc" != 0 ] && [ "$verdict" = pass ] && verdict=fix   # a red executable check is never overruled to pass

Y un bucle que no converge se detiene. Si el revisor informa del mismo hallazgo dos veces seguidas, la tarea va a una persona con ese hallazgo adjunto. Otra ronda no lo arreglaría.

Un detalle más: el texto no fiable va acotado. Los cuerpos de los issues y los comentarios de los PR llegan al modelo marcados como datos, no como instrucciones.

¿Por qué no bastan unas reglas en un archivo de texto para un agente?

Hace poco el agente tenía sus reglas solo en archivos de reglas. A veces no las seguía. Así que las convertimos en comprobaciones que no puede esquivar: ESLint, tests de arquitectura, un typecheck antes del push, y todo ello otra vez en CI.

Cada puerta adicional estrecha el camino: tests de arquitectura, una comprobación de que el código está completo, archivos obligatorios. Cuantas más puertas, menos margen tiene el agente para desviarse. Solo queda el camino permitido.

Hay también un efecto secundario:

¿Dónde entra una persona?

En tres momentos, y en ningún otro:

El cuello de botella es la revisión, no el agente. Por eso el dispatcher no empieza ninguna tarea nueva mientras haya PR del agente esperando a las personas. Una tarea ya en curso puede continuar. El merge, el push a main, los envíos y los despliegues están bloqueados por debajo del agente, en hooks que no puede editar.

¿Qué se rompió por el camino?

Más de lo que esperábamos. Estos son los casos que vale la pena conocer:

• El dispatcher dejó de empezar tareas, en silencio. Un cambio en el límite de revisiones puso un recuento entre jq | y while read. El bucle leía entonces una entrada vacía y no empezaba ninguna tarea. Nada falló, nada avisó. Lo encontró una auditoría. El arreglo llegó con un test del dispatcher sobre un gh simulado, rojo con el código antiguo y verde con el nuevo.
• La infraestructura acababa en una persona como blocked. A una sesión que moría en sus primeros minutos le faltaba acceso, no era mal trabajo. Ahora se reintenta en el siguiente ciclo.
• Un CI que nunca terminaba contaba como verde. Ahora es una devolución a una persona. No terminado no es aprobado.
• La comprobación de preparación llegó tarde. La comprobación de la premisa contra el código la añadimos después. Hoy es la primera etapa, y por ahí empezaríamos.

El paso más difícil suele ser el último: verificar que de verdad funciona de principio a fin. Puertas y tests reales. Mantener los entornos alineados, para que las comprobaciones se ejecuten siempre, es lo que más trabajo cuesta. Un truco nos ha funcionado bien: enviamos a un agente a la funcionalidad como un tipo de cliente, una persona, para que la explore por su cuenta.

Antes de este bucle probamos otras dos formas. Una era un pipeline de workflows de GitHub Actions dirigido por etiquetas. La otra, menciones @claude de un solo uso en los issues. Borramos las dos. Los jobs de CI sin estado encajan mal cuando el trabajador necesita reanudar una sesión y preguntar a una persona en mitad de una tarea.

¿En qué no estamos de acuerdo con lo que se escribe sobre harness engineering?

La mayoría de lo que se escribe trata de las herramientas. En nuestra opinión, lo decisivo es dónde está la persona en el proceso.

¿Puede aplicarlo en su propio equipo?

Empiece por las puertas de calidad. Si su equipo no tiene ninguna, empiece por ahí. Nuestro bucle READY → BUILD → VERIFY → CI → HANDOFF es sencillo y funciona. Aun así, cada sistema necesita uno un poco distinto.

El bucle en sí está ligado a nuestra configuración. Las piezas más importantes, no. Las hemos publicado como un pequeño repositorio público: el Claude Code production starter. Tiene reglas del agente, hooks que paran comandos peligrosos, un Stop hook que bloquea el "terminado" mientras las comprobaciones están en rojo y una puerta de CI con tests red-proof. Licencia MIT. Clónelo, quédese con las herramientas y sustituya la aplicación.

¿Cuáles de estas tiene ya su equipo?

Qué va en las reglas que alimentan un harness así lo explicamos en Reglas para el código de IA en un equipo. Cuándo basta en un equipo con el modo de planificación del agente lo explicamos en Plan mode de Claude Code.

¿Quiere un harness así en su repositorio?

Construimos este tipo de bucle directamente en el repositorio de un equipo como parte de AI-native SDLC para equipos de desarrollo. ¿A su equipo le faltan más manos que reglas? Vea un desarrollador sénior para su equipo. Desde 2023 hemos entregado más de 15 proyectos en producción. Un sénior se incorpora a su repositorio y a sus pull requests desde el primer día.

Le respondemos en un plazo de dos días hábiles con algunas preguntas sobre su trabajo. Después acordamos qué hacemos primero.

Si prefiere hablar primero, reserve una llamada inicial de 15 minutos.

¿Qué hace hoy su agente cuando no está seguro: pregunta o adivina?

Preguntas frecuentes

¿Qué significa harness engineering en la práctica?

Construir el código alrededor de un agente de IA: qué tarea toma, qué herramientas y reglas recibe, qué comprueba su trabajo y cuándo entra una persona. El modelo hace el trabajo. El harness decide cuándo el trabajo cuenta como terminado.

¿Qué es un agent harness?

Todo lo que rodea al modelo y dentro de lo que trabaja un agente de IA: reglas y contexto, herramientas, el bucle que lo ejecuta, las comprobaciones de su resultado y el momento en que pregunta a una persona. El nuestro es un dispatcher y un runner en bash que toman un issue de GitHub por sesión de Claude Code, ejecutan comprobaciones y un revisor nuevo, y después entregan un PR a una persona.

¿Qué diferencia hay entre un agent harness y un framework de agentes?

Un framework, como un SDK de agentes, es una librería con la que se construye un agente. Un harness es el entorno de trabajo en el que funciona el agente: qué reglas carga, qué puede tocar, qué comprobaciones deciden cuándo está terminado y cuándo entra una persona. Un harness se puede construir con un framework o alrededor de un agente ya hecho como Claude Code.

¿El agente hace merge de sus propios pull requests?

No. Solo una persona hace merge. El merge, el push a la rama principal, los envíos y los despliegues están bloqueados por hooks por debajo del agente, que este no puede cambiar.

¿Qué debe incluir primero un agent harness?

Cuatro piezas, antes de cualquier bucle: reglas del agente en el repositorio, hooks que paran comandos peligrosos, un Stop hook que bloquea el "terminado" mientras las comprobaciones están en rojo y una puerta de CI con tests red-proof. Nuestro Claude Code production starter público tiene las cuatro. Añada un bucle cuando una sesión por tarea ya no baste.