Un harness para agentes de código evita que Claude Code, Codex u otro agente convierta una buena solicitud en un pull request roto. Define entrada, contexto, herramientas, pruebas, revisión y criterio de salida. La respuesta corta es clara: el agente solo abre PR después de que la evidencia técnica pasa.
En 2025, el Stack Overflow Developer Survey 2025, sección AI, informó que 84% de las personas encuestadas usa o planea usar IA en el proceso de desarrollo, frente a 76% el año anterior (Stack Overflow, Developer Survey 2025 AI, acceso 2026-06-30). El número explica la urgencia. La práctica todavía necesita salir del prompt suelto.
Un harness para agentes de código es un conjunto pequeño de reglas y verificaciones alrededor del agente. No reemplaza arquitectura, revisión humana ni CI. Reduce ambigüedad para que el agente trabaje como ejecutor verificable, no como compañero imaginario con texto convincente.
Este artículo parte de una observación práctica: los equipos no sufren solo porque la IA escribe código equivocado. Sufren porque el error llega tarde, mezclado en un diff grande, sin prueba clara y con demasiado contexto para revisar rápido.
Versiones de este artículo: portugués e inglés. Para contexto de autoría, consulta la página sobre. Para contacto editorial, usa la página de contato.
TL;DR práctico
- Si 84% de devs usa o planea usar IA, la ventaja no es usar agente. Es verificar la salida.
- Un buen harness empieza con spec corta, contexto mínimo, prueba reproducible y regla de PR.
- Subagentes y MCP ayudan cuando reducen ruido; si amplían superficie sin prueba, perjudican.
¿Qué es un harness para agentes de código?
En 2025, el Stack Overflow Developer Survey 2025, sección AI, registró 84% de uso o intención de uso de IA en desarrollo (Stack Overflow, Developer Survey 2025 AI, acceso 2026-06-30). Un harness es la respuesta operativa a ese volumen: transforma la ejecución del agente en un flujo con entrada, herramientas y salida auditables.
Piensa en cinco bloques. Primero viene la spec: una descripción corta del comportamiento esperado y de lo que queda fuera. Después viene el contexto: archivos, contratos, logs y decisiones previas que realmente importan. Luego viene la ejecución del agente, con permisos compatibles con el riesgo de la tarea.
El cuarto bloque es verificación. Aquí entran pruebas unitarias, pruebas de integración, lint, typecheck, migración local o cualquier comando que represente calidad en el repositorio. El quinto bloque es decisión: abrir PR, volver al loop o pedir revisión humana antes de tocar más código.
En síntesis, un harness para agentes de código es una frontera entre generación y entrega. Stack Overflow registró 84% de uso o intención de uso de IA en desarrollo en 2025 (Stack Overflow, Developer Survey 2025 AI, acceso 2026-06-30), pero adopción no equivale a calidad. La función del harness es exigir que cada cambio pase por spec corta, contexto explícito, comandos reproducibles y una decisión de PR auditable.
¿Cuándo usar subagentes en agentic coding?
En 2025, la misma encuesta indicó que 51% de desarrolladores profesionales usa herramientas de IA a diario (Stack Overflow, Developer Survey 2025 AI, acceso 2026-06-30). Los subagentes tienen sentido cuando ese uso diario empieza a contaminar la conversación principal con logs, búsquedas, archivos largos o revisiones paralelas.
La documentación de Claude Code describe los subagentes como asistentes especializados que se ejecutan en ventanas de contexto propias, con prompt, herramientas y permisos específicos (Anthropic, Create custom subagents, acceso 2026-06-30). El beneficio técnico es simple: la conversación principal recibe síntesis, no volcados.
Usa subagente para exploración de codebase, lectura de logs, revisión de diff y verificación de pruebas. No uses subagente para multiplicar intentos ciegos. Si tres agentes escriben código a la vez sin spec común, ganas concurrencia aparente y pierdes trazabilidad.
En flujos largos, el ahorro real viene de no cargar todo en la misma ventana. Cuando el agente necesita cruzar repositorios grandes, un recurso como RemoteCode para extender Claude Code y Codex en flujos agentic puede ayudar a avanzar más con menos desperdicio de contexto, siempre que el harness siga decidiendo qué pasa.
¿Cómo elegir contexto antes de que el agente escriba código?
En 2025, Stack Overflow mostró 47,1% de uso diario de IA entre todos los respondentes y 17,7% de uso semanal (Stack Overflow, Developer Survey 2025 AI, acceso 2026-06-30). Con uso frecuente, el contexto se vuelve el cuello de botella: enviar todo el repositorio parece seguro, pero suele generar ruido.
Empieza con una lista corta. Incluye issue o spec, archivos probables, contratos de API, pruebas cercanas, comandos de validación y decisiones arquitectónicas que no son obvias en el código. Excluye historial irrelevante, logs repetidos, archivos generados y documentación antigua sin relación con el cambio.
Una buena regla es pedir al agente un plan de contexto antes de implementar. Debe decir qué archivos leerá y por qué. Si la lista parece demasiado grande, redúcela. Si falta un contrato crítico, agrégalo antes del código. Context engineering es triaje, no acumulación.
¿Dónde entra MCP sin convertirse en riesgo?
En 2025, 13,7% de respondentes de Stack Overflow dijo usar IA mensual o infrecuentemente, mientras 5,3% no la usaba aún, pero planeaba hacerlo pronto (Stack Overflow, Developer Survey 2025 AI, acceso 2026-06-30). Para equipos en transición, MCP debe entrar por necesidad, no por moda.
El Model Context Protocol es un estándar abierto para conectar aplicaciones de IA con sistemas externos, como archivos, bases de datos, herramientas y flujos de trabajo (Model Context Protocol, What is MCP?, acceso 2026-06-30). En Claude Code, MCP permite conectar herramientas, bases, APIs, issues y observabilidad (Anthropic, Connect Claude Code to tools via MCP, acceso 2026-06-30).
Usa MCP cuando el agente necesita buscar una issue, consultar una base de prueba, leer un error en Sentry o abrir un pull request. No conectes herramientas solo porque existen. Cada servidor aumenta superficie de permisos, riesgo de prompt injection y costo cognitivo.
¿Cómo montar el loop de spec, TDD y CI?
En 2025, el uso o intención de uso de IA en desarrollo llegó a 84%, desde 76% el año anterior (Stack Overflow, Developer Survey 2025 AI, acceso 2026-06-30). Esa subida cambia la pregunta: no si el agente escribe código, sino qué loop impide que escriba sin prueba.
El loop mínimo tiene seis pasos:
- Escribe una spec de una página o menos, con comportamiento esperado y fuera de alcance.
- Pide al agente un plan de archivos y comandos antes de editar.
- Crea o ajusta la prueba primero cuando el cambio lo permita.
- Haz el patch más pequeño que resuelve la spec.
- Ejecuta pruebas, lint y typecheck en ambiente limpio.
- Genera una revisión automática con bloqueos y riesgos residuales.
Esta secuencia encaja con TDD porque el agente recibe una frontera concreta. Si la prueba falla antes y pasa después, la conversación cambia. El agente deja de argumentar que el cambio “parece correcto” y empieza a demostrar comportamiento. En backend, esto vale para contratos HTTP, colas, migraciones, idempotencia y observabilidad.
Claude Code también ofrece hooks para ejecutar comandos en puntos del ciclo de vida, como después de ediciones o antes de comandos sensibles (Anthropic, Automate actions with hooks, acceso 2026-06-30). Usa hooks para formato, bloqueo de archivos protegidos y validaciones determinísticas. El juicio sigue en revisión.
¿Cómo revisar un PR generado por IA?
En 2025, 16,2% de respondentes de Stack Overflow dijo que no usa IA y no planea usarla en desarrollo (Stack Overflow, Developer Survey 2025 AI, acceso 2026-06-30). Ese grupo recuerda algo importante: la confianza no es obligatoria. El PR generado por IA debe ganársela.
La revisión debe empezar por el contrato de la spec. ¿El diff resuelve exactamente lo pedido? ¿La prueba cubre el caso principal? ¿Hay cambios ocultos en archivos sin relación? ¿El agente citó comportamiento externo o salida de herramienta sin enlace? ¿Quedó implícita alguna migración, permiso o variable de entorno?
Pide una revisión automática antes del humano. Debe listar bloqueos, riesgos y comandos ejecutados. No aceptes una review que solo elogia. Un buen revisor automático busca falla de contrato, caso límite, regresión de seguridad, riesgo de performance e inconsistencia entre código y prueba.
La mejor señal de madurez no es que el agente abra PR solo. Es que sepa cuándo no debe abrirlo. Si la fuente no fue verificada, la prueba no cubre el flujo o el diff creció más allá de la spec, el resultado correcto es volver al loop.
Checklist antes de dejar que el agente abra el PR
En 2025, Stack Overflow mostró que 84% de respondentes ya usa o planea usar IA en desarrollo, pero ese dato no valida cualquier automatización (Stack Overflow, Developer Survey 2025 AI, acceso 2026-06-30). El checklist final debe ser menor que el proceso y más duro que la intuición.
| Señal | Cómo verificar | Acción si falla |
|---|---|---|
| Spec cubierta | Prueba o caso manual descrito | Volver a la spec |
| Contexto suficiente | Archivos y contratos citados | Reabrir contexto |
| Pruebas limpias | Comando registrado en el PR | Corregir antes del PR |
| Lint y tipos limpios | Salida de CI o comando local | Corregir antes del PR |
| Review sin bloqueo | Lista de riesgos revisada | Pedir revisión humana |
| Fuente citada | Enlace y fecha de acceso | Quitar o verificar claim |
Si todas las señales pasan, el agente puede abrir PR con descripción objetiva: problema, enfoque, comandos ejecutados, riesgos y próximos pasos. Si alguna señal falla, no conviertas la falla en nota al pie. Vuelve al loop, reduce el alcance o llama a una persona.
FAQ sobre harness para agentes de código
¿Qué es un harness para agentes de código?
Es una estructura operativa que rodea al agente con spec, contexto, herramientas permitidas, pruebas y regla de salida. En 2025, 84% de respondentes de Stack Overflow usaba o planeaba usar IA en desarrollo (Stack Overflow, Developer Survey 2025 AI, acceso 2026-06-30), así que la ventaja está en verificar.
¿MCP es obligatorio para agentic coding?
No. MCP ayuda cuando el agente necesita herramientas externas con contrato claro. La documentación de MCP lo define como estándar abierto para conectar IA a sistemas externos (Model Context Protocol, What is MCP?, acceso 2026-06-30). Para cambios locales simples, pruebas y CI bastan.
¿Los subagentes ahorran tokens?
Pueden ahorrar contexto cuando aíslan exploración y devuelven síntesis corta. La documentación de Claude Code afirma que los subagentes se ejecutan en ventanas propias y ayudan a preservar contexto (Anthropic, Create custom subagents, acceso 2026-06-30). Si devuelven volcados largos, el beneficio desaparece.
¿Codex y Claude Code necesitan el mismo harness?
El diseño cambia por herramienta, pero el principio es el mismo. Codex, Claude Code y agentes similares necesitan spec, alcance, herramientas, verificación y revisión. Cuando el agente ejecuta comandos y edita archivos, el harness se vuelve parte del proceso de ingeniería.
Fuentes consultadas
- Stack Overflow, Developer Survey 2025 AI, acceso 2026-06-30, https://survey.stackoverflow.co/2025/ai
- Anthropic, Create custom subagents, acceso 2026-06-30, https://code.claude.com/docs/en/sub-agents
- Anthropic, Connect Claude Code to tools via MCP, acceso 2026-06-30, https://code.claude.com/docs/en/mcp
- Anthropic, Automate actions with hooks, acceso 2026-06-30, https://code.claude.com/docs/en/hooks-guide
- Model Context Protocol, What is MCP?, acceso 2026-06-30, https://modelcontextprotocol.io/docs/getting-started/intro
- OpenAI, Introducing Codex, acceso 2026-06-30, https://openai.com/index/introducing-codex/