A saída de um agente deveria ser tratada como saída de compilador? Link para o cabeçalho

Existe uma cena cada vez mais comum no desenvolvimento de software: você entrega uma tarefa para um agente de programação, ele lê arquivos, executa comandos, altera código, roda testes e termina com uma resposta tranquila, organizada, quase executiva.

“Implementei a mudança. Rodei os testes. Está tudo certo.”

A tentação é aceitar aquilo como entrega pronta. Afinal, o agente parece confiante. Ele escreveu bem. Ele parece ter entendido o contexto. E, se você está cansado, atrasado ou apenas feliz por não ter precisado navegar por seis arquivos de configuração, aquela resposta tem cheiro de alívio.

Só que esse é exatamente o ponto perigoso.

A saída de um agente de programação não deveria ser lida como certificado de correção. Ela deveria ser lida de modo mais parecido com a saída de um compilador, de um linter, de uma suíte de testes ou de uma ferramenta de análise estática: um sinal técnico útil, contextual, às vezes muito valioso, mas ainda assim um sinal que precisa ser interpretado.

Um compilador não pede confiança. Ele aponta um arquivo, uma linha, uma regra quebrada, uma severidade e, às vezes, uma sugestão de correção. Um agente deveria aprender com essa humildade operacional.

A resposta boa não é necessariamente a que soa mais humana. É a que deixa trilha revisável, rastreável e reversível.

Essa tese não vem literalmente da documentação de GCC, Clang, Claude Code ou Codex. É uma conclusão editorial a partir de uma cultura técnica já conhecida: ferramentas confiáveis não tentam parecer infalíveis. Elas deixam evidências.

Infográfico conceitual com a frase “Diagnóstico, não oráculo”, mostrando uma saída de agente transformada em evidências técnicas revisáveis.

A resposta confiante que parece pronta demais Link para o cabeçalho

O problema dos agentes não é simplesmente errar. Todo software erra. Compiladores têm bugs, linters têm falsos positivos, testes podem estar mal escritos, humanos revisam mal depois do almoço. Erro não é novidade.

O problema específico dos agentes é que eles conseguem errar com fluência.

Um erro de compilação normalmente chega com cara de erro. Ele é frio, seco, quase antipático. Diz que algo não fecha. Mostra a linha. Reclama de um tipo. Interrompe o build. Ele não tenta parecer convincente.

Já um agente pode produzir uma explicação elegante para uma mudança que não resolveu o problema. Pode dizer que rodou testes sem deixar claro quais testes rodou. Pode afirmar que preservou compatibilidade sem mostrar onde verificou isso. Pode declarar que “a implementação agora cobre o caso X” quando, na prática, cobriu apenas uma interpretação estreita do pedido.

Essa fluência é útil para colaboração, mas ruim para validação. Ela mistura diagnóstico técnico com narrativa. E narrativa, em engenharia, é uma faca bonita demais para ser deixada solta em cima da mesa.

O problema não é o agente errar; é errar com cara de entrega final Link para o cabeçalho

Quando um compilador falha, ninguém diz: “ele parecia tão seguro”. A mensagem pode ser ruim, confusa ou verbosa, mas ela pertence claramente à categoria de diagnóstico. É uma ferramenta dizendo: “olhe aqui”.

Com agentes, a fronteira entre diagnóstico e conclusão fica borrada. O agente não apenas aponta problemas; ele propõe soluções, altera arquivos, interpreta intenção, resume decisões e tenta fechar a conversa com uma resposta final.

Isso cria um risco sutil: a saída do agente passa a ser tratada como o fim do trabalho, quando muitas vezes deveria ser apenas mais uma etapa do trabalho.

A diferença parece pequena, mas muda tudo.

Se a resposta final diz “feito”, a mente humana tende a reduzir a atenção. Se a resposta final diz “hipótese implementada, verificada pelos comandos A e B, com risco restante C”, ela convida revisão. Uma pede confiança. A outra deixa trilha.

E trilha é o que permite engenharia.

Por que “parece plausível” não basta como critério de aceite Link para o cabeçalho

Em software, plausibilidade é barata.

Um diff pode parecer razoável e quebrar um caso de borda. Uma refatoração pode parecer limpa e remover uma compatibilidade antiga. Uma correção pode passar nos testes existentes porque os testes não cobrem o bug real. Uma explicação pode fazer sentido e ainda assim estar baseada em um arquivo errado.

Com agentes, essa plausibilidade fica ainda mais sedutora porque ela vem embalada em linguagem natural. O agente não entrega apenas código; ele entrega uma história sobre o código. E humanos gostam de histórias coerentes.

Mas critério de aceite pede mais do que coerência narrativa. Pede evidência, julgamento técnico e contexto de produto.

O que foi alterado? Onde? Por quê? Qual comportamento esperado foi verificado? Qual comando rodou? Qual teste falhou antes e passou depois? O que não foi testado? Que parte depende de revisão humana? Que decisão é reversível? Que decisão é arriscada?

Sem isso, a resposta do agente é uma aposta bem escrita.

O que compiladores nos ensinaram sobre confiança técnica Link para o cabeçalho

Compiladores são uma das grandes escolas de humildade da programação. Não porque sejam perfeitos, mas porque sua interface com o erro é mais madura do que parece.

Eles não dizem apenas “não gostei”. Eles classificam. Um erro bloqueia a compilação. Um warning indica uma condição suspeita. Uma nota adiciona contexto. Uma sugestão de correção, quando existe, tenta ser pequena, localizada e segura.

A documentação do GCC, por exemplo, separa erros e warnings de forma direta: erros impedem a compilação; warnings indicam condições incomuns que podem apontar problema, mesmo que o programa ainda possa ser compilado. Essa distinção é simples, mas poderosa. Nem todo problema tem a mesma severidade. Nem toda suspeita deve bloquear o fluxo. Nem toda sugestão merece aplicação automática.

Agentes também se beneficiam dessa cultura de severidade.

Hoje, muitas respostas de agentes chegam como um bloco narrativo único: “fiz X, Y e Z”. Mas, em um fluxo de engenharia mais maduro, a saída tenderia a separar melhor o que é fato, hipótese, alteração, verificação, limitação e recomendação.

Erro, warning, nota e sugestão de correção são coisas diferentes Link para o cabeçalho

Imagine que um agente termina uma tarefa e relata quatro coisas:

encontrou uma falha de lógica;
percebeu um possível caso de borda não coberto;
alterou dois arquivos;
sugere adicionar testes em uma área relacionada.

Essas quatro coisas não têm o mesmo peso.

A falha de lógica talvez seja o problema principal. O caso de borda talvez seja um warning. Os arquivos alterados são parte do patch. A sugestão de testes pode ser uma nota. Misturar tudo em um parágrafo elegante reduz a utilidade da resposta.

Compiladores já aprenderam isso há muito tempo. Um diagnóstico bom não é apenas uma mensagem; é uma estrutura de decisão.

Para agentes, essa estrutura poderia ser algo como:

entendimento da tarefa;
arquivos analisados;
alterações feitas;
verificações executadas;
limitações encontradas;
riscos restantes;
próximos passos recomendados.

Não é burocracia. É ergonomia de revisão.

Quando um agente escreve código, ele entra no fluxo mais sensível de um projeto: o repositório. Ele pode alterar comportamento, apagar complexidade acidentalmente, simplificar algo que era feio por bons motivos ou introduzir uma dependência desnecessária. Se a saída final não ajuda a revisar essas decisões, ela está incompleta.

Localização, regra, severidade e contexto importam Link para o cabeçalho

Um bom compilador tenta dizer onde o problema apareceu. Um bom linter aponta a regra violada. Um bom teste mostra expectativa e resultado. Um bom agente tende a fazer algo equivalente.

Não basta dizer “corrigi o bug no fluxo de autenticação”. Isso é pouco.

Melhor seria dizer que a mudança ocorreu em determinado módulo, que a causa provável era uma validação feita antes da normalização dos dados, que o comportamento foi verificado com uma suíte específica e que ainda não houve teste manual no navegador. Mesmo sem virar um relatório gigante, a resposta passa a ter pontos de ancoragem.

Localização permite revisar. Regra permite entender. Severidade permite priorizar. Contexto permite decidir.

Sem esses elementos, o agente vira uma espécie de colega muito produtivo que entrega coisas sem explicar direito onde mexeu. Pode funcionar em uma tarefa pequena. Em uma base real, isso cobra juros.

Um bom diagnóstico reduz ambiguidade, não exige fé Link para o cabeçalho

A melhor saída de ferramenta é aquela que reduz a pergunta “será que isso está certo?” para perguntas menores e verificáveis.

Compiladores fazem isso quando apontam um tipo incompatível. Testes fazem isso quando isolam uma expectativa quebrada. Linters fazem isso quando mostram uma regra específica. Agentes deveriam fazer isso quando terminam uma tarefa.

A saída ideal de um agente não é “confie em mim”. É “aqui está o que eu fiz, aqui está como verifiquei, aqui está o que ainda pode estar errado”.

Essa mudança parece de tom, mas é de arquitetura.

Porque um agente de programação não é apenas um chatbot com acesso ao editor. Ele é uma camada operacional sobre o repositório. Lê estado, escreve estado, executa comandos, interpreta erros, muda plano e produz diffs. Quanto mais autonomia ele tem, mais importante é que sua saída seja auditável.

Onde a analogia funciona para agentes de IA Link para o cabeçalho

A analogia entre agentes e compiladores funciona bem quando falamos de interface de confiança. Não porque agentes sejam compiladores, mas porque a cultura de diagnóstico dos compiladores oferece uma régua útil.

Um compilador analisa e processa código segundo regras formais e, quando algo dá errado, produz diagnósticos. Um agente transforma intenção em ações sobre um ambiente e, quando termina, deveria produzir um diagnóstico do que aconteceu.

Essa é a virada importante: a resposta final do agente não é apenas uma mensagem para o usuário. Ela faz parte do próprio artefato de trabalho.

A saída do agente como diagnóstico operacional Link para o cabeçalho

Um diagnóstico operacional responde a perguntas que importam para continuidade.

O agente entendeu a tarefa como? Quais arquivos leu? Que comandos executou? Que alterações aplicou? Que testes rodou? Que erro encontrou? Que decisão tomou para contornar o erro? Que parte não conseguiu verificar?

Essas informações não são enfeite. Elas permitem que outro humano, outro agente ou você mesmo amanhã consiga reconstruir o caminho.

Isso é rastreabilidade.

A resposta também precisa ser revisável. Ou seja: precisa permitir que alguém compare afirmação e evidência. Se o agente diz que “o build passa”, deve citar o comando executado. Se diz que “não há impacto visual”, deve dizer se conferiu por screenshot, navegador, teste ou apenas inspeção de código. Se diz que “a mudança é pequena”, o diff precisa confirmar.

E precisa ser reversível. Uma boa saída ajuda a desfazer ou ajustar a mudança. Diz quais arquivos foram tocados, qual intenção guiou cada alteração e quais partes são independentes. Se tudo vem misturado em uma grande narrativa, a reversão fica mais difícil.

Diffs, comandos, testes e evidências como parte da resposta Link para o cabeçalho

Um agente que altera código deveria pensar em evidências como parte da entrega.

Não basta produzir diff. É preciso conectar diff a objetivo.

Não basta rodar teste. É preciso conectar teste a risco.

Não basta dizer “não rodei testes”. É preciso explicar o impacto disso.

Isso vale especialmente para agentes que trabalham em modo mais autônomo. A documentação do Claude Code recomenda dar ao agente meios de verificar o próprio trabalho, como testes, screenshots e saídas esperadas. Também recomenda separar exploração, planejamento e implementação. Essa sequência não é ritual; é uma forma de evitar que o agente resolva o problema errado com muita eficiência.

O Codex CLI, por outro lado, documenta explicitamente modos de aprovação. No modo Read-only, ele fica mais consultivo. No modo Auto, pode ler, editar e executar comandos dentro do diretório de trabalho, com limites. No modo Full Access, ganha acesso muito mais amplo e deve ser usado com cautela. A documentação também afirma que o Codex mostra uma transcrição de suas ações, permitindo revisão e rollback pelo fluxo normal de Git.

Essas duas abordagens apontam para a mesma direção por caminhos diferentes: autonomia precisa vir acompanhada de verificação, permissões claras e trilha de ações.

Se o agente apenas “fala bonito”, ele ajuda pouco. Se ele fala, altera, verifica e deixa evidência, ele começa a se comportar como ferramenta de engenharia.

Quando uma sugestão pode virar patch automático Link para o cabeçalho

Compiladores modernos às vezes oferecem sugestões de correção. O Clang chama isso de fix-it hints: pequenas transformações que podem orientar a correção de um problema localizado. Mas há uma ideia importante na documentação interna do Clang: uma correção automática precisa ter alta probabilidade de corresponder à intenção do usuário. Quando isso não é claro, a sugestão deve ser mais cautelosa.

Esse princípio combina muito bem com agentes de programação.

Nem toda sugestão deve virar patch. Nem todo patch deve ser aplicado sem confirmação. Nem toda confirmação deveria autorizar mudanças amplas.

Uma correção localizada, mecânica, coberta por teste e fácil de reverter pode ser aplicada com mais autonomia. Uma mudança arquitetural, uma alteração de comportamento público, uma migração de dados ou uma modificação de segurança exige outro nível de aprovação.

Autonomia não é um botão binário. É uma escala baseada em confiança, escopo e reversibilidade.

Agentes em código real deveriam diferenciar melhor:

“posso corrigir isso diretamente”;
“posso propor um patch pequeno”;
“preciso confirmar a intenção”;
“isso exige decisão humana”;
“não há evidência suficiente para mexer”.

Isso é muito menos cinematográfico do que uma demo de IA construindo um aplicativo inteiro em cinco minutos. Também é muito mais parecido com engenharia real.

Onde a analogia quebra Link para o cabeçalho

A comparação com compiladores é útil, mas tem limite. E é importante marcar esse limite para não criar uma fantasia nova em cima de outra.

Compiladores trabalham sobre regras formais. Eles têm gramáticas, sistemas de tipos, fases de análise e critérios relativamente claros para aceitar ou rejeitar um programa. Agentes trabalham com linguagem natural, contexto parcial, inferência probabilística, histórico de conversa, arquivos lidos, comandos executados e instruções de sistema que muitas vezes o usuário não vê por completo.

Isso muda o tipo de erro.

Um compilador pode apontar uma incompatibilidade de tipo. Um agente pode interpretar errado o objetivo do usuário. Um compilador pode falhar ao otimizar. Um agente pode otimizar a coisa errada. Um compilador normalmente não decide que seria melhor refatorar seu módulo inteiro porque “fica mais limpo”. Um agente pode sugerir isso, com a melhor das intenções e o pior dos impactos.

Compiladores operam sobre regras formais; agentes operam sobre contexto incompleto Link para o cabeçalho

Um agente normalmente não opera com o projeto inteiro em contexto da mesma forma que um compilador opera sobre uma unidade formal de análise. Ele pode ler muitos arquivos, mas ainda trabalha com seleção de contexto. Pode não ver uma decisão histórica. Pode não conhecer uma restrição de produto. Pode não entender que um trecho feio existe para manter compatibilidade com um cliente antigo, uma API ruim ou um bug de navegador que ninguém quer reencontrar.

Esse é um ponto essencial: o agente não erra apenas por falta de inteligência. Ele também erra por falta de contexto.

E contexto, em agentes, é um recurso operacional. Ele enche, envelhece, é podado, resumido, reorganizado. O post recente sobre os problemas do Claude Code mostrou bem isso: a qualidade percebida de um agente não depende apenas do modelo base, mas também de esforço de raciocínio, contexto, cache, system prompt, ferramentas e harness ao redor.

Quando uma dessas camadas muda, o comportamento pode mudar.

Para o usuário, tudo aparece como “a IA piorou”. Por baixo, pode ser uma mudança de default, uma política de cache, uma instrução de sistema, uma perda de histórico ou um caminho de execução específico. Esse é mais um motivo para exigir trilha. Sem rastreabilidade, o diagnóstico vira sensação.

Um agente pode estar errado na intenção, não só na sintaxe Link para o cabeçalho

Compiladores são ótimos para dizer que algo não compila. Eles são menos úteis para dizer se você está resolvendo o problema certo. Agentes entram justamente nesse território ambíguo.

Quando você pede “melhore a performance dessa tela”, o agente precisa inferir o que significa melhorar. Latência? Tamanho do bundle? Tempo de renderização? Consulta ao banco? Percepção visual? Ele pode escolher uma direção plausível e ainda assim errada.

Quando você pede “simplifique esse código”, ele pode remover uma complexidade que parecia acidental, mas era deliberada.

Quando você pede “corrija esse bug”, ele pode tratar o sintoma em vez da causa.

Esse tipo de erro não aparece como erro de sintaxe. Às vezes passa no build. Às vezes passa nos testes. Às vezes parece até uma melhoria.

Por isso a saída do agente precisa registrar entendimento. Antes de listar o que fez, o agente deveria deixar claro qual problema acredita estar resolvendo. Essa parte é revisável. Se o entendimento estiver errado, o trabalho para ali, antes de virar diff.

Parece detalhe, mas evita muito retrabalho.

Linguagem natural aumenta o risco de autoridade falsa Link para o cabeçalho

A linguagem natural é a grande interface dos agentes. Também é a fonte de parte do perigo.

Um warning de compilador não tenta convencer você com tom sereno. Já uma resposta de agente pode soar como uma decisão madura mesmo quando é apenas uma hipótese. Pode usar palavras como “garante”, “resolve”, “preserva”, “sem impacto” e “correto” sem evidência suficiente.

Essas palavras têm peso. Em times apressados, peso vira aceite.

Por isso, uma cultura saudável de agentes deveria preferir linguagem proporcional à evidência. Se testou, diga que testou. Se inferiu, diga que inferiu. Se não verificou, diga que não verificou. Se há risco, diga qual.

A saída madura não é a mais confiante. É a mais honesta sobre o próprio grau de certeza.

Como deveria ser uma boa saída de agente Link para o cabeçalho

Uma boa saída de agente deveria ser estruturada para revisão. Não precisa ser longa por padrão. Não precisa transformar cada tarefa em ata de reunião. Mas precisa conter os elementos certos para que o humano não seja obrigado a confiar no carisma da resposta.

Pense nela como uma mistura de diagnóstico, changelog e relatório de verificação.

O que foi entendido Link para o cabeçalho

Antes de falar da solução, o agente deveria explicitar a interpretação da tarefa.

Isso é especialmente importante em pedidos ambíguos. Se o usuário pede “ajuste o layout mobile”, o agente precisa dizer o que considerou problema: overflow horizontal, espaçamento, quebra de linha, tamanho de botão, contraste, hierarquia visual. Se o usuário pede “corrija o build”, precisa dizer qual falha encontrou e qual causa provável atacou.

Essa etapa não é burocrática. É uma proteção contra eficiência na direção errada.

O agente pode ser rápido para editar. Justamente por isso precisa ser claro antes de editar.

O que foi alterado Link para o cabeçalho

A resposta precisa apontar os arquivos e a natureza das mudanças. Não no nível de “mexi em algumas coisas”, mas no nível necessário para orientar revisão.

O que mudou no comportamento? O que mudou na estrutura? O que foi removido? O que foi mantido de propósito? Houve alteração de API, layout, dependência, configuração, dados ou contrato público?

Em uma revisão humana, essas categorias importam. Uma alteração em CSS local não tem o mesmo risco de uma mudança em autenticação. Uma cópia de texto não tem o mesmo risco de uma migração. Um ajuste em teste não tem o mesmo risco de uma alteração na lógica que o teste deveria validar.

Agentes precisam parar de tratar todas as mudanças como “mudanças”.

O que foi verificado Link para o cabeçalho

Essa é a parte em que a saída do agente mais se aproxima de ferramentas tradicionais.

Se rodou teste, qual? Se rodou build, qual comando? Se verificou visualmente, em qual ambiente? Se validou referência, como? Se comparou saída, com qual expectativa?

Uma afirmação sem verificação pode ser útil, mas precisa ser marcada como tal.

Existe uma diferença enorme entre:

“Está funcionando.”

“Rodei a suíte X; ela passou. Não executei teste manual no navegador.”

A segunda resposta é menos glamourosa e muito mais útil. Ela permite decisão. Talvez o risco seja aceitável. Talvez não. Mas agora o risco está visível.

O que não foi verificado Link para o cabeçalho

Essa parte deveria aparecer com frequência em tarefas não triviais.

Agentes tendem a querer encerrar com uma sensação de completude. Mas engenharia boa também é saber dizer o que ficou fora.

Não foi possível rodar testes por falta de dependência? Diga. A tarefa envolve uma integração externa que não foi chamada? Diga. A mudança visual não foi aberta em mobile? Diga. A correção depende de comportamento de produção? Diga.

Isso não diminui o valor do agente. Pelo contrário: aumenta a confiança na saída.

Ferramentas que escondem incerteza parecem melhores no curto prazo e custam mais caro no longo.

Quais riscos continuam abertos Link para o cabeçalho

Toda mudança tem risco residual. Às vezes pequeno, às vezes enorme. O agente deveria ajudar a nomeá-lo.

Um diff grande pode esconder regressão. Uma correção em fluxo compartilhado pode afetar outros módulos. Uma alteração de prompt pode mudar comportamento em casos não testados. Um ajuste de cache pode criar bug apenas em sessões longas. Um CSS pode resolver mobile e quebrar desktop.

Quando o agente lista riscos, ele não está sendo inseguro. Está sendo útil.

Esse é o tipo de comportamento que separa ferramenta de demo.

O paralelo com vibe coding Link para o cabeçalho

A discussão sobre vibe coding entra aqui com força.

No post anterior sobre o tema , a ideia central era simples: pedir código em linguagem natural não é o problema. O problema é usar código gerado por IA sem entender, revisar ou validar o que foi feito.

Essa distinção continua valendo.

Existe uma versão saudável do desenvolvimento com agentes: você usa linguagem natural para acelerar exploração, automatizar tarefas, gerar alternativas, fazer refatorações mecânicas, escrever testes, investigar erros e reduzir carga cognitiva. Nesse cenário, o dev deixa de ser apenas digitador de sintaxe e passa a atuar como diretor técnico do processo.

Mas existe também a versão perigosa: você descreve uma intenção vaga, aceita o diff porque “parece bom” e só descobre a dívida técnica quando algo quebra.

Esse é o lado ruim do vibe coding: não a vibe, mas a ausência de critério de aceite.

O problema não é pedir em linguagem natural Link para o cabeçalho

Linguagem natural é uma ótima interface para intenção.

Muitas tarefas de programação começam como intenção antes de virarem implementação: “quero que esse fluxo seja mais claro”, “essa tela está lenta”, “esse teste está frágil”, “esse post precisa validar referências”, “esse módulo está difícil de manter”.

Humanos também trabalham assim. Ninguém começa toda tarefa com uma especificação formal perfeita. A diferença é que, em times bons, a intenção vai sendo refinada até virar critério, plano, implementação e verificação.

Agentes podem ajudar muito nesse caminho. Eles podem fazer perguntas, explorar arquivos, propor alternativas, identificar riscos e escrever o primeiro patch. A linguagem natural não é o inimigo.

O inimigo é a aceitação automática.

O problema é aceitar sem revisão Link para o cabeçalho

Vibe coding sem revisão transforma o agente em uma máquina de dívida técnica educada.

Ele entrega rápido. Você aceita rápido. O projeto acumula decisões que ninguém entendeu. Depois, quando algo quebra, a equipe não tem uma linha clara para voltar. O diff existe, mas a razão não. O código está lá, mas a intenção se perdeu. A conversa explica alguma coisa, mas não necessariamente o suficiente.

É por isso que a saída do agente precisa ser revisável, rastreável e reversível.

Revisável para que alguém consiga avaliar a mudança.

Rastreável para que a equipe saiba como a decisão foi tomada.

Reversível para que uma escolha ruim não vire escavação arqueológica.

Sem essas três propriedades, agente vira produtividade aparente. E produtividade aparente é uma das formas mais eficientes de produzir retrabalho.

O dev deixa de ser digitador e vira responsável pelo critério de aceite Link para o cabeçalho

A promessa boa dos agentes não é “ninguém mais precisa saber programar”. Essa é a versão panfletária, boa para vídeo curto e ruim para produção.

A promessa boa é outra: devs podem gastar menos energia com trabalho mecânico e mais energia com intenção, revisão, arquitetura, validação e decisão.

Mas isso exige uma mudança de postura. Se o agente escreve mais código, o humano precisa ficar melhor em avaliar código. Se o agente executa mais tarefas, o humano precisa definir melhor o que conta como tarefa concluída. Se o agente sugere soluções, o humano precisa distinguir sugestão útil de atalho perigoso.

O centro do trabalho se desloca.

Você talvez digite menos. Mas precisa aceitar melhor.

O caso Claude Code e a importância da trilha operacional Link para o cabeçalho

O caso recente do Claude Code é um bom lembrete de que agentes de programação não são apenas modelos com uma interface simpática.

No post anterior sobre os problemas recentes do Claude Code , a tese era justamente essa: a qualidade percebida de um agente depende do sistema ao redor. Modelo importa, claro. Mas também importam harness, system prompt, contexto, cache, esforço de raciocínio, ferramentas, permissões, avaliações e comunicação com usuários.

Segundo o postmortem da Anthropic citado naquele texto, os problemas recentes envolveram três mudanças diferentes: uma alteração no esforço de raciocínio padrão, um bug relacionado a cache/contexto em sessões retomadas e uma mudança de system prompt voltada a reduzir verbosidade que acabou afetando qualidade em tarefas de programação.

O ponto aqui não é recontar o episódio. É observar o padrão.

Para o usuário, tudo isso aparece como comportamento do agente. O agente esquece, responde raso, escolhe ferramenta estranha, perde continuidade ou parece menos confiável. Por baixo, a causa pode estar em várias camadas.

Sem trilha, tudo vira sensação.

Modelo, prompt, contexto, cache e ferramentas afetam a qualidade percebida Link para o cabeçalho

Quando um agente erra, é confortável dizer “o modelo falhou”. Às vezes é verdade. Muitas vezes é incompleto.

O modelo pode ser o mesmo, mas o prompt de sistema mudou. O modelo pode ser bom, mas o contexto foi podado no momento errado. O raciocínio pode estar limitado por um default mais econômico. A ferramenta pode ter retornado uma saída truncada. O ambiente pode estar em um estado diferente do esperado. O teste pode não cobrir o comportamento real.

Isso torna agentes mais parecidos com sistemas operacionais do que com caixas mágicas.

Eles têm camadas. E camadas falham de formas diferentes.

Por isso, a saída final precisa deixar sinais sobre essas camadas. Quais comandos foram executados? Qual contexto foi usado? Que arquivos foram lidos? Que validações passaram? Onde houve suposição? O agente mudou algo ou apenas propôs? Houve limitação de ambiente?

Essas perguntas não eliminam erro. Elas tornam o erro diagnosticável.

Sem rastreabilidade, toda falha vira “a IA piorou” Link para o cabeçalho

Quando não há rastreabilidade, a conversa fica pobre.

O usuário acha que a IA ficou burra. O fornecedor acha que o usuário está comparando casos diferentes. A equipe acha que a ferramenta não é confiável. Ninguém sabe se o problema foi prompt, contexto, modelo, teste, ambiente, instrução, cache ou expectativa.

Essa confusão não é só irritante. Ela impede melhoria.

Em engenharia, melhorar exige comparar. Comparar exige registrar. Registrar exige trilha.

O mesmo vale dentro de um repositório. Se um agente faz uma mudança e não deixa claro o motivo, a próxima pessoa que mexer naquele código terá menos contexto do que deveria. Se um agente altera algo e não diz o que verificou, a revisão começa no escuro. Se um agente falha e não mostra por onde passou, a correção vira tentativa e erro.

A saída do agente é parte do sistema de observabilidade do trabalho.

Logs e checkpoints são parte da confiança Link para o cabeçalho

Confiança em agentes não deveria vir de personalidade. Deveria vir de checkpoints.

Um checkpoint pode ser um teste passando. Pode ser um build. Pode ser uma revisão visual. Pode ser uma lista de arquivos alterados. Pode ser um resumo de decisão. Pode ser um diff pequeno. Pode ser uma confirmação humana antes de uma ação destrutiva. Pode ser um modo de aprovação que separa leitura, escrita e execução.

Nada disso parece tão impressionante quanto “o agente fez tudo sozinho”.

Mas é assim que software confiável é construído: com limites, registros e validação.

A autonomia boa não é ausência de freio. É freio bem colocado.

Uma régua prática para usar agentes em código real Link para o cabeçalho

Se aceitarmos que a saída de agentes deve ser tratada como diagnóstico técnico, algumas regras práticas aparecem.

A primeira: saída sem teste é rascunho.

Isso não significa que toda tarefa exige uma suíte gigantesca. Um ajuste de texto talvez não precise. Um post de blog pode precisar de build Hugo e revisão visual. Uma mudança em lógica de negócio precisa de testes mais sérios. O ponto é que a resposta deve dizer qual validação corresponde ao risco da mudança.

Sem validação, o estado correto da entrega tende a ser “proposto”, não “pronto”.

Saída sem teste é rascunho Link para o cabeçalho

Um agente que não verificou o próprio trabalho pode ainda ter feito algo útil. Mas a utilidade está em outro estágio.

Ele gerou uma hipótese. Produziu um patch candidato. Fez uma exploração. Escreveu uma primeira versão. Isso é ótimo.

O erro é chamar isso de concluído.

Essa distinção reduz ansiedade e melhora o fluxo. O agente não precisa acertar tudo de primeira se o processo espera iteração. Mas, para iterar bem, o estado do trabalho precisa ser nomeado corretamente.

Rascunho é rascunho. Patch verificado é patch verificado. Entrega pronta é outra conversa.

Diff grande exige desconfiança proporcional Link para o cabeçalho

Quanto maior o diff, maior a necessidade de explicação.

Não porque diff grande seja sempre ruim. Às vezes uma mudança ampla é necessária. Mas um diff grande aumenta a superfície de erro, dificulta revisão e cria mais chances de comportamento colateral.

Agentes podem resolver problemas pequenos com reorganizações grandes quando não há instruções claras. Podem criar abstrações cedo demais, mexer em arquivos relacionados por entusiasmo ou “melhorar” partes que ninguém pediu.

Em código real, isso precisa ser contido.

Uma boa saída de agente deveria justificar diffs grandes. Por que tantos arquivos? Quais mudanças são essenciais? Quais são mecânicas? Quais poderiam ser separadas? O que ficou fora?

Se a resposta não consegue explicar o tamanho do diff, talvez o diff esteja grande demais.

Afirmação sem fonte ou comando precisa ser marcada como hipótese Link para o cabeçalho

Agentes são bons em explicar. Às vezes bons demais.

Quando um agente afirma algo sobre uma biblioteca, uma API, uma regra de negócio ou um comportamento de ferramenta, a pergunta natural deve ser: de onde veio essa informação?

Se veio de documentação lida, cite. Se veio de teste executado, mostre o comando. Se veio de inspeção do código, aponte o arquivo. Se veio de inferência, diga que é inferência.

Isso vale para pesquisa e vale para código.

A diferença entre fato e hipótese precisa aparecer na saída. Caso contrário, tudo recebe o mesmo tom de certeza. E quando tudo parece certo, nada é realmente verificável.

Autonomia deve crescer junto com verificabilidade Link para o cabeçalho

A regra mais importante talvez seja esta: quanto mais autonomia você dá ao agente, mais forte precisa ser a verificação.

Se o agente apenas responde uma pergunta, o risco é baixo. Se propõe um diff, o risco sobe. Se edita arquivos, sobe mais. Se executa comandos, maior ainda. Se publica, remove, migra, altera dados ou mexe em histórico Git, o risco muda de categoria.

Não faz sentido aumentar autonomia sem aumentar rastreabilidade.

Aqui vale distinguir as ferramentas. O Codex CLI documenta modos de aprovação e uma transcrição de ações que pode ser revisada junto ao fluxo normal de Git. O Claude Code documenta práticas de uso como fornecer critérios de verificação, usar testes ou screenshots quando fizer sentido e separar exploração, planejamento e implementação. São capacidades e recomendações diferentes, mas ambas reforçam a mesma tese operacional: agentes não devem ser avaliados apenas por “quanto conseguem fazer sozinhos”, mas por quão bem conseguem deixar o trabalho auditável.

Um agente que pede confirmação na hora certa não é menos capaz. É mais confiável.

Infográfico em três etapas mostrando a saída de agente como diagnóstico técnico: narrativa, evidência e aceite.

Conclusão: não trate agente como oráculo; trate como ferramenta de diagnóstico avançada Link para o cabeçalho

A saída de um agente deveria ocupar um lugar mais técnico e menos místico no nosso fluxo de trabalho.

Não é profecia. Não é sentença. Não é garantia. Também não é lixo só porque pode errar.

É um diagnóstico avançado produzido por um sistema probabilístico com acesso a ferramentas, contexto e capacidade de ação. Isso é poderoso. Justamente por ser poderoso, precisa ser tratado com disciplina.

A boa pergunta não é apenas “o agente acertou?”. Essa pergunta vem tarde demais.

As boas perguntas são:

O agente entendeu o problema certo? Deixou claro o que mudou? Mostrou evidências? Separou hipótese de fato? Rodou validações proporcionais ao risco? Expôs limitações? Tornou a mudança fácil de revisar? Tornou a decisão rastreável? Tornou o caminho reversível?

Esse é o padrão que deveríamos exigir.

O futuro bom dos agentes de programação não é aquele em que eles falam com mais confiança. É aquele em que eles deixam menos trabalho invisível.

Porque, no fim, software não precisa de mais vozes convincentes. Precisa de sistemas que permitam revisar, rastrear e reverter decisões sem transformar cada bug em investigação paranormal.

E se um compilador, com toda a sua frieza, já entendeu isso há décadas, talvez nossos agentes falantes também possam aprender.

Checklist prática: como revisar a saída de um agente Link para o cabeçalho

A resposta deixa claro qual problema o agente entendeu que deveria resolver?
O agente separa fatos, hipóteses, alterações feitas e sugestões futuras?
Os arquivos alterados estão identificados de forma suficiente para revisão?
O tamanho do diff é proporcional ao pedido original?
Mudanças grandes estão justificadas por necessidade real, não por “limpeza” genérica?
A saída informa quais comandos, testes, builds ou verificações foram executados?
Quando não houve teste ou validação, isso está declarado explicitamente?
Afirmações sobre comportamento, API, biblioteca ou regra de negócio apontam para fonte, arquivo, comando ou evidência?
A resposta mostra o que não foi verificado?
Os riscos restantes estão nomeados de forma concreta?
A mudança é reversível sem exigir reconstruir a intenção do zero?
Existe uma trilha clara entre pedido, interpretação, ação, evidência e resultado?
O agente pediu confirmação antes de ações destrutivas, publicações, migrações, alterações amplas ou mudanças difíceis de desfazer?
A saída ajuda um humano a revisar melhor, ou apenas tenta convencê-lo de que está tudo pronto?
Se essa resposta viesse de um compilador, linter ou teste, você aceitaria a severidade e a evidência como suficientes?

Saída de agente: por que ela deveria ser tratada como saída de compilador