Arnés de codificación con IA (AI Coding Harness)

Qué es

Un arnés de codificación con IA (AI coding harness) es el andamiaje de aplicación de reglas y verificación que construyes alrededor de un agente de codificación para que pueda funcionar de forma autónoma sin romper nada. Mientras que una barrera de seguridad (guardrail) es un hábito que tienes que recordar (ejecutar las pruebas, leer el diff), un arnés es una máquina que recuerda por ti: se coloca entre la intención del agente y el mundo real, y en cada paso peligroso registra, advierte o bloquea. dancinlab/harness es un motor de referencia independiente del proyecto — un núcleo compartido en TypeScript donde cada repositorio difiere únicamente por un harness.config.json más unos pocos archivos de datos .harness/*.json.

Fortalezas

• Convierte tus barreras de seguridad de hábitos opcionales en reglas aplicadas por código — el agente no puede saltárselas.
• Controla todo el ciclo de vida de la herramienta: antes de ejecutar un comando, antes de escribir un archivo, en el prompt, en el commit y en el push.
• Un ledger (libro de registro) aquí es como un cuaderno en el que solo añades líneas nuevas y nunca borras las antiguas. Estos ledgers se escriben en JSONL (JSON Lines — un objeto JSON por línea) y ofrecen un registro a prueba de manipulaciones de todo lo que hizo el agente. Son baratos de escribir y triviales de auditar.
• Se integra en cualquier repositorio: el comportamiento es configuración y datos, no código bifurcado (forked).
• Está diseñado para permanecer silencioso cuando todo va bien, para que las advertencias sigan teniendo significado.

Contrapartidas

• Es plomería, no magia: un arnés hace que los errores sean baratos de detectar, no hace que la IA sea correcta.
• Requiere una configuración inicial y un ajuste fino a las zonas de peligro de tu proyecto.
• Las reglas demasiado estrictas generan fricción; la disciplina del "bitter-gate" (retirar una regla inactiva antes de añadir una nueva) existe precisamente para combatir esto.
• Es más valioso en proyectos reales con usuarios reales — es excesivo para un prototipo desechable.

Mejor para

Vibe coding serio, en el que dejas que un agente haga cambios en varios archivos y ejecute comandos en gran medida sin supervisión, y necesitas que el costo de una acción incorrecta se mantenga cercano a cero.

Los cinco principios (H1–H5)

• H1 Éxito silencioso, fallo ruidoso — sin ruido que termines aprendiendo a ignorar.
• H2 Nunca corregir automáticamente — proponer, bloquear o advertir; decide un humano o el agente informado.
• H3 Bitter-gate — retirar una regla inactiva antes de añadir una nueva.
• H4 Impulsado por configuración — un solo motor, un harness.config.json por proyecto.
• H5 Nativo de IA — ledgers en JSONL de solo anexado, imposibles de reescribir en silencio.

Cómo se ve

Un boceto mínimo de configuración:

// harness.config.json
{
  "lockedPaths": ["src/auth/**", "infra/**", ".github/**"],
  "blockCommands": ["rm -rf", "git push --force", "curl * | sh"],
  "verify": ["npm run lint", "npm run typecheck", "npm test"],
  "ledger": ".harness/ledger.jsonl"
}

Y el flujo de hooks pre/post alrededor de una sola acción del agente:

agent intends an action
        │
   ┌────▼─────────────┐
   │ pre  (PreToolUse) │  block dangerous? warn? → else allow
   └────┬─────────────┘
        │  command runs / file is written
   ┌────▼──────────────┐
   │ post (PostToolUse) │  record to JSONL · warn if a locked file was touched
   └────┬──────────────┘
        │  at commit / push
   ┌────▼─────┐
   │  verify  │  lint · typecheck · tests (parallel) → green or stop
   └──────────┘

El agente nunca puede eludir la puerta de control — ese es todo el sentido.