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.

Todos los pasos en texto

«Hola, ¿cómo estás?»

  1. 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.

  2. 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?

  3. 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?

  4. 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?»

  1. Escribes y pulsas Enter

    El arnés recibe la pregunta. La respuesta está en un archivo del proyecto, no en el modelo.

  2. 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?

  3. 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")

  4. 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.

  5. 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"

  6. 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.

  7. 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»

  1. Escribes y pulsas Enter

    Ahora es una tarea, no una pregunta. Hará falta leer código, editarlo y comprobarlo.

  2. 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

  3. 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")

  4. El arnés lee los archivos

    Leer archivos del proyecto está permitido, así que el arnés ejecuta las dos lecturas.

  5. 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() … }

  6. 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")

  7. 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.

  8. 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

  9. 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.

  10. 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)

  11. 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")

  12. El arnés edita y formatea otra vez

    Las mismas reglas de permisos y el mismo hook de formato que en la vuelta anterior.

  13. 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

  14. 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.

  15. 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.

  1. Sección 01

    Fundamentos

    Cómo pedir bien una tarea y qué información necesita el agente, ahora y entre sesiones.

    1. Empieza aquí
      Setup base

      El punto de partida: un agente sin configuración adicional.

    2. En la ruta
      Diseñar tareas para un agente

      Objetivo, límites y criterios de aceptación para un encargo claro.

    3. En la ruta
      Diseño del contexto

      La información justa para cada decisión del agente.

    4. En la ruta
      Estado y memoria

      Guardar el progreso fuera del modelo para que sobreviva entre sesiones.

  2. Sección 02

    Contexto del proyecto

    Instrucciones persistentes y procedimientos reutilizables para orientar el trabajo.

    1. En la ruta
      AGENTS.md

      Instrucciones persistentes que presentan el proyecto al agente.

    2. En la ruta
      Skills

      Procedimientos reutilizables que se cargan solo cuando hacen falta.

  3. Sección 03

    Capacidades externas

    Herramientas, servidores externos y los límites que contienen lo que el agente puede hacer.

    1. En la ruta
      Herramientas y permisos

      Qué puede hacer el agente sin preguntar, qué requiere aprobación y qué se bloquea.

    2. En la ruta
      MCP

      Un estándar para conectar el agente con servicios externos.

    3. En la ruta
      Ejecución segura

      Capas del entorno que limitan el daño aunque el agente se equivoque.

  4. Sección 04

    Control y coordinación

    Comprobar el resultado, automatizar los controles y repartir el trabajo sin perder el control.

    1. En la ruta
      Verificación y evaluación

      Comprobar el resultado con evidencias, no con el resumen del agente.

    2. En la ruta
      Hooks

      Comandos que se ejecutan solos en momentos concretos, sin depender de que el agente se acuerde.

    3. En la ruta
      Subagentes y delegación

      Repartir una tarea entre agentes con encargos claros y una verificación final.