Agente de código precisa de orçamento, não só de prompt

Tem uma fase em que usar agente de código parece quase grátis.

Você já paga a assinatura. O botão está ali. A tarefa parece pequena. Então você pede: "corrige esse bug", "faz esse refactor", "cria os testes", "ajusta a tela".

Só que a conta real quase nunca aparece no primeiro prompt.

Ela aparece na terceira tentativa, quando o agente já leu contexto demais e começou a misturar hipóteses. Aparece na fila de capacidade bem na hora em que você queria fechar o PR. Aparece no diff grande demais para revisar com calma. Aparece quando a explicação ficou bonita, mas ninguém salvou a evidência de que o teste certo rodou.

E aí fica uma sensação estranha: a ferramenta era para acelerar, mas você terminou gastando atenção para descobrir se acelerou mesmo.

Para mim, essa é a próxima conversa séria sobre agentes de código. Não é só "qual prompt funciona melhor?". É orçamento operacional.

O custo não é só token

Quando uma ferramenta passa a cobrar por uso, token, crédito ou limite de execução, o custo financeiro fica mais visível. Isso importa, claro. Mas mesmo quando a cobrança está escondida dentro de uma assinatura, o workflow continua gastando outras coisas.

Gasta contexto.

Gasta tempo de espera.

Gasta revisão humana.

Gasta confiança.

Gasta capacidade de retomar uma tarefa depois que o agente falha, trava, muda de rota ou entrega pela metade.

Esse é o ponto que muita gente sente no dia a dia, mas ainda descreve como "o modelo não foi tão bom". Às vezes o modelo até foi bom. O processo em volta é que deixou o loop caro demais.

Um agente de código em repositório real não é autocomplete com mais texto. Ele lê arquivos, propõe plano, altera código, roda comando, interpreta erro, tenta de novo e entrega algum tipo de pacote para você revisar. Cada uma dessas etapas consome orçamento. Se você não define esse orçamento antes, o agente define por você.

Normalmente do jeito mais caro.

Contexto longo também precisa de limite

Existe uma armadilha bem comum: achar que quanto mais contexto o agente receber, menor será o risco.

Às vezes ajuda mesmo. Para entender uma base desconhecida, investigar um fluxo espalhado ou comparar padrões entre módulos, contexto grande é uma bênção.

Mas contexto grande sem recorte vira ruído caro.

O agente lê o README atual, o README antigo, um teste que ninguém atualizou, uma issue que ficou aberta por abandono, um arquivo parecido que usa uma regra diferente, e tenta montar uma resposta coerente a partir desse caldo. O resultado pode compilar e ainda assim nascer torto.

Antes de chamar o agente, vale fazer uma pergunta simples:

Qual é o menor pedaço de repositório que torna essa tarefa justa?

Se a resposta for "o projeto inteiro", talvez a tarefa ainda não esteja pronta para execução. Talvez ela precise virar investigação primeiro. Talvez precise de um plano curto, uma lista de arquivos prováveis, ou um ponto de parada antes de qualquer patch.

Prompt bom ajuda. Escopo bom ajuda mais.

Retry sem ponto de parada vira vício

Outro custo escondido é a tentativa repetida.

O agente errou? Você pede para corrigir.

Ele corrigiu uma parte e quebrou outra? Você pede de novo.

O teste continua falhando? Mais uma rodada.

De repente, a tarefa que parecia simples virou uma conversa longa, com contexto acumulado, suposições antigas e um diff que já não representa uma decisão clara. A cada retry, fica mais difícil saber se o agente está melhorando o resultado ou só remendando em cima do próprio remendo.

Eu gosto de tratar agente como execução com limite, não como conversa infinita.

Algo como:

faça um plano curto antes de editar;
pare se precisar tocar em mais de X arquivos;
rode apenas estes comandos;
se o teste falhar duas vezes, explique o bloqueio em vez de continuar tentando;
no final, diga exatamente o que mudou e qual evidência comprova.

Isso parece burocrático, mas não é. É o equivalente a limitar tamanho de PR. Você não faz isso porque odeia velocidade. Faz porque sabe que revisão humana tem teto.

Capacidade também entra no desenho

Quando agente vira parte do fluxo diário, disponibilidade deixa de ser detalhe.

Se a ferramenta entra em modo de capacidade, fica lenta, perde sessão ou falha no transporte, o trabalho não pode depender da sua memória de curto prazo. Você precisa conseguir retomar.

Retomar significa ter artefatos pequenos:

qual era a tarefa;
quais arquivos estavam no escopo;
que plano foi aprovado;
que comando rodou;
que erro apareceu;
o que ainda falta validar.

Sem isso, qualquer falha vira teatro. Você volta meia hora depois, olha para a tela, tenta lembrar por que aquele arquivo mudou e acaba aceitando uma explicação bonita porque já está cansado.

Agente bom não elimina handoff. Ele aumenta a importância do handoff.

O diff grande é onde a mágica cobra juros

Existe um tipo de entrega de agente que parece impressionante e ao mesmo tempo me dá preguiça na hora: o diff gigante.

Muda código, teste, copy, tipo, configuração, talvez documentação. A explicação vem organizada, com tom confiante. Parece trabalho de alguém muito produtivo.

O problema é que a revisão não fica mais barata só porque quem escreveu foi um modelo.

Se o diff mistura refactor, correção de bug, ajuste visual e mudança de contrato, o humano ainda precisa separar tudo mentalmente. Precisa descobrir o que era necessário, o que foi consequência, o que foi chute e o que virou dívida.

Um jeito prático de reduzir esse custo é pedir entregas em lotes menores:

primeiro investigação, sem patch;
depois mudança mínima;
depois teste;
depois limpeza;
depois documentação, se ainda fizer sentido.

Nem todo trabalho precisa ser quebrado assim. Mas se você não consegue revisar o diff em uma passada honesta, o lote já passou do tamanho.

O orçamento antes do prompt

Antes de abrir o agente, eu tentaria responder estas perguntas:

Qual é a tarefa mínima?
Quais arquivos ele pode tocar?
Qual comando prova que terminou?
Qual é o ponto de parada?
Que evidência precisa ficar no final?
Quem revisa o resultado e com qual critério?

Repara que nenhuma dessas perguntas é sobre "engenharia de prompt" no sentido mágico da coisa. É só engenharia mesmo.

Você está definindo fronteira, validação e entrega.

Para times pequenos, isso muda bastante o jogo. O agente deixa de ser aquele colega rápido que você deixa sair mexendo em tudo e vira uma peça do processo. Ele pode continuar sendo rápido. Só que agora corre dentro de uma raia.

Não esqueça os artefatos de publicação

Tem uma parte que dev costuma lembrar tarde demais: a tarefa não termina quando o código compila.

Se o trabalho vai virar changelog, post técnico, página de lançamento ou material para rede social, os artefatos também entram no orçamento. Texto, imagem, screenshot, tamanho certo, nome de arquivo, link final. Tudo isso parece pequeno até ficar faltando cinco minutos antes de publicar.

Uma imagem para Instagram, por exemplo, pode passar por um recurso browser-local como Resize Image for Instagram para sair no tamanho certo antes de entrar no pacote final. Não é o centro do workflow. É só o tipo de detalhe que precisa estar no checklist se a entrega termina fora do repositório.

Esse é o ponto: orçamento operacional não é só o tempo do agente. É o pacote inteiro chegar revisável, validado e publicável.

Um bom agente recompensa tarefas menores

Eu não acho que a conclusão seja "use menos IA".

Para mim é quase o contrário: se você quer usar agente de código com mais frequência, precisa parar de tratá-lo como um chat sem custo.

O agente recompensa quem prepara bem o loop.

Tarefa menor. Contexto mais limpo. Comando de validação claro. Retry com limite. Diff revisável. Evidência no final. Handoff que outra pessoa consegue entender amanhã.

Isso não tem o glamour de descobrir o prompt perfeito. Mas é o que separa uma ferramenta útil de uma máquina de gerar trabalho disfarçado de produtividade.

No fim, agente de código não precisa só de mais instrução.

Precisa de orçamento.