AI Coding Harness (Arreio de Segurança para Codificação com IA)

O que é

Um AI coding harness (arreio de segurança para codificação com IA) é a estrutura de reforço e verificação que você constrói ao redor de um agente de codificação para que ele possa rodar de forma autônoma sem quebrar nada. Enquanto uma guardrail (proteção) é um hábito que você precisa lembrar de seguir (rodar os testes, ler o diff), um harness é uma máquina que lembra por você: ele fica entre a intenção do agente e o mundo real, e a cada passo perigoso ele registra, avisa ou bloqueia. O dancinlab/harness é um motor de referência independente de projeto — um núcleo compartilhado em TypeScript onde cada repositório se diferencia apenas por um harness.config.json mais alguns arquivos de dados .harness/*.json.

Pontos fortes

Transforma suas guardrails de hábitos opcionais em regras impostas por código — o agente não consegue simplesmente pular por cima delas.
Cobre todo o ciclo de vida da ferramenta: antes de um comando rodar, antes de um arquivo ser escrito, no , no e no push.
Um ledger (livro-razão) aqui é como um caderno em que você só adiciona linhas novas e nunca apaga as antigas. Esses ledgers são escritos em JSONL ( Lines — um objeto JSON por linha) e fornecem um registro à prova de adulteração de tudo que o agente fez. São baratos de escrever e triviais de auditar.
Se encaixa em qualquer repositório: o comportamento é definido por configuração e dados, não por código bifurcado (fork).
Projetado para ficar quieto quando tudo está bem, para que os avisos ainda signifiquem alguma coisa.

Trade-offs (contrapartidas)

É encanamento, não mágica: um harness torna os erros baratos de detectar, ele não torna a IA correta.
Precisa de uma configuração inicial ajustada às zonas de perigo do seu projeto.
Regras excessivamente rígidas criam atrito; a disciplina do "bitter-gate" (aposentar uma regra adormecida antes de adicionar uma nova) existe justamente para combater isso.
É mais valioso em projetos reais com usuários reais — é exagero para um protótipo descartável.

Melhor para

Vibe coding sério, em que você deixa um agente fazer mudanças em vários arquivos e rodar comandos praticamente sem supervisão, e você precisa que o custo de uma ação ruim fique perto de zero.

Os cinco princípios (H1–H5)

H1 Sucesso silencioso, falha ruidosa — nenhum ruído que você vá aprender a ignorar.
H2 Nunca corrigir automaticamente — propor, bloquear ou avisar; um humano ou o agente informado decide.
H3 Bitter-gate — aposentar uma regra adormecida antes de adicionar uma nova.
H4 Guiado por configuração — um único motor, harness.config.json por projeto.
H5 Nativo de IA — ledgers em JSONL somente-para-anexar, impossíveis de reescrever silenciosamente.

Como se parece

Um esboço mínimo de configuração:

// 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"
}

E o fluxo de hooks pré/pós em torno de uma única ação do 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
   └──────────┘

O agente nunca consegue burlar o portão — esse é todo o ponto.