Como Fazer a IA Encontrar Bugs Reais em Pull Requests em Vez de Gerar Comentários Triviais

A maioria dos bots de rede neural para revisão de código funciona da mesma forma. Eles recebem o diff de um commit, dão uma olhada nas linhas modificadas e geram dezenas de comentários superficiais. Como resultado, os desenvolvedores recebem dicas de formatação, docstrings ausentes ou alucinações óbvias quando a IA lacks context from neighboring files. A equipe do projeto Agent-Field decidiu abordar o problema de forma diferente e criou a ferramenta PR-AF.

O Que é PR-AF e Para Quem Serve

PR-AF significa Pull Request AgentField. Esta é uma ferramenta open-source de auditoria profunda de código no estágio de CI/CD.

O projeto não tenta competir com utilitários interativos rápidos como o Claude Code, que retornam uma resposta em poucos segundos diretamente no terminal. O PR-AF é projetado para tarefas diferentes: executa por 35 a 50 minutos, mas constrói um grafo dinâmico de agentes, extrai árvores AST do repositório e verifica cada achado quanto à falseabilidade.

A ferramenta é útil para equipes que precisam de controle de qualidade automatizado rigoroso antes de fazer merge na branch principal. Isso é especialmente relevante para projetos com alto custo de erros em segurança ou arquitetura.

Como o Pipeline Dinâmico Funciona

Em vez de executar um script estático com um prompt hardcoded, o PR-AF analisa a estrutura do pull request recebido e ajusta o grafo de execução de acordo.

O processo de análise é dividido em várias etapas.

Primeiro, o sistema avalia o diff através de três fatias diferentes: semântica, mecânica e sistêmica. Agentes revisores especializados temporários são criados para as tarefas identificadas.

Então o motor de verificação de provas entra em ação. Se um agente acredita que a validação de input está faltando no código, o sistema não aceita sua palavra. Ele escaneia o repositório, extrai a árvore AST e verifica a cadeia de chamadas. O achado é descartado se nenhuma confirmação for encontrada no código.

Na próxima etapa, o filtro de falseamento é ativado. O sistema tenta refutar sua própria hipótese sobre um bug verificando salvaguardas existentes e o comportamento pretendido pelo autor.

No final, o sintetizador composto de risco entra em ação. Problemas menores isolados em arquivos diferentes frequentemente se combinam em uma vulnerabilidade crítica. A ferramenta linking such findings into a single report.

Resultados nos Benchmarks e Economia

No benchmark Martian Code-Review-Bench, o sistema PR-AF em combinação com o modelo open GLM-5.2 mostrou um recall de detecção de bugs (golden recall) de 0.706. No conjunto de teste de 42 ferramentas, este resultado colocou o projeto em primeiro lugar entre as soluções open-source.

Durante os testes, o sistema descobriu independentemente 595 erros confirmados. Ao usar modelos comerciais de topo, os resultados são ainda maiores.

Ao mesmo tempo, o custo de uma execução é aproximadamente 10 vezes menor do que alternativas SaaS fechadas. Você paga apenas pelos tokens LLM através da sua própria chave de API, sem uma assinatura mensal por usuário.

Início Rápido e Trabalho via API

Você pode iniciar o PR-AF localmente em poucos minutos via Docker Compose.

git clone https://github.com/Agent-Field/pr-af.git
cd pr-af
cp .env.example .env
docker compose up --build

No arquivo .env, você só precisa especificar seu OPENROUTER_API_KEY e GH_TOKEN com permissões de leitura e escrita para o repositório. Após a inicialização, o nó de controle estará disponível na porta 80.

Você pode enviar um pull request para revisão com uma requisição HTTP padrão:

curl -X POST http://localhost:8080/api/v1/execute/async/pr-af.review \
  -H "Content-Type: application/json" \
  -d '{"input": {"pr_url": "https://github.com/owner/repo/pull/123"}}'

Em resposta, você recebe um JSON final com análise de vulnerabilidade, dividida por nível de severidade. Se o bot tiver acesso ao GitHub, ele automaticamente colocará comentários nas linhas relevantes do código com evidências de suporte.

Integração com GitHub Actions

A forma mais fácil de integrar auditoria integrada é no CI/CD padrão. Um arquivo .github/workflows/pr-af-review.yml é adicionado ao repositório, e a execução é triggered by adding a pr-af label to the pull request.

name: AgentField PR Review

on:
  pull_request:
    types: [labeled]

jobs:
  pr-af-review:
    if: github.event.label.name == 'pr-af'
    runs-on: ubuntu-latest

    permissions:
      contents: read
      pull-requests: write

    steps:
      - name: Checkout PR-AF
        uses: actions/checkout@v4
        with:
          repository: Agent-Field/pr-af
          path: pr-af

      - name: Start AgentField & PR-AF
        working-directory: ./pr-af
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          docker compose up -d
          sleep 15

      - name: Execute Deep Architectural Audit
        working-directory: ./pr-af
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
        run: |
          python3 scripts/ci_runner.py

O desenvolvedor anexa o label ao PR responsável, passa meia hora e um relatório detalhado com fatos verificados aparece na thread.

Por Trás dos Panos

O nó principal do projeto foi recentemente reescrito em Go (o código está no diretório go/), o que afetou positivamente a velocidade e o consumo de memória. A implementação original em Python permanece disponível no repositório como alternativa.

O projeto é distribuído sob a licença permissiva Apache 2.0. O código é totalmente aberto, incluindo scripts para reproduzir os resultados do benchmark.

Conclusão

O PR-AF oferece uma abordagem sensata para revisão automatizada. Em vez de spammar a compilação com comentários superficiais, o sistema gasta tempo em análise AST detalhada e verificação de hipóteses.

A ferramenta é ideal para equipes que estão cansadas de falsos positivos de bots de IA regulares e precisam de um filtro de segurança confiável no CI/CD. Não é adequada para correções rápidas de typos, mas se sai excellentemente antes de fazer merge de funcionalidades críticas em produção.