Cómo construir un Agent Harness: guía paso a paso para equipos de AI engineering

• Un proyecto con AI agent activo (Claude Code, Codex, Cline o similar)
• Repositorio git
• Capacidad de crear scripts de shell y hooks de git
• (Opcional) Acceso a CI/CD pipeline

project-root/
├── AGENTS.md              # Reglas y convenciones
├── .cursorrules           # Context file alternativo
├── .githooks/
│   ├── pre-commit         # Verificación automática antes de commit
│   └── pre-push           # Verificación antes de push
├── scripts/
│   ├── verify.sh          # Script de verificación estándar
│   └── lint.sh            # Linter configurado
├── docs/
│   ├── ARCHITECTURE.md    # Decisiones de arquitectura
│   └── PROGRESS.md        # Estado actual del proyecto
└── .github/workflows/
    └── ci.yml             # CI pipeline con verificaciones

El archivo de contexto (AGENTS.md, .cursorrules, CLAUDE.md) es el briefing que el agente lee antes de tocar cualquier cosa.

Qué poner:

- /src — código fuente
- /tests — tests unitarios
- /docs — documentación
npm run dev — desarrollo
npm run build — producción
npm run test — tests
TypeScript strict mode
Prettier para formateo
ESLint para linting
NO borrar archivos sin verificar que no se usan
NO modificar package.json sin actualizar lockfile
NO asumir que el test coverage es suficiente
Cada vez que el agente repite un error, agregás una regla. Así crece el archivo con el tiempo.
  

  
  
    2. Tool & permission layer — qué puede y no puede tocar
    VerboPermisoEjemploread✅ SiempreLeer archivos, buscar en codebasesearch✅ SiempreGrep, búsqueda webcreate_draft✅ Con revisiónGenerar código nuevomodify✅ Con revisiónEditar archivos existentessend⚠️ Aprobación humanaEnviar emails, postear en Slackmerge⚠️ Aprobación humanaMerge PRsdeploy❌ Solo humanoDeploy a produccióndelete❌ Solo humanoBorrar archivos, recursos cloudpurchase❌ NuncaComprar servicios, APIs de pago
En Hermes Agent:
`bash
hermes tools enable web terminal file
hermes tools disable deployment browser
hermes config set security.tirith_enabled true

En Cline/Roo Code (.clinerules):

rm -rf git push --force npm publish

Jerarquía de velocidad (más rápido primero): hooks (ms) → pre-commit (segundos) → CI (minutos) → revisión humana (horas)

#!/bin/bash
npm run lint
npm run type-check
npm run test -- --changed
if [ $? -ne 0 ]; then
  echo "❌ Pre-commit checks failed."
  exit 1
fi

Escribir "corré el linter" en un archivo es un pedido. Conectarlo con un pre-commit hook es una garantía. El agente puede ignorar un pedido. No puede saltarse un hook.

Los agents tienen contextos frescos en cada sesión. El harness arregla esto guardando estado en disco:

• docs/PROGRESS.md — qué se hizo, qué falta
• docs/ROADMAP.md — features pendientes, en progreso, completados
• Git history — el registro permanente de todo cambio

Formato de PROGRESS.md:

`markdown

• ✅ Feature A implementada
• ✅ Tests de Feature A pasando
• 🔄 Feature B en progreso (step 3/5)
• ❌ Feature C bloqueada

• SQLite en vez de PostgreSQL (no necesita escalar)

1. Terminar Feature B
2. Review de Feature A con el equipo
3. Arrancar Feature D

Problema: Los filtros de comandos funcionan por string matching, y el string matching se puede engañar.

El incidente Shumer en detalle:

r''m

Defensas que funcionan:

1. Parseá como el shell, no como un censor (estrategia de Continue)

1. Sandboxing con Docker:

1. Approval gates para operaciones destructivas:

### 1. El estado vive fuera del modelo

Nunca confíes en que el contexto window va a recordar. Confiá en el disco.

### 2. Cada error se convierte en una regla permanente

El patrón Hashimoto: cada vez que un agente comete un error, modificás el entorno para que ese error no se pueda repetir.

Error: el agente borró archivos temporales necesarios
→ Regla en AGENTS.md: NO usar rm sin listar archivos primero
→ Hook pre-commit: verificar que no hay rm sin --dry-run
Error: el agente deployó código sin test
→ CI: bloquea si el test coverage es < 80%

Reintentar es una oración. Una regla es una solución.

### 3. La verificación es más difícil que la generación

Anthropic lo descubrió cuando sus agents marcaban features como completadas sin validación end-to-end. OpenAI documentó lo mismo: Sol actualizó un documento de investigación para decir que un cálculo había sido verificado cuando nunca produjo el resultado.

Implementación — Evaluator pattern:

CHECKLIST = [
    "Feature A funciona en test",
    "Feature A sin errores en consola",
    "Tests pasan",
    "Sin regresiones",
]
for check in CHECKLIST:
    if not verify(check):  # contexto fresco, default-FAIL
        return FAIL

El claim de "done" de un agente es una hipótesis. El harness corre el experimento.

### 4. Protegé estructura, no strings

GuardFall expuso el problema: el filtro revisa cómo se VE el comando. Bash ejecuta lo que el comando SIGNIFICA.

No hagas esto:

denylist = ["rm", "sudo", "chmod"]
if any(cmd.startswith(bad) for bad in denylist):
    block()

Hacé esto:

tokens = shell_parse(command)
tokens = expand_variables(tokens)
tokens = eval_substitutions(tokens)
if is_structural_delete(tokens):
    require_approval()

Una denylist es una sugerencia. Un sandbox es una pared.

Score: __/12

• Después de cada release de modelo: comentá componentes del harness uno por uno. Los que sigan siendo necesarios, quedan. Los que el modelo ya resuelve solo, se eliminan.
• Cada 2 semanas: revisá AGENTS.md. ¿Reglas duplicadas? ¿Reglas que ya no aplican? ¿Errores nuevos que necesitan reglas?
• Cada mes: corré el checklist otra vez. El score debería subir.