Harness para agentes de código é a camada que impede Claude Code, Codex ou outro agente de transformar uma boa intenção em pull request quebrado. Ele define entrada, contexto, ferramentas, testes, revisão e critério de saída. A resposta curta é simples: agente só abre PR depois que a evidência técnica passa.
Em 2025, o Stack Overflow Developer Survey 2025, seção AI, informou que 84% das pessoas respondentes usam ou planejam usar IA no processo de desenvolvimento, contra 76% no ano anterior (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-06-30). O número explica a urgência. A prática, porém, precisa sair do prompt solto.
Harness para agentes de código é um conjunto pequeno de regras e verificações ao redor do agente. Ele não substitui arquitetura, revisão humana ou CI. Ele reduz ambiguidade para que o agente trabalhe como um executor verificável, não como um colega imaginário que parece confiante.
Este post parte de uma observação prática: times não sofrem apenas porque a IA erra código. Sofrem porque o erro chega tarde, misturado a um diff grande, sem teste claro e com contexto demais para revisar rápido.
Versões deste artigo: inglês e espanhol. Para contexto de autoria, consulte a página sobre. Para pauta, correção ou parceria editorial, use a página de contato.
TL;DR prático
- Se 84% dos devs já usam ou planejam IA, o diferencial não é usar agente. É verificar saída.
- Um harness bom começa com spec curta, contexto mínimo, teste reproduzível e regra de PR.
- Subagentes e MCP ajudam quando reduzem ruído; quando aumentam superfície sem prova, atrapalham.
O que é um harness para agentes de código?
Em 2025, o Stack Overflow Developer Survey 2025, seção AI, registrou 84% de uso ou intenção de uso de IA no desenvolvimento (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-06-30). Um harness é a resposta operacional a esse volume: ele transforma o agente em um fluxo com entrada, ferramentas e saída auditáveis.
Na prática, pense em cinco blocos. Primeiro vem a spec: uma descrição curta do comportamento esperado e do que está fora do escopo. Depois vem o contexto: arquivos, contratos, logs e decisões anteriores que realmente importam. Em seguida vem a execução do agente, com permissões compatíveis com o risco da tarefa.
O quarto bloco é verificação. Aqui entram teste unitário, teste de integração, lint, typecheck, migração local ou qualquer comando que represente qualidade no repositório. O quinto bloco é decisão: abrir PR, voltar ao loop ou pedir revisão humana antes de mexer em mais código.
Um harness para agentes de código é útil porque separa hipótese de evidência. O agente pode propor uma mudança, mas o CI, os testes e a revisão automatizada dizem se a mudança merece chegar ao pull request. Essa diferença evita diffs grandes que parecem produtivos e quebram na primeira execução limpa.
Em síntese, um harness para agentes de código é uma fronteira entre geração e entrega. O Stack Overflow registrou 84% de uso ou intenção de uso de IA no desenvolvimento em 2025 (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-06-30), mas adoção não equivale a qualidade. A função do harness é exigir que cada mudança passe por spec curta, contexto explícito, comandos reproduzíveis e uma decisão de PR que possa ser auditada por outra pessoa depois. Se o agente não consegue explicar quais arquivos leu, quais testes executou e por que o diff ficou naquele tamanho, ele ainda não terminou a tarefa. Esse ponto é especialmente importante em repositórios com filas, migrações e contratos entre serviços, onde uma correção local pode quebrar consumo assíncrono.
Quando usar subagentes no agentic coding?
Em 2025, o mesmo levantamento apontou que 51% dos desenvolvedores profissionais usam ferramentas de IA diariamente (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-06-30). Subagentes fazem sentido quando esse uso diário começa a poluir a conversa principal com logs, buscas, arquivos longos ou revisões paralelas.
A documentação de Claude Code descreve subagentes como assistentes especializados que rodam em janelas de contexto próprias, com prompt, ferramentas e permissões específicas (Anthropic, Create custom subagents, acesso em 2026-06-30). O benefício técnico é simples: a conversa principal recebe síntese, não despejo.
Use subagente para exploração de codebase, leitura de logs, revisão de diff e checagem de testes. Não use subagente para multiplicar tentativa cega. Se três agentes escrevem código ao mesmo tempo sem spec comum, você ganha concorrência aparente e perde rastreabilidade.
Em fluxos longos, a economia real vem de não carregar tudo para a mesma janela. Quando o agente precisa atravessar repositórios grandes, um recurso como RemoteCode para estender Claude Code e Codex em fluxos agentic pode ajudar a levar o trabalho mais longe com menos desperdício de contexto, desde que o harness continue decidindo o que passa.
Em síntese, subagente é ferramenta de isolamento, não de terceirização irrestrita. A documentação de Claude Code diz que subagentes rodam em janelas de contexto próprias, com permissões e ferramentas específicas (Anthropic, Create custom subagents, acesso em 2026-06-30). Isso ajuda quando a tarefa paralela devolve uma conclusão curta, como arquivos relevantes, risco do diff ou causa provável de uma falha. O agente principal deve receber decisão, evidência e próximos passos, não todos os caminhos explorados. Se o retorno é um bloco longo de logs, o harness falhou e o contexto foi apenas transferido de lugar. Para fan-out funcionar, cada subagente precisa ter pergunta estreita, limite de ferramentas, formato de resposta previamente definido e dono claro da decisão final.
Como escolher contexto antes do agente escrever código?
Em 2025, a pesquisa do Stack Overflow mostrou 47,1% de uso diário de IA entre todos os respondentes e 17,7% de uso semanal (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-06-30). Esse hábito frequente torna o contexto o gargalo: mandar o repositório inteiro parece seguro, mas costuma gerar ruído.
Comece com uma lista curta. Inclua a issue ou spec, os arquivos prováveis, contratos de API, testes próximos, comandos de validação e decisões arquiteturais que não estão óbvias no código. Exclua histórico irrelevante, logs repetidos, arquivos gerados e documentação antiga sem relação com a mudança.
Uma boa regra é pedir ao agente um plano de contexto antes da implementação. Ele deve dizer quais arquivos vai ler e por quê. Se a lista parece grande demais, peça redução. Se falta um contrato crítico, acrescente antes do código. Context engineering é triagem, não acúmulo.
Depois da primeira leitura, congele o escopo. Mudança de escopo durante a execução deve voltar para a spec. Isso parece burocrático, mas evita o padrão clássico do agente: resolver a tarefa, descobrir um problema vizinho, editar mais três módulos e entregar um PR difícil de revisar.
Onde MCP entra sem virar risco?
Em 2025, 13,7% dos respondentes do Stack Overflow disseram usar IA mensalmente ou de forma infrequente, enquanto 5,3% ainda não usavam, mas planejavam usar em breve (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-06-30). Para esses times em transição, MCP deve entrar por necessidade, não por moda.
O Model Context Protocol é um padrão aberto para conectar aplicações de IA a sistemas externos, como arquivos, bancos, ferramentas e fluxos de trabalho (Model Context Protocol, What is MCP?, acesso em 2026-06-30). Em Claude Code, MCP permite conectar ferramentas, bancos, APIs, issues e painéis de observabilidade (Anthropic, Connect Claude Code to tools via MCP, acesso em 2026-06-30).
Use MCP quando o agente precisa buscar uma issue, consultar um banco de teste, ler um erro no Sentry ou abrir um pull request. Não conecte ferramentas só porque existem. Cada servidor aumenta superfície de permissão, prompt injection e custo cognitivo.
O harness deve registrar três decisões por servidor MCP: qual dado o agente pode ler, qual ação ele pode executar e qual evidência precisa voltar para o PR. Se um servidor só serve para substituir um copiar e colar ocasional, talvez ele não mereça entrar no fluxo ainda.
Em síntese, MCP deve entrar quando reduz atrito verificável entre o agente e sistemas externos. A especificação pública define MCP como padrão aberto para conectar aplicações de IA a ferramentas, dados e fluxos de trabalho (Model Context Protocol, What is MCP?, acesso em 2026-06-30). No harness, isso significa registrar permissões, limitar ações perigosas e exigir evidência no PR. Um servidor para issues pode trazer requisito; um servidor de observabilidade pode trazer erro real; um servidor de banco pode confirmar hipótese em ambiente seguro. Conectar tudo por padrão aumenta risco sem melhorar entrega. O melhor primeiro servidor costuma ser aquele que remove uma cópia manual recorrente e deixa rastro claro no histórico do trabalho, sem ampliar permissão de escrita.
Como montar o loop de spec, TDD e CI?
Em 2025, o uso ou intenção de uso de IA no desenvolvimento chegou a 84%, acima dos 76% do ano anterior (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-06-30). Essa alta muda a pergunta: não é se o agente escreve código, mas qual loop impede que ele escreva sem prova.
O loop mínimo tem seis passos:
- Escreva uma spec de uma tela ou menos, com comportamento esperado e fora de escopo.
- Peça ao agente um plano de arquivos e comandos antes de editar.
- Crie ou ajuste teste primeiro quando a mudança permitir.
- Faça o patch menor que resolve a spec.
- Rode teste, lint e typecheck em ambiente limpo.
- Gere uma revisão automática com bloqueios e riscos residuais.
Essa sequência combina bem com TDD porque o agente recebe uma borda concreta. Se o teste falha antes e passa depois, a conversa muda. O agente deixa de argumentar que a mudança “parece correta” e passa a demonstrar comportamento. Para backend, isso vale para contrato HTTP, fila, migração, idempotência e observabilidade.
Claude Code também oferece hooks para executar comandos em pontos do ciclo de vida, como após edições ou antes de comandos sensíveis (Anthropic, Automate actions with hooks, acesso em 2026-06-30). Use hooks para formatação, bloqueio de arquivos protegidos e validações determinísticas. Julgamento continua com revisão.
Em síntese, o loop de spec, TDD e CI funciona porque cada etapa troca opinião por prova. Em 2025, a adoção ou intenção de uso de IA subiu de 76% para 84% no levantamento do Stack Overflow (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-06-30). Quanto mais comum o agente fica, mais importante é manter comandos reproduzíveis, testes que falham antes do patch e revisão automática que bloqueia risco real. O agente pode ser rápido, mas só o teste mostra comportamento, só o lint mostra consistência e só o CI aproxima a execução do ambiente do time. Em APIs, inclua contrato e compatibilidade; em jobs, inclua idempotência; em banco, inclua migração, rollback e verificação de dados.
Como revisar o PR gerado por IA?
Em 2025, 16,2% dos respondentes do Stack Overflow disseram que não usam IA e não planejam usar no desenvolvimento (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-06-30). Esse grupo lembra algo importante: confiança não é obrigatória. O PR gerado por IA precisa merecer confiança.
A revisão deve começar pelo contrato da spec. O diff resolve exatamente o que foi pedido? O teste prova o caso principal? Há mudança escondida em arquivo sem relação? O agente citou fonte externa ou comportamento de ferramenta sem link? Alguma migração, permissão ou variável de ambiente ficou implícita?
Peça uma revisão automática antes do humano. Ela deve listar bloqueios, riscos e comandos executados. Não aceite review que só elogia. Um bom revisor automático procura falha de contrato, caso de borda, regressão de segurança, mudança de performance e inconsistência entre código e teste.
O melhor sinal de maturidade não é o agente abrir PR sozinho. É o agente saber quando não deve abrir. Se a fonte não foi verificada, o teste não cobre o fluxo ou o diff cresceu além da spec, o resultado correto é voltar ao loop.
Em síntese, revisão de PR gerado por IA deve ser mais objetiva que uma revisão comum, não mais permissiva. O Stack Overflow registrou 16,2% de respondentes que não usam IA e não planejam usar no desenvolvimento (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-06-30). Esse ceticismo é saudável quando vira critério: diff pequeno, teste claro, fonte citada, risco declarado e comandos visíveis. O revisor humano não deve reconstruir a intenção do agente; o PR precisa trazer contexto suficiente para aceitar, pedir ajuste ou fechar sem debate longo. Quando a explicação do PR é vaga, trate isso como falha do harness, mesmo que o código pareça plausível e os testes passem.
Checklist antes de deixar o agente abrir o PR
Em 2025, o Stack Overflow mostrou que 84% das pessoas respondentes já usam ou planejam usar IA no desenvolvimento, mas esse dado não valida qualquer automação (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-06-30). O checklist final precisa ser menor que o processo e mais duro que a intuição.
| Sinal | Como verificar | Ação se falhar |
|---|---|---|
| Spec coberta | Teste ou caso manual descrito | Voltar para spec |
| Contexto suficiente | Arquivos e contratos citados | Reabrir etapa de contexto |
| Testes limpos | Comando registrado no PR | Corrigir antes do PR |
| Lint e tipos limpos | Saída do CI ou comando local | Corrigir antes do PR |
| Review sem bloqueio | Lista de riscos revisada | Pedir revisão humana |
| Fonte citada | Link e data de acesso | Remover ou verificar claim |
Se todos os sinais passam, o agente pode abrir PR com descrição objetiva: problema, abordagem, comandos executados, riscos e próximos passos. Se algum sinal falha, não transforme falha em nota de rodapé. Volte ao loop, reduza o escopo ou chame uma pessoa.
FAQ sobre harness para agentes de código
O que é um harness para agentes de código?
É uma estrutura operacional que cerca o agente com spec, contexto, ferramentas permitidas, testes e regra de saída. Em 2025, 84% dos respondentes do Stack Overflow usavam ou planejavam usar IA no desenvolvimento (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-06-30), então a diferença competitiva está na verificação.
MCP é obrigatório para agentic coding?
Não. MCP é útil quando o agente precisa acessar ferramentas externas com contrato claro. A própria documentação do MCP o define como padrão aberto para conectar IA a sistemas externos (Model Context Protocol, What is MCP?, acesso em 2026-06-30). Para mudanças locais simples, teste e CI bastam.
Subagentes economizam tokens?
Podem economizar contexto quando isolam exploração e devolvem síntese curta. A documentação de Claude Code afirma que subagentes rodam em janelas próprias e ajudam a preservar contexto (Anthropic, Create custom subagents, acesso em 2026-06-30). Se eles devolvem dumps longos, o ganho desaparece.
Codex e Claude Code precisam do mesmo harness?
O desenho muda por ferramenta, mas o princípio é o mesmo. Codex, Claude Code e agentes parecidos precisam de spec, escopo, ferramentas, verificação e revisão. Quando o agente executa comandos e edita arquivos, o harness vira parte do processo de engenharia, não um acessório.
Fontes consultadas
- Stack Overflow, Developer Survey 2025 AI, acesso em 2026-06-30, https://survey.stackoverflow.co/2025/ai
- Anthropic, Create custom subagents, acesso em 2026-06-30, https://code.claude.com/docs/en/sub-agents
- Anthropic, Connect Claude Code to tools via MCP, acesso em 2026-06-30, https://code.claude.com/docs/en/mcp
- Anthropic, Automate actions with hooks, acesso em 2026-06-30, https://code.claude.com/docs/en/hooks-guide
- Model Context Protocol, What is MCP?, acesso em 2026-06-30, https://modelcontextprotocol.io/docs/getting-started/intro
- OpenAI, Introducing Codex, acesso em 2026-06-30, https://openai.com/index/introducing-codex/