O termo vem da analogia com o arreio do cavalo ou equipamentos de segurança. O modelo sozinho é uma força bruta com muita inteligência, mas sem controle. O harness é a estrutura que dá limites, ferramentas e contexto para que essa inteligência produza resultados úteis, previsíveis e seguros em um ambiente de produção.

Uma frase comum na web: se você não é o modelo, então você é o harness

O Harness

Um harness completo se divide em duas metades complementares:

Guia (feed-forward): Tudo o que direciona o agente antes ou durante a execução. Inclui arquivos de regras e memória (como AGENTS.md ou CLAUDE.md), instruções de arquitetura, skills reutilizáveis e especificações de design.
Sensores (feedback): Mecanismos determinísticos e de verificação que avaliam o resultado depois que o agente atua. Inclui linters, compiladores, executores de testes (unit, integration, end-to-end), hooks do editor e até modelos adicionais no papel de juízes.

Nos fluxos de trabalho atuais de desenvolvimento, o maior gargalo deixou de ser a capacidade bruta do modelo e passou a ser a qualidade do ambiente onde ele opera. Agentes sem um harness bem projetado tendem a falhar por padrões conhecidos:

One-Shot Hero: Tentativa de criar aplicações inteiras de uma vez, estourando a janela de contexto ou deixando funcionalidades pela metade.
Vitória Prematura: Declaração de que uma tarefa foi concluída quando na verdade partes importantes foram esquecidas ou ignoradas.
Degradação de Arquitetura: Duplicação de código, desrespeito aos padrões do projeto e quebra de testes à medida que novas sessões avançam.

Existem dois níveis de harness atuando em conjunto no ciclo de desenvolvimento:

Built-in Harness (Estrito): A ferramenta/ambiente fornecido por terceiros, como Claude Code, Cursor, Codex ou Open Code, responsável pela orquestração base, leitura de arquivos e chamadas no terminal.
User Harness (Customizado): A camada configurada pelo próprio engenheiro de software para aquele projeto específico. Envolve a criação de gates de qualidade, políticas estritas, conexões via protocolo MCP, validação de arquitetura e regras de negócio direcionadas.

Com um harness bem construído, o desenvolvedor deixa de atuar no micro-gerenciamento do código e passa a projetar a infraestrutura e os fluxos de trabalho automatizados que garantem entregas consistentes e seguras.

Outra frase comum na web: se o modelo está gerando código ruim, ajuste o harness, não o código.

Contexto

A forma de desenvolver software utilizando Inteligência Artificial passou por três grandes fases:

Prompt Engineering (2022–2023): As janelas de contexto eram muito pequenas (cerca de 4.000 tokens). O foco era descobrir a estrutura perfeita de instrução para o modelo não errar a resposta.
Context Engineering (2024–2025): As janelas de contexto se expandiram para até 1 milhão de tokens. O desafio mudou: em vez de apenas saber como pedir, tornou-se fundamental saber o que enviar. Como passar todo o repositório estoura o limite de processamento ou polui a atenção da IA, a engenharia focou em selecionar, resumir e carregar o contexto exato para cada tarefa.
Harness Engineering (2026+): Entendeu-se que o modelo por si só é apenas uma força bruta com muita inteligência, mas sem controle prático do ambiente. O harness surge como a infraestrutura ao redor do modelo: um conjunto de regras, ferramentas, sensores determinísticos, limites e orquestração para transformar essa inteligência em entregas úteis e seguras em sistemas de produção.

O Contexto é a informação que alimenta a tomada de decisão da IA. O gerenciamento inadequado do contexto causa as falhas mais comuns em desenvolvimento assistido:

Context Rot (Apodrecimento do Contexto): Encher a janela de contexto com logs longos, tentativas frustradas anteriores ou muitos arquivos irrelevantes degradam a capacidade de raciocínio da IA.
On-Demand Loading (Carregamento Sob Demanda): A boa prática de Harness Engineering dita carregar apenas arquivos leves de índice ou referências dinâmicas, utilizando subagentes ou chamadas específicas para pesquisar o código em janelas isoladas sem poluir o processo principal.

As Camadas de verificação

As camadas de verificação formam o pilar de feedback (sensores) dentro do Harness Engineering. Elas funcionam como filtros e portões de validação (gates) dispostos em esteira, cuja função principal é avaliar criticamente o código gerado pelo agente.

A premissa fundamental dessa abordagem é simples: o agente executor nunca deve julgar a qualidade do próprio trabalho. As camadas de verificação entram justamente para impor travas e checagens objetivas.

Em vez de disparar avaliações pesadas de imediato, um harness eficiente organiza os sensores em uma cascata que vai de checagens determinísticas rápidas a julgamentos probabilísticos mais avançados:

Camada Determinística Base (Análise Estática): é a validação imediata, barata e sem margem para interpretação.

Compilador e Tipagem: Garante que o código compila e que o checador de tipos (Type Checker) não aponta erros.
Linters e Formatação: Verifica convenções, estilos de código e detecta anomalias estáticas.
Varredura de Integridade: Garante que arquivos críticos da arquitetura ou chaves sensíveis não foram alterados ou deletados indevidamente.

Camada Executável (Testes e Suítes Automatizadas): avalia se o comportamento do código satisfaz os requisitos funcionais.

Testes de Unidade e Integração: O harness roda a suíte do repositório para verificar se a funcionalidade passou e se nada do sistema legado foi quebrado (regressão).
Testes End-to-End (E2E): Uso de ferramentas automatizadas (como Playwright) para abrir o navegador, interagir com a interface e provar que o fluxo completo funciona na prática.

Camada de Agentes de Code Review (Revisão Especializada): janelas e processos de subagentes com papéis isolados analisam o diff da alteração por diferentes perspectivas:

Agente de Arquitetura: Analisa se o código viola padrões do projeto (ex.: regras de Clean Architecture ou importações proibidas).
Agente de Segurança: Busca por vulnerabilidades, exposição de dados ou falta de sanitização.
Agente de Regressão e Alucinação: Checa se o agente alterou arquivos irrelevantes à tarefa ou adicionou abstrações desnecessárias.

Camada de Juiz Cognitivo (LLM-as-a-Judge): a etapa final e mais completa para a aprovação.

Juiz Separado: Um modelo de raciocínio avançado ou diferente do executor (por exemplo, usar um modelo mais forte para julgar o resultado de um modelo de implementação) lê a especificação, os critérios de aceite e o diff final.
Nota de Conformidade: O modelo juiz gera um relatório de concorrência e atribui uma nota ou veredito de aprovação/rejeição. Se reprovado, o relatório com as falhas exatas é devolvido ao agente executor para autocorreção.

O fluxo de autocorreção (Looping), quando qualquer uma dessas camadas falha, o harness intervém:

O erro (seja um log de teste que falhou ou um apontamento do linter) é capturado e injetado diretamente na janela de contexto do agente.
O agente recebe a informação exata da falha e ganha uma nova tentativa para corrigir o código.
O código alterado passa novamente por toda a cascata de verificação desde a primeira camada.

Essa abordagem garante que uma alteração só seja considerada "concluída" quando cruza todas as barreiras do harness com aprovação.

Níveis de interação

Human In the Loop

É o estágio inicial onde a maioria dos desenvolvedores e times começa. A IA atua gerando código em rajadas ou via prompts diretos, e o engenheiro atua inspecionando cada linha, diff ou alteração criada pelo agente.

O desenvolvedor precisa revisar manualmente cada trecho gerado para garantir que o modelo não quebrou testes, não alucinou ou não introduziu débitos técnicos no repositório.

Conforme o volume de código gerado por IA cresce, fazer code review manual de cada linha se torna insustentável e interrompe o fluxo de trabalho constantemente.

Human On the Loop

Em vez de inspecionar o resultado gerado linha a linha, o desenvolvedor passa a projetar e manter o harness (a infraestrutura ao redor da IA). O engenheiro define os guias (feed-forward via especificações, regras no AGENTS.md, arquitetura e skills) e implementa os sensores de validação (feedback via compiladores, linters, testes automatizados e agentes juízes).

O humano atua na supervisão do processo de entrega e na construção do ambiente operacional. Se a IA comete um erro, o desenvolvedor não corrige apenas o código pontual; ele ajusta uma regra, cria uma nova skill ou adiciona uma barreira no harness para impedir que a IA repita a falha nas execuções futuras.

Human Out of the Loop

É o nível mais avançado de maturidade agêntica, onde a infraestrutura de validação e o harness são suficientemente robustos para permitir execuções totalmente autônomas.

Os agentes recebem demandas (seja via tickets, PRDs ou eventos do sistema), planejam, implementam e executam suas próprias correções e verificações de forma isolada.

O humano sai do fluxo direto de implementação e atua na governança de alto nível, na definição de metas de produto, na avaliação estratégica de regras de negócio e na auditabilidade do sistema. O aceite de entregas depende de evidências numéricas e relatórios estruturados gerados pelas camadas de verificação e julgamento (LLM-as-a-Judge).

Times que ficam estagnados no nível In the loop costumam enfrentar degradação de código e perda de previsibilidade à medida que tentam criar aplicações maiores. Por outro lado, a migração para On the loop redefine a profissão do engenheiro de software, deslocando o foco para o design de arquitetura, governança e construção.

Processo de implementação

As principais estratégias de implementação e seus pilares operacionais estruturam-se da seguinte forma:

Research → Plan → Implement → Verify (RPIV)

Essa é a estrutura fundamental utilizada para otimizar o uso do contexto e evitar ruídos na janela de execução principal:

Research (Exploração/Pesquisa): O agente utiliza subagentes e ferramentas (como servidores MCP) para ler arquivos, bancos de dados, documentações e chamadas de API. Toda a sujeira e consumo massivo de tokens ficam isolados nesses subagentes, gerando apenas um resumo compacto do ambiente.

Plan (Planejamento Unificado): Em vez de separar exageradamente em especificações burocráticas e arquivos de design separados, o agente consolida os requisitos funcionais e as decisões de arquitetura em um plano de execução claro (uma especificação funcional e técnica combinada).

Implement (Implementação de Alto Desempenho): O agente executor recebe o plano consolidado e ganha liberdade para implementar múltiplos blocos de código de uma só vez ou em paralelo.

Verify (Checagem e Prova): A execução só é considerada encerrada quando cruza barreiras determinísticas e dinâmicas (sensores de qualidade).

Spec Driven Development (SDD)

A estratégia de orientar implementações por especificações dividiu-se em duas abordagens distintas:

Classic Spec Driven: o trabalho é dividido em três etapas rígidas (Spec, Design Doc e Tasks pequenas). O agente executa uma tarefa atômica por vez e obriga o rodar de um teste após cada pequena alteração. Ideal para modelos de capacidade intermediária ou mais baratos (como o Composer ou modelos locais/open source) que precisam de Human in the loop para não saltar etapas. É um processo lento, caro em termos de tempo e que exige microgerenciamento do modelo.

Lean / Plan-Based Spec Driven: funciona em modelos avançados de raciocínio alto (como Grok, Claude Sonnet ou Opus), a burocracia do microgerenciamento de tarefas diminui. O agente recebe o plano geral (Spec + Design no mesmo arquivo) e um checklist de critérios de aceite. Ele faz as implementações necessárias de forma contínua ou paralela e, ao final, roda uma suíte rígida de verificação para demonstrar que tudo está passando. Esse processo aumenta exponencialmente a velocidade de entrega, consome menos janelas de contexto ativas do desenvolvedor e aproveita ao máximo a capacidade nativa de raciocínio dos modelos.

Tentar rodar grandes implementações dentro de um único chat estoura a janela de contexto ou degrada o raciocínio do modelo (Context Rot). As estratégias modernas aplicam dois padrões de isolamento:

Isolamento de Janela por Subagentes: O agente principal atua como orquestrador. Ele abre janelas isoladas de subagentes para executar pesquisas e tarefas específicas (ex.: quatro subagentes criando repositórios, serviços e componentes em paralelo) e recebe de volta apenas o status final de conclusão.

Isolamento de Ambiente via Git Worktrees / Sandboxes: Para impedir que o agente altere a branch principal ou cause conflitos de arquivos enquanto trabalha, o harness cria ambientes de execução temporários (como Git Worktrees ou Sandboxes). Cada tarefa roda em seu próprio ambiente e só é unificada ao projeto principal após a validação completa dos sensores.

Em vez de confiar em prompts informais ("construa uma API de fornecedores"), a implementação por harness adota contratos claros e checklists de verificação:

Contratos Estritos: Definem o formato das respostas, estruturas de dados de entrada/saída e dependências obrigatórias antes da escrita de qualquer linha de código.

Checklist Baseado em Comportamento: O plano de execução extrai uma lista de verificação (ex.: GET /suppliers em tabela vazia deve responder 200 com array vazio). O agente executor ou o agente validador precisa executar os testes automatizados correspondentes a cada item do checklist para provar que a tarefa foi finalizada com sucesso.

Flywheel de melhoria

O Flywheel de melhoria é onde a própria infraestrutura em volta do modelo aprende e evolui a partir dos seus próprios erros de execução.

Em vez de tratar falhas, testes quebrados ou PRs rejeitados como eventos isolados em que o desenvolvedor simplesmente corrige o código e segue em frente, a abordagem de Flywheel transforma cada erro em um aprendizado sistêmico definitivo.

Captura do Registro de Falha: Sempre que um gate de qualidade reprova um código, uma instrução falha ou um Pull Request é rejeitado, o harness gera um registro detalhado cobrindo o que falhou, o motivo da falha e a correção efetuada.
Análise de Causa Raiz: O time analisa os padrões de erro e faz a pergunta central: "Qual guia, regra ou sensor preventivo poderíamos ter adicionado para evitar que o agente cometesse este erro?".

Formalização no Harness: O aprendizado é convertido diretamente em um artefato do repositório, como uma atualização no AGENTS.md ou CLAUDE.md, uma nova skill especializada, um novo teste de regressão ou uma trava no linter.
Promoção de Memória: Em harnesses autônomos avançados, se um mesmo tipo de falha ocorre mais de uma vez, o sistema gera uma lição cognitiva e a promove automaticamente para a memória compartilhada do time.

A grande vantagem do Flywheel é que a próxima execução do agente será obrigatoriamente melhor que a anterior. Ao fechar o loop entre o feedback dos sensores e a atualização dos guias (feed-forward), o sistema impede que o agente repita o mesmo erro nas sessões futuras.