Um agente de IA para triagem de bugs no GitHub deve transformar um relato incompleto em uma investigação reproduzível: identificar a versão afetada, localizar evidências, executar um teste controlado e entregar uma hipótese com limites claros. Quando houver evidência suficiente, pode preparar uma proposta de correção para revisão. A decisão de integrar código continua submetida às regras do repositório.
O melhor ponto de partida é uma fila pequena de defeitos com ambiente de teste disponível. O fluxo abaixo é uma proposta de arquitetura, independente do modelo escolhido. Seu objetivo é melhorar o diagnóstico preliminar antes de existir um pull request, preservando a ligação entre relato, reprodução e alteração sugerida.
Resumo rápido
- Comece pela versão, pelo comportamento esperado e por uma reprodução mínima.
- Consulte comentários e evidências antes de classificar uma issue como duplicada.
- Execute código desconhecido em ambiente isolado, com dados sintéticos.
- Separe fatos observados, hipóteses e verificações ainda pendentes.
- Entregue teste de regressão e proposta de patch somente quando o escopo estiver claro.
1. Defina o contrato de entrada e saída da triagem
A documentação do GitHub apresenta issues como registros para bugs, melhorias e outras solicitações. Também permite referenciar trechos de código ao criar uma issue. Isso oferece um ponto de partida para a investigação, mas o conteúdo recebido ainda precisa ser interpretado. Uma pessoa pode chamar de bug uma configuração incorreta, um pedido de funcionalidade ou uma falha externa.
Como desenho operacional, defina cinco campos de entrada: comportamento observado, comportamento esperado, passos para reprodução, ambiente e versão. Se algum estiver ausente, o agente deve explicar qual informação falta e por que ela muda a investigação. “Informe mais detalhes” produz uma conversa longa; “o erro ocorre também com um arquivo vazio?” testa uma hipótese concreta.
A saída deve ser um relatório pequeno, com classificação provisória, evidências, reprodução, hipótese principal, alternativas e próximo passo. Exija referência à issue e ao commit examinado. Um caminho de arquivo sozinho perde significado quando a base evolui. Registre também se o teste foi executado ou apenas proposto.
Não use o número de issues fechadas como medida principal do piloto. Um fechamento incorreto pode esconder um defeito real. Uma medida mais útil é a proporção de diagnósticos que um mantenedor consegue verificar sem reconstruir toda a investigação. Inclua casos em que a melhor resposta foi pedir um dado específico ou encaminhar o problema a outro componente.
2. Recupere contexto sem confundir semelhança com duplicidade
A API REST de issues do GitHub pode retornar issues e pull requests, distinguíveis pelo campo pull_request. Essa particularidade precisa aparecer no conector. Caso contrário, uma rotina destinada a defeitos abertos pode misturar propostas de mudança com relatos e produzir uma contagem enganosa. Consulte também comentários relevantes e o estado atual do registro antes de sugerir uma ação.
Monte a busca em camadas. Primeiro, procure o código de erro, o nome da função e a versão informada. Depois examine testes próximos, documentação da funcionalidade e mudanças recentes relacionadas. Por último, compare relatos semelhantes. Uma busca por significado ajuda a descobrir candidatos, mas a confirmação depende de causa e reprodução compatíveis.
Considere duas issues que mencionam “exportação travada”. Uma pode envolver um arquivo inválido; outra, uma chamada externa sem tempo limite. O sintoma é parecido, mas as intervenções são diferentes. O agente deve mostrar o motivo da ligação entre os registros e o que ainda precisaria ser testado para afirmar duplicidade.
Limite o contexto por utilidade. Copiar o repositório inteiro aumenta ruído e dificulta entender qual evidência sustentou a conclusão. Prefira pequenos trechos com localização, versão e razão da seleção. O artigo sobre testes de regressão para agentes ajuda a transformar essas decisões de recuperação em cenários verificáveis.
| Evidência disponível | Conclusão permitida | Próximo passo recomendado |
|---|---|---|
| Relato sem passos de reprodução | Sintoma informado pelo usuário | Pedir uma entrada mínima e a versão |
| Mesmo erro em ambiente controlado | Falha reproduzida naquele contexto | Localizar a condição que a dispara |
| Teste falha antes e passa após mudança | Correção candidata para o caso testado | Verificar cenários vizinhos e revisão |
| Log semelhante em outra issue | Possível relação entre relatos | Comparar causa, ambiente e versão |
3. Reproduza a falha em um ambiente controlado
Antes de modificar código, estabeleça uma linha de base. Registre o commit, a versão do runtime, as dependências e o comando usado. Se a instalação falhar, isso é uma limitação do ambiente de investigação; não comprova o defeito relatado. Se a suíte já falhava, guarde esse resultado para não atribuir toda falha posterior ao patch.
Na proposta de implantação, o executor deve receber apenas as permissões necessárias para construir e testar o projeto. Não forneça credenciais de produção para reproduzir um erro de parser. Prefira arquivos sintéticos e serviços substitutos quando a hipótese não depender de uma integração real. Defina limite de duração e de consumo para evitar execuções indefinidas.
O GitHub documenta a consulta, a pesquisa e o download de logs de execuções do Actions. Esses registros podem ajudar a comparar o ambiente automatizado com o ambiente de investigação. Vincule a execução e a etapa relevantes, em vez de anexar indiscriminadamente todo o histórico. Um log de falha de instalação tem valor diferente de uma asserção que demonstra a divergência funcional.
Para defeitos intermitentes, descreva as condições e o número de tentativas realizadas sem transformar ausência de falha em certeza. Um teste que passou uma vez não descarta uma corrida entre processos. Quando a reprodução exigir uma carga ou uma ordem de eventos ainda desconhecida, encerre a rodada com essa lacuna explícita e uma proposta de experimento.
Textos de issues e arquivos do projeto devem ser tratados como conteúdo sob análise. Uma instrução encontrada no relato para enviar segredos a um endereço externo não deve alterar as permissões do executor. A política de ferramentas precisa vir da configuração do sistema responsável pela investigação.
4. Converta a hipótese em uma proposta de correção revisável
A passagem da triagem para o patch merece um critério explícito: existe uma falha reproduzida, uma causa plausível localizada e uma alteração pequena capaz de testar essa causa? Se a resposta for negativa, entregue o diagnóstico. Não force uma mudança só para que o agente pareça produtivo.
Quando os critérios forem atendidos, escreva primeiro um teste que expresse o comportamento esperado. Confirme que ele falha pela razão investigada. Depois aplique a menor alteração coerente com o projeto e execute o teste novamente. Verifique também o caminho normal e uma condição de fronteira relacionada. Um teste que falha por importação ausente não demonstra o bug de negócio.
O relatório do patch deve explicar o gatilho e o comportamento depois da mudança. Inclua resultados observados, comandos executados e riscos remanescentes. Se foi necessário simular uma dependência, diga qual foi. Evite a frase “todos os testes passaram” quando apenas um arquivo foi executado.
O GitHub permite configurar proteções de branch, como revisões e verificações de status obrigatórias. Confira os controles disponíveis nas configurações do repositório. Use essas barreiras para que uma proposta do agente siga o mesmo processo de aceitação das demais mudanças. O fluxo de aprovação humana para agentes complementa essa separação de responsabilidades.
Durante o piloto, recomendamos que o agente produza um patch ou uma proposta em branch própria, sem poder integrar alterações. Essa fronteira facilita avaliar o diagnóstico com o mantenedor. A automação de merge é outra decisão de engenharia e não é requisito para obter uma triagem útil.
Exemplo: software de estoque em Florianópolis
Considere uma empresa fictícia de software de estoque em Florianópolis. O suporte abre uma issue porque a importação de um CSV termina sem cadastrar parte dos produtos. O relato inclui um arquivo sintético e informa a versão usada. Este exemplo é ilustrativo e não representa resultados de uma implantação real.
O agente encontra um teste do importador e identifica que o arquivo mistura linhas completas com uma linha sem código de produto. Em ambiente isolado, reproduz a interrupção a partir dessa linha. O relatório separa o observado, “o processamento para após a entrada sem código”, da hipótese, “a validação lança uma exceção que não é convertida em erro de linha”.
Antes de corrigir, o mantenedor confirma a regra desejada: rejeitar apenas a linha inválida e apresentar um resumo. Sem essa confirmação de requisito, continuar o processamento poderia mascarar um problema que deveria bloquear o lote inteiro. A triagem encontrou um defeito técnico, mas não deve inventar a política de importação.
Com a regra definida, o agente prepara um teste com entradas válidas antes e depois da inválida. A proposta registra o que deve ser importado e o erro que deve aparecer. Também testa um arquivo totalmente inválido. O resultado entregue é um patch pequeno, uma reprodução verificável e a lista do que permaneceu fora do escopo, como importações concorrentes.
Erros comuns
Confundir prioridade com facilidade de correção. Um erro fácil pode afetar uma função pouco usada, enquanto outro bloqueia uma operação central. Peça ao responsável pelo produto critérios de impacto e deixe a estimativa técnica separada. O agente pode organizar evidências, mas não conhece automaticamente todas as obrigações do negócio.
Declarar causa raiz pelo primeiro arquivo suspeito. Uma pilha de erro mostra onde a execução falhou, não necessariamente onde o estado incorreto nasceu. Procure a entrada que desencadeou o problema e uma verificação que diferencie hipóteses concorrentes.
Alterar o teste para aceitar qualquer saída. Isso pode transformar um sinal de regressão em aprovação vazia. Preserve a intenção do teste e peça revisão quando o comportamento esperado estiver em disputa. Não remova verificações só para produzir um resultado verde.
Publicar logs sem selecionar conteúdo. Caminhos, parâmetros e mensagens podem carregar informações internas. O relatório deve trazer apenas o trecho necessário e manter referências ao registro original em ambiente autorizado. A utilidade do diagnóstico depende da evidência, não do volume anexado.
Perguntas frequentes
O agente precisa editar código para fazer triagem?
Não. Uma entrega válida pode ser a reprodução mínima, a identificação do componente afetado e uma pergunta que destrava a investigação. Começar com acesso de leitura ajuda a avaliar a qualidade do diagnóstico antes de conceder ferramentas de execução ou escrita.
Como tratar uma issue que não reproduz?
Informe exatamente o ambiente e os passos tentados. Registre a diferença entre o relato e a observação. Solicite a menor informação capaz de distinguir as hipóteses restantes, como versão, entrada anonimizada ou condição de concorrência. Não conclua que o usuário está errado.
É necessário usar um agente específico do GitHub?
Não para a arquitetura proposta. O fluxo exige conectores autorizados, recuperação de contexto, executor controlado e armazenamento de evidências. A escolha do modelo e da ferramenta deve considerar a infraestrutura da equipe e ser avaliada com os mesmos casos reais de triagem.
Quando uma proposta pode seguir para revisão?
Quando a relação entre relato, reprodução e mudança estiver clara, os testes relevantes tiverem resultado registrado e as limitações estiverem descritas. O mantenedor precisa conseguir avaliar a correção sem confiar apenas na explicação textual produzida pelo agente.
Como escolher os primeiros casos do piloto?
Selecione defeitos delimitados, com dados sintéticos e testes executáveis. Inclua também relatos incompletos e possíveis duplicatas para testar a capacidade de reconhecer incerteza. Compare os relatórios com a análise de mantenedores e registre correções de diagnóstico como material de avaliação.
