Como dar ao seu agente de programação com IA um ciclo de feedback que pega os próprios bugs

Quando um agente de programação com IA escreve um código que parece correto mas quebra algo silenciosamente, o problema normalmente não é o modelo — é que o agente nunca viu a falha. Ele escreveu a mudança, declarou vitória e seguiu em frente, porque nada lhe disse que a suíte de testes agora estava vermelha. A solução é fechar o ciclo: fazer com que as próprias ferramentas do agente reportem de volta para ele automaticamente.

Este guia mostra como construir esse ciclo de feedback para que seu agente pegue os próprios erros antes de você.

A ideia central: os erros devem fluir de volta para o contexto

Um fluxo de trabalho de agente confiável tem quatro etapas — explorar, planejar, construir, verificar. A maioria das pessoas para em "construir". A etapa de verificação é o que separa um agente que produz código funcional de um que produz código com aparência plausível.

Verificar significa rodar checagens reais após cada mudança — seu executor de testes, linter e verificador de tipos — e alimentar a saída de volta ao agente. Quando uma checagem falha, a mensagem de erro chega ao contexto do agente, e o modelo a trata como qualquer outra instrução: lê a falha e a corrige. Sem humano no ciclo para os ciclos de ida e volta tediosos.

Você pode fazer isso de duas maneiras: pedir nas instruções do seu projeto, ou automatizar para que não possa ser pulado.

Opção 1: Apenas peça, na configuração do seu projeto

A versão de menor esforço é uma linha no seu CLAUDE.md ou AGENTS.md (o arquivo de instruções em texto puro que a maioria dos agentes lê na inicialização):

## Verification
After any code change, run `npm run typecheck && npm test`.
If either fails, fix the cause and re-run before reporting done.

Isso funciona surpreendentemente bem — mas é apenas recomendatório. Um agente ocupado pode esquecer, ou decidir que uma mudança é "pequena demais" para verificar. Para qualquer coisa com que você se importe, torne a verificação determinística.

Opção 2: Automatize com um hook

Os hooks do Claude Code permitem rodar um comando de shell em resposta a eventos do ciclo de vida, independentemente de o modelo lembrar ou não. O relevante aqui é o PostToolUse, que dispara depois que o agente edita um arquivo. Como coloca um guia prático sobre hooks, o PostToolUse foi feito para reações — formatar, registrar logs, rodar testes — e sua saída é injetada de volta no contexto do agente para influenciar seu próximo passo.

Aqui está um hook mínimo que roda seu verificador de tipos após qualquer edição de arquivo e devolve as falhas ao agente. Em .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run typecheck"
          }
        ]
      }
    ]
  }
}

Agora o ciclo é automático: o agente escreve código → o hook roda tsc → se houver um erro de tipo, a mensagem flui de volta como contexto → o agente corrige → o hook roda de novo. A referência de hooks documenta como o código de saída diferente de zero e a saída são expostos ao modelo. Esse ciclo roda a cada escrita, sem nenhum aviso.

Mantenha o ciclo rápido e bem delimitado

Um ciclo de feedback só ajuda se for rápido. Algumas regras práticas:

• Rode as checagens baratas a cada edição, e as caras com menos frequência. Uma verificação de tipos ou um linter no arquivo alterado é rápido. Uma suíte completa de integração não é — coloque-a atrás de um hook Stop (quando o agente conclui um turno) ou de um comando manual, não a cada tecla.
• Delimite ao que mudou. Rodar sua suíte de testes inteira após um ajuste de uma linha em CSS desperdiça tempo e inunda o contexto. Onde sua ferramenta permitir, mire nos arquivos afetados.
• Torne as falhas legíveis. O agente só corrige aquilo que consegue ler. Linters e verificadores de tipos com mensagens de erro claras e localizadas (file:line: message) dão ao modelo exatamente o que ele precisa; um genérico "build failed" não.

Um antes-e-depois concreto

Sem um ciclo: você pede ao agente para renomear uma função. Ele atualiza três pontos de chamada, perde um quarto em um arquivo que não abriu, e reporta que terminou. Você descobre o import quebrado em tempo de execução uma hora depois.

Com o ciclo: a mesma renomeação dispara o typecheck ao salvar. O tsc reporta Cannot find name 'oldFn' no ponto de chamada perdido. Esse erro chega ao contexto, o agente abre o quarto arquivo, corrige a referência, e a próxima checagem passa — tudo antes de ele dizer a você que terminou.

A lição

Agentes de IA são bons em produzir código e ruins em perceber quando ele está errado. Você fecha essa lacuna dando a eles o mesmo sinal de que você depende: um teste vermelho, um erro de tipo, uma regra de lint falhando — entregue automaticamente, logo após a mudança. Comece com uma linha nas instruções do seu projeto e, depois, promova sua checagem mais importante a um hook, para que ela rode quer o modelo lembre, quer não. Os agentes que parecem "inteligentes" geralmente são só aqueles conectados a um ciclo de feedback bem ajustado.