建立先重現問題再修復 Bug 的 AI 智能體

Agente de IA que Corrige Bugs: Crie um que Reproduza o Problema Primeiro

Um agente de IA que corrige bugs sozinho funciona quando obedece a uma regra: sem reprodução, sem correção. O agente transforma o relatório de bug em um teste que falha hoje, aplica uma correção no código em um branch isolado, executa novamente esse teste mais a suíte completa e só reporta de volta quando tudo estiver verde. O merge continua sendo feito por um humano. Se não conseguir reproduzir o bug, ele fica em silêncio.

Experimente o Apidog hoje

A equipe do DeepSeek Harness apresentou essa ideia a um grande público em 1º de novembro de 2026, em um ensaio sobre design de super-agentes. Este guia a transforma em um pipeline que você pode construir esta semana, com a reprodução escrita como um teste de API que seu agente cria e executa a partir do terminal.

Por que “agente, corrija isso” falha sem uma reprodução

Peça a um agente de codificação que corrija um relatório de bug e você geralmente receberá um diff confiante. Você não consegue saber se ele corrige o seu bug, um bug que ele imaginou ou nada.

Sem uma etapa de reprodução, três coisas dão errado:

• O agente adivinha a causa. Ele escolhe a linha mais provável a partir da mensagem de erro e a edita.
• “Corrigido” não tem definição. A única prova é o resumo do próprio agente.
• Regressões passam despercebidas. Uma alteração em um validador compartilhado pode corrigir um endpoint e quebrar outros quatro.

Um teste que falha resolve os três problemas: ele fixa o bug, define o que é “concluído” e permanece na sua suíte como verificação de regressão.

De onde vem “reproduzir e corrigir em silêncio”

Em "Exploring Super-agent Design", a equipe do DeepSeek Harness descreve uma política do seu próprio grupo de usuários: quando alguém relata um bug, um agente tenta reproduzi-lo em segundo plano. Ele se manifesta apenas com uma correção confirmada e simples. Caso contrário, não diz nada.

O ensaio chama isso de execução especulativa e o associa a dois componentes que você reutilizará aqui. Os workers recebem uma sessão isolada por tarefa, todas as ferramentas e o modelo mais forte, e reportam a um roteador em vez de falar com humanos. Um watchdog é uma sessão separada que verifica se cada worker está progredindo ou se desviando.

Uma ressalva: o ensaio descreve uma arquitetura, não recursos já lançados do DeepSeek Harness. Partes dela vivem em um plugin de protótipo, dsh-superagent-prototype, que, segundo os autores, não é um produto oficial da DeepSeek. Para entender o panorama de roteador e worker, veja como construir um super-agente.

O pipeline de agente de correção de bugs em cinco etapas

Um agente de autocorreção executa o mesmo loop todas as vezes, com dois portões:

1. Recepção: coletar o relatório, a requisição que falha e a resposta recebida.
2. Reproduzir: escrever um teste que falha pelo motivo relatado. Sem teste que falha, sem correção.
3. Corrigir: aplicar a correção no código em um branch ou worktree isolado.
4. Reexecutar: o novo teste deve passar, e a suíte existente também.
5. Entregar: abrir um pull request com as evidências ou ficar em silêncio.

Etapa 1: Receber o relatório de bug

Seu agente não consegue reproduzir “o checkout quebrou de novo”. Dê à recepção um formato fixo:

Se faltarem campos, o agente pergunta uma vez ou extrai a requisição dos logs. Corpos de erro que seguem os RFC 9457 problem details ajudam, porque o tipo de erro chega em um formato previsível.

Etapa 2: Reproduzir o bug como um teste de API que falha

Esta é a porta de entrada. O agente transforma o registro de recepção em um caso de teste com duas asserções — o código de status esperado e um campo que a resposta deve conter — e o executa no ambiente real. Três resultados são possíveis:

• Falha pelo motivo relatado. Você tem uma reprodução. Prossiga.
• Passa. O bug não é reproduzível como descrito. Registre nos logs e pare.
• Falha por outro motivo (erro de autenticação, dados ausentes, timeout). Essa é uma reprodução quebrada, não um bug confirmado. Pare.

Somente o primeiro desbloqueia uma correção. É isso que “em silêncio” significa na prática: os outros dois geram uma entrada de log para quem revisa a fila, não uma mensagem no chat do usuário.

Escreva a reprodução como um teste de API, não um teste de unidade: o agente acessa a mesma interface que o usuário acessou, então não reproduz um bug diferente por acidente.

Etapa 3: Corrigir o código em um branch isolado

Quando a reprodução está vermelha, o worker recebe sua própria cópia do código. Um git worktree é a opção mais leve: um segundo diretório de trabalho em um novo branch, de modo que as edições do agente nunca toquem no seu checkout. Execute o serviço a partir dele e aponte o ambiente de teste para lá.

Mantenha duas restrições rigorosas. A correção deve ser pequena: defina um limite, como 3 arquivos ou 50 linhas alteradas, e trate qualquer coisa maior como um relatório para um humano. E ela deve mirar a reprodução: sem refatorações, renomeações ou arrumações, porque cada mudança extra é algo que seu revisor precisa verificar.

Etapa 4: Reexecutar a reprodução e a suíte completa

O segundo portão tem duas partes. Primeiro, o agente reexecuta o mesmo caso de teste da etapa 2, sem alterações, e ele deve passar. Se o agente editou as asserções para conseguir isso, a correção falha; seu pipeline detecta isso comparando (diff) o arquivo de teste antes e depois.

Segundo, a suíte existente deve continuar verde. Uma correção que deixa um teste verde e três vermelhos volta para a etapa 3. Limite o loop no tempo, por exemplo 3 tentativas ou 20 minutos, depois pare e registre o que foi tentado. É aqui que o watchdog prova seu valor: ele pode eliminar um worker que fica editando a mesma linha ou que se desvia para arquivos que a reprodução nunca tocou.

Etapa 5: Entregar apenas uma correção confirmada e simples

Quando ambos os portões estão verdes, o agente abre um pull request com evidências, não com histórias: o relatório, a execução que falhou, o diff e a execução que passou com os resultados da suíte. Um humano revisa e faz o merge. Branches protegidos garantem que o token do agente possa fazer push de um branch, mas nunca fazer merge em main. Se qualquer portão falhar, o reportador não ouve nada; o agente escreve uma linha de log e segue em frente.

Salvaguardas para um agente de IA que se autocorrige

Configure estas barreiras antes da primeira execução sem supervisão:

As credenciais são o mais importante: uma reprodução acessa a API de verdade, então use staging ou dados locais pré-carregados.

Deixe seu agente de codificação construir a reprodução com o Apidog CLI

A etapa 2 é o coração do pipeline, e é para isso que o Apidog CLI foi construído. Seu agente de codificação (Claude Code, Codex, Cursor ou OpenCode) escreve o caso de teste como JSON, cria-o no seu projeto Apidog e o executa a partir do terminal. Você escreve um único prompt.

Configure uma vez:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Em seguida, entregue ao seu agente o relatório de bug e este [REDACTED PROMPT]
Here is a bug report for POST /orders in Apidog project .
Turn it into an Apidog test case that fails today: assert status 201
and that $.id exists. Run it against staging and confirm it fails for
the reported reason. If it does, fix the handler on a new worktree
branch until the same test passes, run the endpoint's other cases, and
open a PR with both JSON reports. If it doesn't reproduce, stop and log why.

O agente não constrói o payload de memória. Ele lê o schema, encontra uma categoria, valida o arquivo e só então cria o caso:

bash
apidog cli-schema get test-case-create
apidog test-case category --project
apidog cli-schema validate test-case-create --file repro-orders.json
apidog test-case create --project --file repro-orders.json

O arquivo que ele escreve fica assim (os IDs vêm do seu projeto):

json
{
"name": "Repro: POST /orders with null coupon returns 500",
"apiDetailId": 123456,
"categoryId": 1,
"method": "post",
"path": "/orders",
"parameters": {},
"commonParameters": {},
"requestBody": {
"type": "application/json",
"data": "{\"items\":[{\"sku\":\"A-100\",\"qty\":1}],\"coupon\":null}"
},
"postProcessors": [
{ "type": "assertion", "defaultEnable": true, "enable": true,
"data": { "name": "status is 201", "subject": "httpCode", "comparison": "equal", "path": "", "value": "201" } },
{ "type": "assertion", "defaultEnable": true, "enable": true,
"data": { "name": "order id exists", "subject": "responseJson", "comparison": "exists", "path": "$.id" } }
]
}

Agora, a execução vermelha que prova o bug:

bash
apidog run --test-case --project -e -r cli,json --out-file repro-before

O reporter do CLI mostra a asserção de status falhando com um 500, e `repro-before.json` é salvo em `apidog-reports/`. Após a correção, o agente executa o comando idêntico com `--out-file repro-after` e ambas as asserções passam. Esses dois arquivos são as evidências no pull request. Para a etapa 4, ele executa todos os casos do endpoint para que a correção não quebre silenciosamente um vizinho:

bash
apidog test-case run --project --endpoint -e -r cli,json

Adicione `--upload-report` para exibir a execução no app do Apidog. Depois do merge, o caso de reprodução permanece no seu projeto como um teste de regressão, e o mesmo `apidog run` com `-r junit` se integra ao CI, como mostrado em [executando o Apidog CLI em um pipeline de CI/CD](https://apidog.com/pt/blog/apidog-cli-ci-cd-pipeline?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation). Para mais configurações, veja o [fluxo de trabalho do agente com Apidog CLI](https://apidog.com/pt/blog/apidog-cli-agent-workflow?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) e [Apidog CLI no Claude Code](https://apidog.com/pt/blog/apidog-cli-in-claude-code?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation). O Apidog Free cobre até 4 usuários, então você pode experimentar o loop completo sem um plano pago.

## FAQ

### Um agente de IA realmente pode corrigir bugs sem um humano?

Ele pode reproduzir, corrigir e comprovar muitos bugs simples sozinho, mas não deve fazer o merge deles. Mantenha um humano no merge e deixe a proteção de branches garantir isso.

### E se o agente não conseguir reproduzir o bug?

Ele para e registra nos logs o que tentou. Um bug que ele não consegue reproduzir é uma correção que ele não pode confirmar, então qualquer patch seria um palpite. Um humano então adiciona detalhes ao relatório ou o encerra.

### Como impedir o agente de editar o teste para fazê-lo passar?

Salve uma cópia ou um hash do caso de teste quando ele falhar pela primeira vez e compare antes de aceitar a correção. Mantenha o arquivo de teste fora dos caminhos que o worker pode editar.

### Preciso do DeepSeek Harness para construir isso?

Não. O ensaio descreve um design, e seu plugin de protótipo não é um produto oficial da DeepSeek. Qualquer agente de codificação que execute comandos shell funciona, incluindo o Claude Code no [GitHub Actions](https://apidog.com/pt/blog/claude-code-github-actions?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation). Veja [o que é o DeepSeek Harness](https://apidog.com/pt/blog/what-is-deepseek-harness?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) se quiser experimentá-lo lá.