Ingeniería de harnesses para agentes de IA
Diseñar el entorno de un agente también importa.
Mi hipótesis de trabajo: a medida que los modelos escriben mejor código, el harness que los rodea puede volverse igual de importante. Aquí exploro esa idea con guías prácticas.
Cómo funciona un arnés
Un mensaje, varias vueltas.
Cuando le escribes a un agente de código, tu mensaje entra en un bucle. El arnés arma el contexto, el modelo decide si responde o pide una herramienta, y el arnés la ejecuta y le devuelve el resultado. Vuelta a vuelta, hasta que el modelo responde sin pedir nada más.
Claude Code, por ejemplo, lo llama agentic loop, y llama agentic harness a la capa que da las herramientas y gestiona lo que ve el modelo. Elige un mensaje y pulsa Enviar. Los ejemplos ocurren en el arnés por capas de la serie, con sus permisos y sus hooks.
Pulsa Enviar para empezar
Verás cada paso del bucle: quién actúa, qué decide el modelo y qué entra en el contexto.
Lo que recibe el modelo
El arnés envía todo esto en cada llamada. Lo nuevo se añade al final.
Vacío hasta que envíes un mensaje.
- Instrucciones del sistema: cómo trabajar y usar las herramientas
- AGENTS.md del arnés por capas
- Herramientas: read_file, edit_file, run_command…
- Skills: add-endpoint y clean-code-review, solo nombre y descripción
- Hola, ¿cómo estás?
- ¡Hola! Bien, gracias. ¿En qué te ayudo con el proyecto?
- Instrucciones del sistema: cómo trabajar y usar las herramientas
- AGENTS.md del arnés por capas
- Herramientas: read_file, edit_file, run_command…
- Skills: add-endpoint y clean-code-review, solo nombre y descripción
- ¿Qué versión de Express usa el proyecto?
- read_file("package.json")
- "express": "5.3.0"
- El proyecto usa Express 5.3.0.
- Instrucciones del sistema: cómo trabajar y usar las herramientas
- AGENTS.md del arnés por capas
- Herramientas: read_file, edit_file, run_command…
- Skills: add-endpoint y clean-code-review, solo nombre y descripción
- Añade el endpoint GET /members/:id/loans
- read_file(".agents/skills/add-endpoint/SKILL.md")
- read_file("src/services/loan-service.ts")
- SKILL.md: repository → service → controller → test
- loan-service.ts: class LoanService { list() lend() … }
- edit_file("src/controllers/members-controller.ts")
- members-controller.ts: editado y formateado
- Listo: añadí GET /members/:id/loans.
- check-architecture-before-stop: controllers-do-not-import-repositories (código 2)
- edit_file("src/services/loan-service.ts")
- edit_file("src/controllers/members-controller.ts")
- 2 archivos editados y formateados
- Listo: el controlador llama al servicio de préstamos.
Todos los pasos en texto
«Hola, ¿cómo estás?»
Escribes y pulsas Enter
Tu mensaje no va directo al modelo. Lo recibe el arnés: el programa que rodea al modelo, le da herramientas y decide qué ve.
El arnés arma el contexto
Junta las instrucciones del sistema, el AGENTS.md del proyecto, la lista de herramientas, las skills disponibles y tu mensaje. El modelo solo sabe lo que entra aquí.
Entra en el contexto: Instrucciones del sistema: cómo trabajar y usar las herramientas · AGENTS.md del arnés por capas · Herramientas: read_file, edit_file, run_command… · Skills: add-endpoint y clean-code-review, solo nombre y descripción · Hola, ¿cómo estás?
El modelo lee y decide
Con todo el contexto, el modelo elige entre dos caminos: responder con texto o pedir una herramienta. Para un saludo no necesita ninguna, así que responde.
Entra en el contexto: ¡Hola! Bien, gracias. ¿En qué te ayudo con el proyecto?
Respuesta: el bucle termina
Como el modelo no pidió herramientas, el bucle acaba tras una sola llamada. Los hooks de cierre se ejecutan igual, aunque solo fuera un saludo; el código no cambió, así que pasan y ves la respuesta.
«¿Qué versión de Express usa el proyecto?»
Escribes y pulsas Enter
El arnés recibe la pregunta. La respuesta está en un archivo del proyecto, no en el modelo.
El arnés arma el contexto
Las mismas piezas que en cualquier mensaje: instrucciones, AGENTS.md, herramientas, skills y tu pregunta. El package.json todavía no está: nadie lo ha leído.
Entra en el contexto: Instrucciones del sistema: cómo trabajar y usar las herramientas · AGENTS.md del arnés por capas · Herramientas: read_file, edit_file, run_command… · Skills: add-endpoint y clean-code-review, solo nombre y descripción · ¿Qué versión de Express usa el proyecto?
El modelo pide una herramienta
La versión no está en el contexto, así que el modelo no responde: devuelve una petición estructurada para leer package.json. El modelo no ejecuta nada por su cuenta.
Entra en el contexto: read_file("package.json")
El arnés comprueba los permisos y ejecuta
Antes de ejecutar, el arnés mira sus reglas: leer package.json está permitido; leer .env, no. Después lee el archivo él mismo.
El resultado vuelve al contexto
El contenido del archivo se añade al contexto, justo después de la petición del modelo. Con eso empieza la siguiente vuelta.
Entra en el contexto: "express": "5.3.0"
Segunda llamada al modelo
El arnés vuelve a enviar todo el contexto, ahora con el resultado. El modelo ya tiene el dato y responde con texto, sin pedir más herramientas.
Entra en el contexto: El proyecto usa Express 5.3.0.
Respuesta: el bucle termina
Pasan los hooks de cierre y ves la respuesta. Para una sola pregunta hicieron falta dos llamadas al modelo y una herramienta.
«Añade el endpoint GET /members/:id/loans»
Escribes y pulsas Enter
Ahora es una tarea, no una pregunta. Hará falta leer código, editarlo y comprobarlo.
El arnés arma el contexto
De la skill add-endpoint solo entran su nombre y su descripción. El texto completo se carga cuando hace falta.
Entra en el contexto: Instrucciones del sistema: cómo trabajar y usar las herramientas · AGENTS.md del arnés por capas · Herramientas: read_file, edit_file, run_command… · Skills: add-endpoint y clean-code-review, solo nombre y descripción · Añade el endpoint GET /members/:id/loans
El modelo pide leer
Pide dos herramientas a la vez: leer la skill y el servicio de préstamos, para seguir los pasos del proyecto.
Entra en el contexto: read_file(".agents/skills/add-endpoint/SKILL.md") · read_file("src/services/loan-service.ts")
El arnés lee los archivos
Leer archivos del proyecto está permitido, así que el arnés ejecuta las dos lecturas.
Los archivos entran al contexto
La skill y el servicio se añaden al contexto. Cada resultado ocupa espacio: por eso el contexto crece en cada vuelta.
Entra en el contexto: SKILL.md: repository → service → controller → test · loan-service.ts: class LoanService { list() lend() … }
El modelo pide editar
Pide cambiar el controlador de socios. En este ejemplo se equivoca: el controlador importa el repositorio de préstamos y se salta la capa de servicios.
Entra en el contexto: edit_file("src/controllers/members-controller.ts")
El arnés edita y un hook formatea
Editar archivos del proyecto está permitido. Justo después, el hook de después de editar formatea el archivo con Prettier.
El resultado vuelve al contexto
El arnés añade el resultado de la edición. Nada ha comprobado todavía la regla de las capas.
Entra en el contexto: members-controller.ts: editado y formateado
El modelo cree que ha terminado
Responde con texto, sin pedir herramientas. Sin hooks, el bucle acabaría aquí, con la regla rota.
Entra en el contexto: Listo: añadí GET /members/:id/loans.
Un hook no le deja terminar
El hook de arquitectura ejecuta dependency-cruiser, encuentra el import prohibido y sale con el código 2. El arnés no te muestra la respuesta: añade el error al contexto y el bucle sigue.
Entra en el contexto: check-architecture-before-stop: controllers-do-not-import-repositories (código 2)
El modelo corrige
Con el error en el contexto, pide añadir la consulta al servicio de préstamos y que el controlador llame al servicio.
Entra en el contexto: edit_file("src/services/loan-service.ts") · edit_file("src/controllers/members-controller.ts")
El arnés edita y formatea otra vez
Las mismas reglas de permisos y el mismo hook de formato que en la vuelta anterior.
El resultado vuelve al contexto
El arnés añade el resultado de las dos ediciones. El contexto ya guarda todo lo que pasó desde tu mensaje.
Entra en el contexto: 2 archivos editados y formateados
El modelo intenta terminar otra vez
Vuelve a responder con texto, sin pedir herramientas.
Entra en el contexto: Listo: el controlador llama al servicio de préstamos.
Pasan los hooks y termina
Esta vez pasan los hooks de cierre: arquitectura, secretos, calidad y duplicados, que solo avisa. Ves la respuesta tras cinco llamadas al modelo.
Ejemplo simplificado: los mensajes, los archivos y los resultados son ilustrativos, no una grabación de una sesión real. Los nombres de las herramientas son genéricos; cada agente usa los suyos.
Fuentes, consultadas el 2026-10-22: How Claude Code works (documentación de Claude Code); How tool use works (documentación de la API de Claude).
Ruta de aprendizaje
Explora los temas, paso a paso
Abre un grupo para ver sus temas. Puedes seguir el orden sugerido o elegir lo que necesitas ahora.
Sección 01
Fundamentos
Cómo pedir bien una tarea y qué información necesita el agente, ahora y entre sesiones.
- En la rutaDiseñar tareas para un agente
Objetivo, límites y criterios de aceptación para un encargo claro.
Sección 03
Capacidades externas
Herramientas, servidores externos y los límites que contienen lo que el agente puede hacer.
- En la rutaHerramientas y permisos
Qué puede hacer el agente sin preguntar, qué requiere aprobación y qué se bloquea.
Sección 04
Control y coordinación
Comprobar el resultado, automatizar los controles y repartir el trabajo sin perder el control.
- En la rutaVerificación y evaluación
Comprobar el resultado con evidencias, no con el resumen del agente.
- En la rutaHooks
Comandos que se ejecutan solos en momentos concretos, sin depender de que el agente se acuerde.
- En la rutaSubagentes y delegación
Repartir una tarea entre agentes con encargos claros y una verificación final.