Quanto guideline um agente de código precisa?

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do Dev Eficiente. Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Quanta configuração um agente de código realmente precisa para gerar bom código? Essa é a pergunta que eu venho tentando responder na prática, e ela faz parte de uma busca maior: até onde dá para minimizar o ser humano no loop da produção de código a partir de uma necessidade.

Para começar a entender isso, montei um experimento. Peguei o mesmo backlog e pedi para que ele fosse implementado por quatro versões de agente, cada uma com um nível diferente de harness, ou seja, o conjunto de configuração e guideline ao redor do agente. A ideia era simples: será que um agente com pouca configuração gera algo muito diferente de um agente com muita configuração, ou com diferentes granularidades de configuração? Neste post eu mostro o desenho do experimento, os resultados e o que eu concluí até agora.

O contexto: minimizar o humano no loop

A plataforma onde hoje servimos os conteúdos do Dev + Eficiente foi integralmente desenvolvida com apoio de agentes baseados em IA generativa. Tanto o back-end quanto o front-end foram construídos com o Claude Code como principal agente, num trabalho que eu fiz junto com Anderson. Nessa rotina, a pergunta que não para de aparecer é até onde dá para revisar o mínimo possível de código.

Esse tema não é só meu. Se você for ao blog da Anthropic, vai encontrar um post de 24 de março de 2026 chamado "Harness Design for Long-Running Application Development", onde uma engenheira descreve uma configuração que você ouve bastante por aí: um agente planejador, um agente gerador e um agente avaliador, rodando em sessões separadas, com o gerador e o avaliador colocados um contra o outro para maximizar a qualidade gerada. No blog da OpenAI tem um post de 11 de fevereiro de 2026, "Harness Engineering: Leverage Codex in an Agent-First World", contando sobre um app cuja restrição era que todo o código fosse desenvolvido pelo agente. Cada empresa conta a sua história. Foi a partir dessas inspirações, e da minha própria experiência, que tentei montar algo o mais próximo possível de um experimento isolado: mesmo input, configurações diferentes.

O desenho do experimento

Peguei o backlog de um desafio que temos na Jornada Dev + Eficiente: implementar o processo de checkout da Hotmart. São dez tarefas, com níveis de complexidade diferentes. A proposta foi implementar esse backlog de uma vez só, com quatro versões de configuração diferentes:

1. Sem guideline nenhum. Só um prompt inicial de entrada definindo a condição de parada. Nada além disso. É uma implementação baseada unicamente no que o modelo aprendeu no treinamento e no que ele consegue produzir em função do que pedi.

2. Apenas o CLAUDE.md. Extraí um CLAUDE.md da plataforma Dev + Eficiente. Ali estão os guidelines de back-end, os padrões de design, o padrão para testes, o padrão para geração de log e o esquema que eu uso para deixar a geração de log mais sistemática.

3. CLAUDE.md mais uma skill revisora de código. A skill tem categorias de checagem: língua e nomenclatura, padrões de design do domínio, padrões de design das bordas mais externas, como olhar para controllers que lidam com requisições HTTP, como lidar com testes e como olhar para logs.

4. CLAUDE.md mais múltiplos agentes revisores de granularidade ultrafina. Aqui são vários revisores especializados, cada um com um recorte: um revisor que olha a complexidade do código usando o CDD, que enxerga complexidade pelo viés do esforço cognitivo para entender o código; um revisor de controller, com as práticas que eu defendo para essa camada; um revisor de bordas externas, olhando os objetos de transporte; um revisor de design para domínio, linguagem e log; e uma skill orquestradora que conversa com as outras.

Faltou uma quinta versão, que seria fazer tudo de fato em sessões separadas, isolando o contexto e reiniciando a sessão a cada etapa, como descreve o post da Anthropic. Essa fica para um próximo vídeo.

Todas as versões rodaram com o Opus 4.7, no Claude Code. As duas perguntas centrais eram: o design de código produzido teria alguma diferença marcante entre as quatro configurações? E os testes gerados teriam alguma diferença relevante?

Tirando o meu viés: CodeScene

Para avaliar a qualidade do design eu quis tirar o meu viés. Por mais que existam diretrizes de qualidade, eu tenho opinião sobre o que é um código que envelhece melhor, e queria afastar isso da análise. Joguei a avaliação para uma ferramenta especializada em análise de qualidade. Poderia ter usado um SonarQube da vida, mas optei pela CodeScene, cujo criador eu acompanho no LinkedIn e cuja visão eu gosto. Paguei um mês, subi os projetos em repositórios privados no GitHub e pedi para analisar.

Vale lembrar uma limitação importante do experimento: foram dez tarefas, é o início da coisa, um cenário greenfield. Os problemas de código geralmente não aparecem no início. Eles aparecem na continuação, quando o sistema vai envelhecendo, as pessoas que mexem nele vão rotacionando e, nessa rotação, contexto vai se perdendo. As alterações passam a ser feitas sem conseguir levar em conta o máximo de variáveis relevantes. Um experimento ainda mais interessante seria comparar humano contra máquina ao longo do tempo, e isso está por vir.

Resultado 1: o super guideline quase não mexeu no design

A métrica que a CodeScene usa é o Code Health. Os números foram estes:

• Sem guideline nenhum: 9.93
• Apenas CLAUDE.md: 9.93
• CLAUDE.md mais skill revisora: nota menor (a diferença não foi relevante para o Code Health, mas saiu abaixo)
• CLAUDE.md mais agentes revisores ultrafinos: 9.85

Todas as versões saíram saudáveis. E o ponto que mais me chamou atenção: o meu super guideline de código não fez grande diferença na produção, pelo menos nesta primeira leva. A versão sem guideline nenhum empatou com a versão só com CLAUDE.md e ficou acima das versões com os agentes revisores.

Minha hipótese para isso é a seguinte. Esse tipo de ferramenta está olhando para padrões muito bem estabelecidos: nível de acoplamento, tamanho de método, coesão. São temas amplamente discutidos, com bastante material de qualidade, nacional e internacional, espalhado pela internet. O modelo está muito bem treinado nesses padrões. A heurística para tamanho de método, por exemplo, já está consolidada. Quando o assunto é tão consolidado assim, dar um guideline extra não muda tanto o resultado.

A diferença de design que apareceu

A diferença principal de design entre as versões está na forma de tratar o controller. O código gerado sem guideline seguiu o que parece ser a tendência mais comum hoje: o controller como um adaptador, no sentido da arquitetura limpa. Ele recebe o que vem de fora e chama um AccountsService, que supostamente cuida daquele caso de uso e pode ser reaproveitado por diversos adaptadores. O problema é que esse serviço acaba ganhando um monte de métodos auxiliares, e não fica claro de onde cada um é chamado.

No código gerado com o meu guideline, o controller é basicamente o próprio caso de uso. Eu direciono tudo para o controller, que é o entry point principal daquele caso de uso. Para mim, isso funciona bem e diminui o número de arquivos de um jeito que não prejudica. Foi a diferença mais visível, mas, do ponto de vista do Code Health, ela não foi brutal.

Outras práticas que eu defendo num guideline de design apareceram no código guiado, mesmo sem mudar muito a nota:

• Construção de objetos pelo construtor, com as informações obrigatórias, para minimizar a chance de esquecer de definir algo e reduzir a necessidade de classes intermediárias como builders.
• Evitar retorno nulo. Em Java não há um tratamento de nulo tão interessante quanto o de outras linguagens, então eu prefiro Optional quando existe possibilidade de retorno vazio. O Optional não garante nada, mas coloca uma guarda a mais: a semântica dele diz que eu deveria checar antes de usar.
• Logs sistemáticos, com registro antes e depois de alterar o estado.

São práticas que, para uma equipe, fariam diferença. Mas a pergunta que fica é: dado que o treinamento do modelo não muda de forma bizarra de uma versão para outra para práticas tão consolidadas, eu preciso me preocupar tanto com isso a médio prazo? Talvez o design do código caminhe para algo mais parecido com código compilado: ninguém se preocupa com como o Java é compilado para rodar na máquina virtual, porque as heurísticas de otimização já são muito boas. Pode ser que parte do design de código vá pelo mesmo caminho.

Resultado 2: a diferença real está nos testes

Aqui o experimento ficou mais interessante. No código gerado sem guideline nenhum, os testes vieram com poucas assertions. Pega um teste de fluxo de checkout: a resposta traz o e-mail do cliente, o valor total, o número de parcelas, o status da compra. O teste chamava o método de checkout passando a request e verificava apenas se o valor estava em 80. Não verificava se a compra rolou com uma parcela só, não verificava se a oferta certa foi aplicada. Em outro caso, verificava só que o status falhou, sem checar se falhou com as informações corretas. Uma compra pode falhar por diversos motivos. Um teste com poucas assertions é um sinal de teste mais frágil, que mais facilmente encobre um bug no código.

Já o código gerado com o meu guideline levou os testes todos para integração: subir o servidor, tocar o sistema a partir da entrada normal, aproximar a execução do teste da realidade. Esse é o tipo de teste que eu costumo priorizar, em vez de partir direto para testes de unidade com muito mock. O fluxo era exercitado de verdade, com @SpringBootTest.

Por que o agente sem guideline gera testes piores? A minha explicação é simples: a qualidade dos testes que as pessoas escrevem por aí é pior do que a qualidade do código que elas escrevem. Logo, o modelo está pior treinado para testes, e o output padrão dele para testes é pior. Tão direto quanto isso.

Minimalismo: dar a instrução suficiente

Esse experimento me manteve em uma linha que minha experiência já vinha apontando. Eu uso agentes em múltiplos contextos diferentes, e uma coisa se mantém: não é sobre tentar dar muita instrução e configurar exaustivamente, é sobre dar a instrução suficiente. Isso está mais perto de uma postura minimalista do que de espalhar a configuração por vários arquivos.

No post da OpenAI, dá para ver o tanto de arquivos que eles mantêm para o harness: um tracker, um arquivo de core beliefs, um índice que aponta para os outros, as specs, e referências separadas em arquivos de design, front-end, product center, quality score, reliability, security. É uma divisão super fina. O post da Anthropic, que é mais recente, já não tem essa fragmentação toda. Estou usando como referência justamente as empresas que criam as ferramentas que a gente usa, e a leitura que faço é que o caminho minimalista vem se sustentando. O modelo está ficando cada vez melhor nas inferências, e o próprio agente em questão(Claude Code, Codex etc) já tenta montar parte do harness para você nos seus arquivos internos.

O que ainda está em aberto

Eu continuo em dúvida sobre quanto de harness preciso construir para ter, de forma recorrente, um output interessante o suficiente para minimizar o meu esforço de revisão, ou até para, em algum momento, decidir não revisar mais.

Tem uma reflexão que vale a pena. Quando recebemos uma especificação muito bem descrita, a gente escreve teste em boa parte para ganhar confiabilidade e ter rede contra regressão. Eu não botaria a mão no fogo que codaria uma task complexa sem nenhum bug. Mas talvez a taxa de erro de um agente para uma tarefa muito bem definida seja menor do que a minha. Se a taxa de erro de partida já é menor, talvez o teste possa ser um pouco menos robusto, porque o código já chega mais confiável. Isso não é uma conclusão, é uma hipótese que precisa ser testada. Senão fica fácil continuar sentado sobre as nossas crenças e nunca experimentar nada diferente para ver onde quebra.

O próximo passo que pretendo fazer é gerar feature requests para esses mesmos sistemas durante algumas semanas, colocando as quatro configurações para implementar cada uma do seu jeito, e acompanhar como a coisa evolui. Outra possibilidade é montar um experimento de pesquisa de verdade: pessoas implementando com o agente, agentes super autônomos implementando, e comparar primeiro a corretude e depois a qualidade do resultado.

Conclusão

Pelo menos nesta primeira leva, mais guideline não melhorou o design do código de forma relevante. Para padrões muito consolidados, o modelo já chega bem treinado, e a configuração extra rende pouco. A diferença que realmente apareceu foi nos testes: sem guideline, eles vieram frágeis, com poucas assertions; com guideline, vieram como testes de integração exercitando o sistema de verdade. Isso reforça a importância de direcionar o agente justamente onde o output padrão dele é mais fraco.

A minha aposta, por enquanto, segue minimalista: dar a instrução suficiente, em vez de espalhar configuração por muitos arquivos. Mas é só uma fotografia de um experimento inicial, em cenário greenfield. O que importa é continuar experimentando no seu próprio contexto para descobrir onde o agente acerta sozinho e onde ele precisa de direção.

Dev + Eficiente

Desenvolva software de alta qualidade e domine Engenharia de IA com o Dev + Eficiente. Cursos práticos, acesso vitalício, comunidade ativa e acesso a vagas remotas exclusivas em diversas empresas de tecnologia. Sua jornada para se tornar um dev mais eficiente pode começar agora.