Engineering harness na prática: seis planos para transformar intenção em evidência

Um agente recebe uma tarefa, abre arquivos, usa ferramentas, produz uma mudança e anuncia que terminou. O resultado pode estar certo. O problema é que “pode estar certo” não é uma propriedade operacional.

Para confiar no trabalho, precisamos saber o que foi pedido, que autoridade existia, qual ambiente foi usado, o que foi verificado, que evidência foi preservada e quem decidiu aceitar. É isso que um engineering harness organiza.

Este artigo é um companion técnico de “O modelo não é o sistema”. Em vez de discutir a tese em alto nível, apresenta um desenho mínimo em seis planos: intenção, política, execução, verificação, evidência e feedback.

Resumo executivo

Um harness não precisa ser uma plataforma monolítica. Ele é um conjunto de fronteiras explícitas ao redor de um executor probabilístico.

Cada plano possui um contrato, uma falha típica e uma evidência mínima:

As fontes examinadas pela FORGE sustentam a separação entre histórico de sessão, orquestração e isolamento de execução; também mostram que complexidade adicional pode melhorar uma tarefa e aumentar materialmente custo e latência. Essas conclusões são delimitadas às implementações estudadas, não uma receita universal. [HARNESS31-C2] [HARNESS31-C3]

O contrato mínimo

Antes de pensar em agentes especializados, um fluxo pode ser descrito assim:

task:
  objective: "publicar o artigo aprovado"
  subject: "FORGE-ARTICLE-A09"
  out_of_scope:
    - "alterar o texto aprovado"
    - "expor conteúdo antes de publish_at"

authority:
  read: ["projecao-editorial"]
  write: ["artefato-estatico"]
  external_effects: ["deploy-pages"]
  requires_human_approval: ["aprovar-artigo", "alterar-agenda"]

verification:
  required: ["digest", "links", "a11y", "secrets", "clock-boundary"]

evidence:
  bind_to: ["article_digest", "commit_sha", "build_id", "deploy_id"]

O formato pode mudar. As responsabilidades não deveriam desaparecer dentro de um prompt.

Plano 1 — intenção

Intenção transforma linguagem aberta em um problema executável.

Contrato

• outcome e público afetado;
• asset ou sistema que será modificado;
• entradas autorizadas;
• fora de escopo;
• critérios de aceite;
• efeitos externos esperados;
• autoridade que aprova a conclusão.

Falha típica

O agente escolhe uma interpretação plausível, otimiza uma métrica local e entrega algo tecnicamente correto para a pergunta errada.

Evidência mínima

Uma spec versionada, ligada à issue e à revisão produzida. Se a intenção muda, a mudança precisa aparecer — não ser absorvida silenciosamente durante a execução.

Pergunta de projeto

Outra pessoa conseguiria distinguir “feito” de “parece bom” sem conversar com o executor?

Plano 2 — política

Política define autoridade antes que a ferramenta seja chamada.

Contrato

• recursos legíveis e graváveis;
• comandos, APIs e canais permitidos;
• classificação de dados;
• orçamento de custo, tempo e tentativas;
• ações reversíveis e irreversíveis;
• condições de parada e escalada;
• gates humanos.

Falha típica

O modelo interpreta a disponibilidade de uma ferramenta como permissão para qualquer uso. Um acesso conveniente vira autoridade organizacional.

Evidência mínima

Uma policy endereçável e um mecanismo que a imponha: allowlist, token escopado, ambiente isolado, branch protection, aprovação ou deny-by-default.

As fontes públicas examinadas descrevem capabilities compartilhadas e escopadas, mas não oferecem um modelo universal de autorização. Cada produto ainda precisa definir revogação, privilégio mínimo e testes de fronteira. [HARNESS31-C4]

Plano 3 — execução

Execução é onde intenção e autoridade encontram ferramentas e estado.

Contrato

• identidade da sessão;
• revisão ou worktree exclusiva;
• runtime e dependências;
• fontes de contexto;
• estratégia de checkpoint e retomada;
• limites de paralelismo;
• destino de outputs e logs.

Falha típica

Duas tarefas modificam o mesmo escopo, uma sessão herda contexto antigo, uma falha apaga progresso ou um resultado não pode ser atribuído ao ambiente que o produziu.

Evidência mínima

ID da sessão, commit base, revisão final, ambiente, duração e outcome. Para tarefas longas, checkpoints precisam ser artefatos, não apenas mensagens.

Separar sessão, modelo e papel

A sessão preserva continuidade. O modelo oferece capacidade. O papel define responsabilidade. Misturar os três torna difícil trocar o modelo, retomar trabalho ou auditar autoridade.

Plano 4 — verificação

Verificação responde propriedades específicas. Ela não é uma votação entre agentes.

Contrato

Para cada controle:

• subject e revisão exatos;
• propriedade observada;
• ferramenta, versão e configuração;
• política de aprovação;
• independência necessária;
• limites e falsos negativos conhecidos.

Falha típica

O mesmo executor cria a mudança, escreve o teste, interpreta o resultado e publica a conclusão. Um único erro de entendimento atravessa todas as camadas e recebe vários nomes de “verde”.

Evidência mínima

Relatório ou resultado reprodutível preso à revisão. Teste unitário, contrato, scanner de segredo, eval comportamental e navegação real ficam separados porque provam coisas diferentes.

Complexidade tem custo

Em um experimento público de desenvolvimento de aplicações de longa duração, planner, generator e evaluator melhoraram o resultado observado, com aumento material de custo e duração. O dado sustenta medir e fazer ablação; não sustenta criar três agentes para toda tarefa. [HARNESS31-C3]

Mantenha um controle porque ele reduz uma classe de falha ou risco mensurável. Remova-o quando uma alternativa mais simples demonstrar a mesma proteção.

Plano 5 — evidência

Evidência liga afirmação ao que foi realmente observado.

Contrato

• subject e digest;
• origem e versão;
• executor e verificador;
• controles aplicados;
• receipts e relatórios;
• validade e limite de inferência;
• aprovador;
• residual conhecido.

Falha típica

Uma página afirma “seguro”, “completo” ou “aprovado”, mas o relatório pertence a outro commit, outro ambiente ou outra data. A evidência existe; o binding não.

Evidência mínima

Um manifest imutável que permita resolver claim → fonte → receipt → asset publicado. A ausência de qualquer elo precisa falhar de forma fechada.

Estado é parte da claim

“Specified” diz que existe desenho. “Observed” diz que algo foi visto. “Enforced” diz que um mecanismo aplica uma regra. “Qualified” exige um corte de aceitação definido. Nenhum estado herda o seguinte por proximidade ou entusiasmo.

Plano 6 — feedback

Feedback fecha a distância entre corrigir uma ocorrência e melhorar o sistema.

Contrato

• evento que abriu o loop;
• causa e impacto;
• correção imediata;
• mudança durável;
• regressão ou controle;
• owner e prazo residual;
• critério de fechamento.

Falha típica

O agente tenta novamente até obter verde. A execução termina, mas a classe de falha continua intacta.

Evidência mínima

Um teste, padrão, decisão, atualização de contexto ou política ligado ao evento original. Fechar a issue sem mudança durável é apenas fechar a fila.

Exemplo 1 — mudança de software

Pedido: adicionar autenticação social.

• Intenção: provedores, jornadas, erros e critérios de aceite.
• Política: segredo server-side, callbacks allowlisted, dados mínimos e aprovação de segurança.
• Execução: worktree isolada, ambiente de teste e identidade de deploy.
• Verificação: contratos OAuth, tenant isolation, scanner, testes e fluxo móvel real.
• Evidência: relatórios e deploy ligados ao mesmo commit.
• Feedback: falhas geram regressões, documentação e ajuste de policy.

Sem harness, o demo de login pode funcionar enquanto a fronteira de identidade permanece errada.

Exemplo 2 — publicação de artigo

Pedido: publicar amanhã às 09h.

• Intenção: texto, canonical, sequência e horário aprovados.
• Política: automação pode projetar e publicar; não pode reescrever o conteúdo.
• Execução: build horário com credenciais fora do repositório.
• Verificação: digest, fontes, links, acessibilidade, segredos e relógio.
• Evidência: commit, build, deploy e URL pública.
• Feedback: correção preserva data e registra nota; falha social não duplica postagem.

Esse exemplo mostra que o harness não é exclusivo de código. Ele organiza qualquer fluxo em que IA produz artefatos e existe efeito externo.

Métricas por plano

Evite um dashboard enorme no início. Escolha sinais que ajudem a decidir:

Cruze esses sinais com outcome, custo e tempo. Um sistema pode ficar mais controlado e deixar de ser economicamente útil; ou ficar rápido enquanto aumenta risco invisível.

Como começar pequeno

1. Escolha um fluxo com efeito real e reversível.
2. Escreva intenção e fora de escopo em uma página.
3. Liste as capabilities mínimas e negue o restante.
4. Ligue dois ou três controles a propriedades distintas.
5. Gere um manifest simples com revisão, relatórios e aprovador.
6. Faça a primeira correção produzir uma regressão.
7. Meça o custo de cada plano e simplifique com evidência.

Depois disso, decida se precisa de um orquestrador, vários agentes ou uma plataforma maior. A arquitetura deve responder à carga e ao risco observados.

Conclusão

Engineering harness é a disciplina de tornar trabalho agentic governável.

Intenção evita velocidade na direção errada. Política impede que ferramenta vire autoridade. Execução preserva identidade e estado. Verificação separa propriedades. Evidência liga resultado à origem. Feedback transforma correção em capacidade permanente.

O objetivo não é cercar a IA até que ela deixe de ser útil. É criar confiança suficiente para delegar mais — e manter os humanos responsáveis pelas decisões que definem propósito, risco e efeito no mundo.

Leitura anterior: O modelo não é o sistema. Próxima leitura: A IA amplifica a empresa que você já tem.