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.

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): `

npm run build npm run test git add -A git commit -m "..." git push

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)

`bash #!/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: `bash 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: `python 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: `python denylist = ["rm", "sudo", "chmod"] if any(cmd.startswith(bad) for bad in denylist): block() `

Hacé esto: `python 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.