Harness engineering, não só prompt engineering

Você melhora o prompt. O agente executa a tarefa corretamente uma vez. Depois, comete o mesmo erro.

Esse ciclo indica um problema de camada. O prompt orienta uma interação. O harness orienta o agente durante todo o trabalho.

Origem do termo

Os primeiros usos públicos do termo são recentes e estão documentados.

Em 5 de fevereiro de 2026, Mitchell Hashimoto (cofundador da HashiCorp, criador do Terraform e do Ghostty) publicou My AI Adoption Journey. No passo 5, ele nomeia a prática de harness engineering: quando o agente comete um erro, você modifica o ambiente para impedir a repetição do erro. Ele mesmo ressalva que não sabe se a indústria já tem um termo aceito para isso. Se surgir outro, ele adere.

Em 11 de fevereiro, a OpenAI publicou Harness engineering: leveraging Codex in an agent-first world. Ryan Lopopolo assina o artigo, que descreve um experimento interno de cinco meses.

Em 17 de fevereiro, Birgitta Böckeler, da Thoughtworks, publicou um memo no site do Martin Fowler. Em 2 de abril, ela publicou a versão ampliada, que substituiu o memo: Harness engineering for coding agent users. O artigo organiza os principais conceitos da disciplina.

O que é um harness

O termo harness virou atalho para tudo que compõe um agente, exceto o modelo. A LangChain resume a relação em uma fórmula:

Agente = Modelo + Harness

Böckeler considera essa definição ampla demais e a restringe ao contexto de agentes de código. Nesse contexto, o harness tem duas partes.

Uma parte vem embutida na ferramenta que você usa: o system prompt, o mecanismo de busca no código, a orquestração. A outra parte pertence ao seu projeto: as regras, os documentos e as ferramentas que você cria para o agente. Böckeler chama essa segunda parte de outer harness.

Harness engineering, para quem usa agentes de código, é o trabalho de projetar e manter essa segunda parte.

A regra de Hashimoto

Hashimoto descreve um hábito simples: cada erro do agente produz uma correção permanente no ambiente. Ele aplica dois tipos de correção:

1. Instruções no AGENTS.md. O agente usa o comando errado ou a API errada? Adicione uma regra ao arquivo.
2. Ferramentas programadas. Scripts para capturar screenshots, rodar testes filtrados e tarefas similares. A ferramenta nova normalmente entra no AGENTS.md. Assim, o agente sabe que ela existe e quando usar.

Hashimoto registra outra conclusão no mesmo texto: o agente corrige mais erros quando consegue verificar o próprio trabalho.

Um harness real de 12 linhas

O exemplo que Hashimoto usa é público e vem do próprio projeto dele. O AGENTS.md do inspector do Ghostty tem 12 linhas e 589 bytes. Este é o arquivo completo:

# Inspector Subsystem

The inspector is a feature of Ghostty that works similar to a
browser's developer tools. It allows the user to inspect and modify the
terminal state.

- See the full C API by finding `dcimgui.h` in the `.zig-cache` folder
  in the root: `find . -type f -name dcimgui.h`. Use the newest version.
- See full examples of how to use every widget by loading this file:
  <https://raw.githubusercontent.com/ocornut/imgui/refs/heads/master/imgui_demo.cpp>
- On macOS, run builds with `-Demit-macos-app=false` to verify API usage.
- There are no unit tests in this package.

Hashimoto afirma que cada linha nasceu de um comportamento ruim do agente, e que o arquivo resolveu quase todos. O relato é dele, sem medição controlada. Ainda assim, mostra o tamanho do investimento inicial: um arquivo pequeno, alimentado por erros reais.

O experimento da OpenAI

O artigo da OpenAI descreve um experimento interno. No fim de agosto de 2025, o primeiro commit chegou a um repositório vazio, com uma restrição: nenhuma linha de código escrita à mão. O Codex gera todo o código, com o scaffold inicial guiado por um pequeno conjunto de templates existentes. Três engenheiros conduziram o trabalho no início. Hoje o time tem sete.

Resultados relatados após cinco meses:

• Aproximadamente um milhão de linhas de código.
• Aproximadamente 1.500 pull requests abertos e integrados, uma média de 3,5 PRs por engenheiro por dia.
• Tempo estimado em um décimo do necessário para escrita manual.
• Centenas de usuários internos, com testadores externos em alpha.

O artigo resume a divisão de trabalho em quatro palavras: “Humans steer. Agents execute.” Os humanos definem prioridade, especificam intenção e validam resultado. Os agentes executam.

Práticas descritas no artigo:

• Use o AGENTS.md como mapa, não como manual. O time testou um arquivo gigante. A abordagem falhou: consumia contexto, diluía prioridade e ficava desatualizada. A versão atual tem cerca de 100 linhas e aponta para uma base de conhecimento em docs/, a fonte de verdade do projeto. Estrutura resumida:

AGENTS.md
ARCHITECTURE.md
docs/
|-- design-docs/
|   |-- index.md
|   |-- core-beliefs.md
|   `-- ...
|-- exec-plans/
|   |-- active/
|   |-- completed/
|   `-- tech-debt-tracker.md
|-- product-specs/
|-- references/
|-- QUALITY_SCORE.md
|-- RELIABILITY.md
`-- SECURITY.md

• Aplique as restrições de arquitetura por máquina. Cada domínio de negócio segue camadas fixas (Types -> Config -> Repo -> Service -> Runtime -> UI), com direções de dependência validadas. Linters customizados e testes estruturais bloqueiam violações.
• Inclua a correção na mensagem de erro. O time escreve os erros dos linters com a instrução de correção. A instrução entra no contexto do agente no momento da falha.
• Mantenha o conhecimento no repositório. O agente só usa a informação que consegue acessar. Decisão de arquitetura fechada no Slack precisa virar documento versionado.
• Exponha o runtime ao agente. O time tornou a aplicação inicializável por git worktree e expôs logs, métricas e traces ao Codex, com consultas via LogQL e PromQL. Com esse acesso, prompts com meta numérica se tornam verificáveis. Dois exemplos citados no artigo:

"ensure service startup completes in under 800ms"
"no span in these four critical user journeys exceeds two seconds"

O artigo relata execuções de uma única tarefa que passam de seis horas, muitas vezes enquanto os humanos dormem.

• Automatize a limpeza recorrente. No início, o time gastava as sextas-feiras (20% da semana) corrigindo código de baixa qualidade. Não escalou. O time então codificou princípios no repositório, os “golden principles”, e criou agentes recorrentes que detectam desvios e abrem pull requests de correção. A OpenAI afirma que a maioria pode ser revisada em menos de um minuto e integrada automaticamente.

Um detalhe muda a leitura dos 1.500 PRs: o repositório opera com poucos gates bloqueantes de merge. Os agentes muitas vezes fazem squash e merge dos próprios PRs. O próprio artigo admite: “This would be irresponsible in a low-throughput environment.”

Uma ressalva nossa antes dos limites: os números são autorrelato da OpenAI, sem auditoria externa. E o próprio time deixa questões em aberto. O comportamento autônomo depende da estrutura daquele repositório específico: não assuma que generaliza sem investimento similar, “pelo menos ainda não”. O time também admite que não sabe como a coerência da arquitetura evolui ao longo de anos, nem onde o julgamento humano rende mais.

Guias e sensores

Böckeler separa os controles do harness em dois grupos. Guias (feedforward) orientam o agente antes da ação e aumentam a chance de acerto na primeira tentativa. Sensores (feedback) verificam o resultado depois da ação e alimentam a autocorreção.

Cada controle tem um tipo de execução. Execução computacional é determinística e barata: pode rodar a cada mudança. Execução inferencial usa um LLM: é mais cara, não produz sempre o mesmo resultado e, em geral, não roda a cada commit. Ela entra onde o julgamento é semântico, posicionada conforme custo e criticidade.

Tabela adaptada dos exemplos de Böckeler:

Controle	Direção	Execução	Exemplos
Convenções de código	Guia	Inferencial	AGENTS.md, skills
Bootstrap de projeto	Guia	Ambas	Skill com instruções e script
Testes estruturais	Sensor	Computacional	Verificação de fronteiras de módulo no pre-commit
Análise estática	Sensor	Computacional	Linters, verificadores de tipo
Revisão de código	Sensor	Inferencial	Agente revisor com instruções próprias

Um sensor sem guia identifica o mesmo erro várias vezes. Um guia sem sensor cria uma regra sem verificação. Um harness eficaz precisa dos dois.

O papel do humano é um ciclo de direção, o steering loop: quando um problema se repete, melhore o guia ou o sensor correspondente.

Uma mensagem de sensor bem escrita ensina a correção. Böckeler chama isso de um tipo positivo de prompt injection. Exemplo ilustrativo, no formato da prática que a OpenAI descreve:

error[no-raw-fetch]: direct fetch call in src/services/user.ts:42
Use the fetchJson helper from src/lib/http.ts.
It adds timeout, retry, and telemetry.

O que o harness ainda não resolve

Böckeler mapeia os limites com precisão, e eles importam tanto quanto as práticas.

Sensores computacionais pegam o estrutural com confiabilidade: código duplicado, complexidade, cobertura ausente, desvio de arquitetura, violação de estilo. Sensores inferenciais cobrem parte dos problemas semânticos, de forma cara e probabilística.

Nenhum dos dois pega com confiabilidade os problemas de maior impacto: diagnóstico errado do problema, soluções superdimensionadas, instruções mal entendidas. E nenhum sensor garante correção se o humano não especificou com clareza o que queria.

O ponto mais aberto é o comportamento funcional. A prática comum hoje: especificação como guia, suíte de testes gerada por IA como sensor, mais teste manual. Böckeler avalia que isso deposita fé demais nos testes gerados e ainda não basta para reduzir a supervisão. Ela cita uma alternativa parcial, o padrão approved fixtures, que colegas dela aplicam de forma seletiva onde encaixa. Não é resposta geral ao problema.

Harness reduz classes conhecidas de erro. Ele não substitui especificação clara nem validação humana de comportamento.

Como começar

Os passos abaixo são o começo barato. Um arquivo de 12 linhas já muda o comportamento do agente, como Hashimoto relata no caso do Ghostty. O harness completo é outra escala: o da OpenAI evoluiu ao longo dos cinco meses do experimento. Böckeler avisa que construir um sistema coerente de guias e sensores é caro. O custo também depende do codebase: tipagem forte, fronteiras claras de módulo e frameworks previsíveis oferecem sensores de graça. Em sistemas legados com dívida técnica, ela aponta o problema mais duro: o harness é mais necessário exatamente onde é mais difícil de construir. Comece pequeno e deixe os erros reais priorizarem o investimento.

1. Crie um AGENTS.md curto na raiz do repositório. Registre a estrutura do projeto, os comandos de build e teste e as principais convenções. Um esqueleto mínimo basta:

# My Project

- Build: `make build`
- Test: `make test` (single test: `make test T=path/to/test`)
- Lint: `make lint`
- Architecture map: docs/ARCHITECTURE.md
- Conventions: docs/CONVENTIONS.md

2. Use o arquivo como mapa. Coloque explicações longas em documentos versionados e adicione os links no AGENTS.md.
3. Dê ao agente um método para verificar o próprio trabalho. Disponibilize comandos de teste, lint e build.
4. Modifique o ambiente quando o agente errar. Adicione a regra, o teste ou a ferramenta que impede a repetição.
5. Inclua a instrução de correção nas mensagens de erro. A OpenAI aplica essa prática nos linters customizados.
6. Revise o ciclo com frequência. Problema recorrente indica a ausência de um guia ou de um sensor.

O ponto central

Prompt engineering continua útil. Porém, o prompt é parte de um sistema maior.

Os guias orientam o agente. Os sensores verificam o resultado. O ciclo de melhoria transforma erro recorrente em regra, teste ou ferramenta no ambiente. Esse trabalho ocorre fora do prompt de cada tarefa e aproxima um agente imprevisível de um agente confiável.

Um bom harness não elimina o trabalho humano. Ele direciona a atenção humana para as decisões que exigem julgamento.

---

Fontes

• Mitchell Hashimoto, My AI Adoption Journey, 5 fev 2026
• OpenAI (Ryan Lopopolo), Harness engineering: leveraging Codex in an agent-first world, 11 fev 2026
• Birgitta Böckeler (martinfowler.com), Harness engineering for coding agent users, 2 abr 2026
• AGENTS.md do inspector do Ghostty (repositório público)
• LangChain (Vivek Trivedy), The Anatomy of an Agent Harness, 10 mar 2026