🧰 Entiende qué es un harness
El harness define: qué puede ver el agente, qué herramientas puede usar, qué acciones puede ejecutar, qué reglas debe seguir, cómo se selecciona el contexto, cómo se conserva el estado, cómo se verifican los resultados, cuándo detenerse y qué requiere aprobación. La diferencia no está en el prompt, sino en el sistema creado alrededor del agente.
🆕 ¿Nuevo por aquí?
Harness significa literalmente «arnés»: el equipo que conecta la fuerza con el trabajo y le da dirección. Aquí es todo lo que rodea al modelo. Sandbox es un entorno desechable, aislado del resto. Observabilidad es el conjunto de logs y métricas que permite reconstruir lo que pasó después de los hechos.
Cómo leer: la solicitud entra por la izquierda y solo llega a la caja iluminada (entrega) después de pasar por ejecución aislada, pruebas, revisión y gates. Observa que ninguna flecha salta directamente del plan a la entrega: esa ausencia de atajos es lo que caracteriza a un harness.
Ver
Contexto seleccionado
Hacer
Herramientas y permisos
Probar
Verificadores
Detener
Límites y aprobación
🗂️ Selecciona el contexto con intención
El contexto es el conjunto de archivos, documentos, ejemplos e información relevantes para la tarea. La tentación es echarlo todo. El resultado de echarlo todo es un agente que imita el peor patrón del repositorio con la misma naturalidad con que imita el mejor.
✓ Contexto que ayuda
- ✓La especificación de la tarea (fuente de la verdad)
- ✓Los 3–8 archivos que realmente se modificarán
- ✓Un ejemplo bueno del patrón que quieres replicar
- ✓Las pruebas relacionadas y cómo ejecutarlas
- ✓El AGENTS.md con comandos y reglas del proyecto
✗ Contexto que estorba
- ✗Todo el repositorio «por si acaso»
- ✗Documentación desactualizada que contradice el código
- ✗Código heredado que justamente quieres abandonar
- ✗Dos fuentes de verdad que dicen cosas diferentes
- ✗Historial de chat irrelevante arrastrado hacia adelante
💡 Consejo práctico
Antes de ejecutar al agente, escribe en una línea: "¿qué necesita leer para no suponer nada?". Si la respuesta tiene más de diez archivos, probablemente la tarea es demasiado grande: divídela antes de ejecutar.
Curaduría
Elegir es el trabajo
Buen ejemplo
Vale más que la descripción
Fuente única
Evita instrucciones contradictorias
Tarea grande
Provoca el fallo antes de ejecutar
🔑 Define herramientas y permisos
Las herramientas son el terminal, el editor, la búsqueda, las pruebas, la base de datos y las APIs. Los permisos definen qué se puede leer, modificar, ejecutar o publicar con cada una. El permiso implícito es permiso total — y la mayoría de los incidentes con agentes se deben a accesos que nadie decidió conceder, simplemente no los denegó.
🧪 Ejercicio copiable — declara el harness en AGENTS.md
Objetivo: sacar los permisos de tu cabeza y ponerlos en un archivo versionado que el agente lee antes de actuar. Crea AGENTS.md en la raíz del repositorio con este contenido, ajustando lo que está entre < >.
# AGENTS.md ## Comandos - instalar: <comando> - testar: <comando de teste> - lint: <comando de lint> - build: <comando de build> ## Pode (sem perguntar) - ler qualquer arquivo do repositório - criar branch e commitar na branch de trabalho - rodar testes, lint e build - criar e editar arquivos em <pastas permitidas> ## Não pode (exige aprovação humana explícita) - alterar arquivos de teste existentes - adicionar ou atualizar dependências - rodar migração de banco - alterar CI/CD, secrets, infraestrutura ou permissões - fazer push na branch principal ou deploy ## Limites - no máximo <N> arquivos alterados por tarefa - no máximo <N> tentativas de correção antes de parar e me perguntar - se a mesma falha ocorrer 2 vezes, pare e relate — não tente uma terceira ## Definição de pronto - os testes passam (cole a saída real, não resuma) - nenhum arquivo fora do escopo foi tocado - o diff cabe em uma revisão de 10 minutos
Cómo verificar: pídele al agente: «lee el AGENTS.md y dime, en una lista, qué NO puedes hacer en esta tarea». Si no repite correctamente tus prohibiciones, el archivo es ambiguo: reescríbelo antes de delegar cualquier cosa.
⚠️ Atención
Un agente con acceso a secrets, producción o CI/CD es un usuario privilegiado; trátalo como tal: identidad propia, credencial con los mínimos privilegios y registro de auditoría. «Es solo un asistente» no es un modelo de amenazas.
Mínimo privilegio
La regla es denegar
Escrito
Una regla fuera del archivo no existe
Identidad
El agente es un usuario, no magia
Auditoría
Toda acción deja un rastro
📦 Aísla la ejecución en un sandbox
Sandbox es el entorno aislado donde el agente ejecuta tareas sin afectar la producción ni tu entorno de trabajo. Es lo que transforma un «error del agente» en un «intento descartado», y lo que permite conceder más autonomía con menos temor.
Aislamiento de código
Branch dedicada o git worktree por separado. Descartar es git worktree remove — costo cero, sin ensuciar tu directorio de trabajo.
Aislamiento de ejecución
Contenedor o VM con red restringida. El agente puede ejecutar lo que quiera allí dentro; lo que no puede alcanzar, no se rompe.
Aislamiento de datos
Base desechable con datos sintéticos o anonimizados. Nunca apuntes un agente autónomo a la base de producción, ni siquiera para leer, si allí hay datos personales.
Equivocarse a bajo costo
Es el objetivo del sandbox
Worktree
Aislamiento de código económico
Red restringida
Limita el alcance real
Dato sintético
La producción queda fuera
🧠 Gestiona memoria, estado y observabilidad
La memoria es lo que lleva consigo; el estado es dónde se detuvo; la observabilidad es lo que quedó registrado. Los tres resuelven problemas diferentes y se confunden con frecuencia.
📊 Qué registrar en cada ejecución
- • Entrada: qué spec, qué contexto, qué versión del repositorio (commit).
- • Acciones: comandos ejecutados y archivos modificados, en orden.
- • Verificación: la salida real de las pruebas, no el resumen del agente.
- • Costo: tiempo, intentos y tokens consumidos.
- • Resultado: éxito, desistimiento o interrupción — y por qué.
Monitor de ejecución (recreación ilustrativa, no es una captura de pantalla real)
[plano] 3 pasos · 4 archivos previstos
[exec ] editó src/pagamentos/idempotencia.ts
[teste] 128 pasaron · 1 falló (duplicidad)
[exec ] intento 2/3 · corrigió la clave compuesta
[teste] 129 pasaron · 0 fallaron
[gate ] esperando aprobación: migración detectada
Cómo leer: cada línea es un evento auditable. «intento 2/3» muestra que el límite funciona; la última línea muestra que el loop se detiene por sí solo ante una acción irreversible: exactamente el comportamiento que quieres.
Memoria
Qué carga
Estado
Dónde se detuvo
Log
Qué quedó demostrado
Salida real
Nunca su resumen
✅ Instala verificadores y límites
Los verificadores son las pruebas y validaciones que evalúan la calidad del resultado. Los límites son los topes de tiempo, costo, intentos, archivos modificados y acciones permitidas. La calidad del verificador determina cuánta autonomía puedes conceder — no la calidad del modelo.
📏 Los límites que vale la pena configurar hoy
- •Archivos modificados: mantiene el diff revisable y denuncia cuando el alcance se excede.
- •Intentos: impide repetir la misma corrección con otra apariencia.
- •Tiempo y costo: convierte «estuvo funcionando toda la noche» en una alerta, no en una factura.
- •Acciones prohibidas: deploy, migración, secret, rama principal: siempre con una persona.
Chequeo rápido: quieres aumentar la autonomía del agente en un repositorio. ¿Qué inversión tiene más efecto?
Verificador
Autoriza la autonomía
Prueba rápida
El loop solo funciona si es rápido
Límite
Freno cuando todo lo demás falla
Aprobación
Parte del harness, no un extra
📌 Resumen del módulo
Próximo módulo:
2.2 - Loop Engineering: el ciclo que ejecuta, prueba, corrige y sabe cuándo detenerse.