Usando Bugbot para Revisão Automatizada de Código no Cursor

Bugbot é o agente de revisão automatizada de código integrado ao Cursor que se integra diretamente aos seus repositórios do GitHub. Quando você abre um pull request, o Bugbot analisa o diff, identifica possíveis bugs, sugere melhorias e deixa comentários inline no seu PR. Este guia cobre tudo, desde a configuração inicial até a configuração avançada, incluindo os problemas de roteamento de PR e integração com GitHub Teams que os usuários do fórum frequentemente encontram.

O Que o Bugbot Faz

O Bugbot realiza várias camadas de análise em cada pull request:

• Detecção de bugs - Identifica erros de lógica, riscos de referência nula e casos extremos
• Verificação de segurança - Sinaliza potenciais vulnerabilidades como injeção de SQL ou segredos codificados diretamente
• Estilo e consistência - Verifica desvios dos padrões da sua base de código
• Dicas de desempenho - Destaca padrões ineficientes como consultas N+1
• Cobertura de testes - Nota quando alterações não têm testes correspondentes

dica

O Bugbot é executado inteiramente na nuvem. Você não precisa manter o Cursor aberto para que as revisões aconteçam. Uma vez ativado em um repositório, o Bugbot revisa cada PR automaticamente, esteja você na sua mesa ou não.

Pré-requisitos

Antes de configurar o Bugbot, certifique-se de ter:

1. Cursor Pro ou plano Business - Bugbot não está disponível no plano gratuito
2. Um repositório GitHub com fluxos de trabalho de pull request ativados
3. Acesso de administrador ou mantenedor ao repositório (necessário para instalação do app)
4. GitHub Teams configurado se deseja roteamento de PR baseado em equipe

Ativando o Bugbot em um Repositório

O problema mais relatado pelos usuários do fórum é o Bugbot dizendo "disabled for this repository." Isso quase sempre remonta à etapa de instalação do GitHub App ter sido pulada ou parcialmente concluída.

Passo 1: Instalar o GitHub App do Cursor

O Bugbot opera através de um GitHub App. Se você ainda não o instalou:

1. Abra o Cursor e navegue até Settings > Features > Bugbot
2. Clique em Connect GitHub Account
3. Você será redirecionado ao GitHub para autorizar o aplicativo Cursor
4. Escolha o escopo:
   • All repositories - O Cursor pode revisar qualquer repo na sua conta
   • Selected repositories - Escolha repos específicos para revisão

aviso

Se você selecionou repositórios específicos durante a instalação e depois criar um novo repositório, o Bugbot não funcionará no novo repo até que você o adicione explicitamente. Esta é a causa número um do erro "disabled for this repository". Para corrigir, vá ao GitHub > Settings > Integrations > Applications > Cursor > Configure, e adicione o novo repositório.

Passo 2: Ativar o Bugbot nas Configurações do Cursor

Depois que o GitHub app estiver instalado:

1. Abra Cursor Settings (Cmd/Ctrl + ,)
2. Navegue até Features > Bugbot
3. Alterne Enable Bugbot para ON
4. Selecione em quais repositórios ativar o Bugbot

Passo 3: Verificar a Conexão

Crie um pull request de teste e verifique se o Bugbot responde:

# Create a test branch
git checkout -b test-bugbot-connection

# Make a small change
echo "// Bugbot test" >> README.md
git add README.md
git commit -m "test: verify bugbot connection"
git push origin test-bugbot-connection

Abra um PR no GitHub. Em 30-60 segundos, o Bugbot deve postar um comentário. Se não o fizer, prossiga para a seção de solução de problemas abaixo.

Roteamento de PR e Atribuição de Revisores

O Bugbot pode rotear pull requests para revisores específicos com base em caminhos de arquivos, propriedade de código ou associação de equipe. Usuários do fórum relatam que o roteamento de PR nem sempre funciona como esperado, particularmente com GitHub Teams.

Compreendendo o Roteamento de PR

O roteamento de PR determina quem recebe a solicitação de revisão quando o Bugbot analisa um PR. A lógica de roteamento segue esta prioridade:

1. Arquivo CODEOWNERS - Se presente, os proprietários dos arquivos alterados tornam-se revisores
2. Mapeamento de GitHub Teams - Roteamento baseado em equipe via configuração do Bugbot
3. Fallback - Todos os mantenedores recebem a solicitação de revisão

Configurando CODEOWNERS

Crie um arquivo CODEOWNERS na raiz do seu repositório (ou .github/CODEOWNERS):

# Default owners
*                           @team-leads

# Frontend files
src/components/             @frontend-team
src/pages/                  @frontend-team
src/styles/                 @frontend-team

# Backend files
src/api/                    @backend-team
src/models/                 @backend-team
src/middleware/             @backend-team

# Infrastructure
terraform/                  @devops-team
docker/                     @devops-team
.github/workflows/           @devops-team

# Security-sensitive files
src/auth/                   @security-team @team-leads
.env*                       @security-team

Integração com GitHub Teams

Para roteamento baseado em equipe, o Bugbot lê a associação das suas GitHub Teams. Para configurar:

1. Certifique-se de que sua organização GitHub tenha equipes configuradas em Org Settings > Teams
2. Adicione membros a cada equipe
3. Referencie nomes de equipes (com prefixo @) no CODEOWNERS
4. No Cursor, vá para Settings > Features > Bugbot > Advanced
5. Ative Use GitHub Teams for routing

dica

Os nomes de equipe do GitHub no CODEOWNERS devem corresponder exatamente. Um erro comum é usar nomes de exibição em vez do slug da equipe. Por exemplo, se sua equipe se chama "Frontend Engineers" com slug frontend-engineers, a entrada no CODEOWNERS deve ser @frontend-engineers, e não @Frontend Engineers.

Problemas Comuns de Roteamento de PR

Problema: PR Roteado para Equipe Errada

Sintoma: Um PR que altera arquivos de backend é roteado para a equipe de frontend.

Causa: Padrões CODEOWNERS sobrepostos. O primeiro padrão correspondente vence, e os padrões são avaliados de cima para baixo.

Solução: Reordene seu arquivo CODEOWNERS para que padrões mais específicos venham antes dos gerais:

# Specific first
src/auth/                   @security-team @team-leads
src/api/                    @backend-team

# Then general
src/                        @all-developers
*                           @team-leads

Problema: Equipe Não Recebe Solicitações de Revisão

Sintoma: O Bugbot revisa o PR, mas nenhum membro da equipe GitHub é adicionado como revisor.

Causa: A equipe do GitHub está definida como "secret" (não visível) ou não tem membros.

Solução: Vá ao GitHub > Organization > Teams > [Nome da Equipe] > Settings. Certifique-se de que a visibilidade da equipe não esteja definida como "Secret" se deseja que ela receba solicitações de revisão. Verifique se a equipe tem membros ativos.

Configuração do Bugbot

Além da ativação básica, o Bugbot oferece várias opções de configuração para personalizar seu comportamento.

Severidade da Revisão

Controle o quão agressivo o Bugbot é com suas descobertas:

{
  "bugbot.severity": "balanced",
  "bugbot.maxComments": 20,
  "bugbot.autoResolve": false
}

Severidade	Comportamento
strict	Relata todas as descobertas, incluindo problemas menores de estilo
balanced	Relata bugs, problemas de segurança e problemas significativos de estilo (padrão)
lenient	Relata apenas bugs e vulnerabilidades de segurança

Exclusões de Arquivos

Evite que o Bugbot revise arquivos gerados ou de terceiros:

{
  "bugbot.excludePaths": [
    "**/*.min.js",
    "**/*.min.css",
    "node_modules/**",
    "dist/**",
    "build/**",
    "*.lock",
    "package-lock.json",
    "yarn.lock"
  ]
}

Configuração do Agente de Segurança

O Bugbot inclui um agente de segurança dedicado que verifica vulnerabilidades. Configure-o independentemente:

{
  "bugbot.securityAgent": {
    "enabled": true,
    "sensitivityLevel": "high",
    "scanForSecrets": true,
    "scanForDependencies": true,
    "ignorePatterns": [
      "test/**",
      "__mocks__/**"
    ]
  }
}

aviso

O agente de segurança verifica se há segredos codificados diretamente (chaves de API, senhas, tokens) no diff do seu PR. Se encontrar o que acredita ser um segredo, ele o sinalizará como um problema crítico. Este é um recurso de segurança. Nunca descarte esses avisos sem verificar se a string sinalizada não é um segredo real. Mesmo fixtures de teste que parecem chaves reais podem ser perigosos se alguém os copiar para o código de produção.

Fluxos de Aprovação

O Bugbot se integra ao sistema de aprovação de revisão do GitHub. Você pode configurar se as descobertas do Bugbot bloqueiam a mesclagem de PRs.

Definindo Revisões Obrigatórias

Nas configurações do seu repositório GitHub:

1. Vá para Settings > Branches > Branch protection rules
2. Edite a regra do seu branch principal
3. Em Require pull request reviews before merging:
   • Defina revisões de aprovação obrigatórias (ex.: 2)
   • Ative Dismiss stale pull request approvals quando novos commits forem enviados
   • Ative Require review from Code Owners

Bugbot como Revisor Obrigatório

Você pode configurar o Bugbot para atuar como um revisor obrigatório. Quando ativado, PRs não podem ser mesclados até que o Bugbot tenha concluído sua revisão e aprovado ou a revisão tenha sido descartada.

No Cursor:

1. Settings > Features > Bugbot > Workflow
2. Ative Block merge on critical findings
3. Defina o limite de severidade para bloqueio (padrão: crítico e alto)

dica

Use o recurso de bloqueio com critério. Se você definir o limite muito baixo (bloqueando descobertas de baixa severidade), os desenvolvedores podem ficar frustrados quando problemas de estilo impedirem a mesclagem. Comece com "crítico e alto" e ajuste com base na experiência da equipe.

Lidando com Desacordos do Bugbot

Às vezes o Bugbot sinaliza algo que o desenvolvedor acredita ser um falso positivo. O fluxo de trabalho recomendado:

1. Clique em Resolve conversation no comentário do Bugbot no GitHub
2. Adicione um comentário explicando por que é um falso positivo
3. Se for um falso positivo recorrente no mesmo padrão, adicione um comentário // bugbot-ignore:

# bugbot-ignore: This is intentionally using eval for a DSL interpreter
result = eval(user_expression)

Solução de Problemas "Disabled for This Repository"

Este é o problema mais relatado do Bugbot. Siga este fluxograma de diagnóstico.

Passo de Diagnóstico 1: Verificar Instalação do GitHub App

# Check if the Cursor app has access to your repo
gh api repos/{owner}/{repo}/installation --jq '.id'

Se isso retornar um 404, o GitHub App não está instalado para este repositório.

Solução: Vá ao GitHub > Settings > Integrations > Applications > Cursor > Configure e adicione o repositório.

Passo de Diagnóstico 2: Verificar Configurações do Repositório no Cursor

1. Abra as configurações do Cursor
2. Navegue até Features > Bugbot
3. Procure seu repositório na lista de ativados
4. Se não estiver lá, clique em Add Repository e selecione-o

Passo de Diagnóstico 3: Verificar Regras de Proteção de Branch

O Bugbot requer que seu repositório permita que o GitHub App poste comentários de revisão. Se suas regras de proteção de branch forem muito restritivas:

1. Vá ao GitHub > Settings > Branches
2. Edite sua regra de proteção de branch
3. Certifique-se de que Allow specified actors to bypass requirements inclua o aplicativo Cursor
4. Certifique-se de que o aplicativo não esteja bloqueado por Restrict who can push to matching branches

Passo de Diagnóstico 4: Verificar Aplicativos Conflitantes

Se você tiver outras ferramentas de revisão automatizada instaladas (CodeRabbit, GitHub Copilot, SonarQube), elas podem conflitar com o Bugbot.

Solução: Desative outros bots de revisão temporariamente e verifique se o Bugbot começa a funcionar. Se funcionar, você precisará configurar as ferramentas para coexistir, o que pode exigir o ajuste de configurações de webhook ou gatilhos de revisão.

Passo de Diagnóstico 5: Verificar Status do Bugbot

# Check Cursor service status
curl -s https://status.cursor.sh/api/v2/incidents.json | jq '.incidents[] | select(.status != "resolved")'

Se houver um incidente ativo, aguarde a resolução e tente novamente.

aviso

O Bugbot às vezes aparece como "disabled" imediatamente após uma atualização do Cursor. Este é um problema conhecido onde o token do GitHub precisa de reautenticação. Vá para Settings > Features > Bugbot, clique em Disconnect, depois em Reconnect sua conta GitHub. Isso atualiza o token sem perder sua configuração.

Análise Profunda da Integração do Bugbot com GitHub Teams

Sincronizando Associação de Equipe

O Bugbot armazena em cache a associação de equipe do GitHub para desempenho. Se você adicionar ou remover um membro da equipe, a mudança pode não ser refletida imediatamente.

Para forçar uma sincronização:

1. Abra as configurações do Cursor
2. Vá para Features > Bugbot > Advanced
3. Clique em Sync GitHub Teams
4. Aguarde a conclusão da sincronização (geralmente menos de 30 segundos)

Associação em Múltiplas Equipes

Quando um desenvolvedor pertence a várias equipes, o Bugbot roteia com base na correspondência do CODEOWNERS. Se um arquivo é de propriedade de várias equipes e o desenvolvedor está em ambas, ele recebe uma única solicitação de revisão, não duplicadas.

Políticas de Revisão Baseadas em Equipe

Você pode configurar diferentes requisitos de revisão por equipe:

{
  "bugbot.teamPolicies": {
    "security-team": {
      "requiredReviews": 2,
      "blockOnHighSeverity": true,
      "additionalScanners": ["dependency-check"]
    },
    "frontend-team": {
      "requiredReviews": 1,
      "blockOnHighSeverity": false
    }
  }
}

Desempenho e Limites do Bugbot

Velocidade de Revisão

O Bugbot normalmente conclui uma revisão em 30-90 segundos após um PR ser aberto ou atualizado. Fatores que afetam a velocidade:

Fator	Impacto
Tamanho do PR (linhas alteradas)	Diffs grandes levam mais tempo para analisar
Número de arquivos	Cada arquivo requer análise individual
Tamanho do repositório	Bases de código maiores exigem mais coleta de contexto
Carga atual	Horários de pico podem ter respostas mais lentas

Limite de Comentários

Por padrão, o Bugbot posta no máximo 20 comentários por revisão. Isso evita sobrecarregar o autor do PR. Você pode ajustar isso:

{
  "bugbot.maxComments": 50
}

dica

Se o Bugbot estiver atingindo o limite de comentários em todos os PRs, considere elevar o limite de severidade. Atingir o limite significa que o Bugbot está encontrando muitos problemas de baixa prioridade. Filtrá-los tornará a revisão mais acionável.

Limites de Taxa

O Bugbot respeita os limites de taxa da API do GitHub. Se sua organização tiver muitos PRs abertos simultaneamente, as revisões podem ser enfileiradas. O Bugbot as processa em ordem, e todas as revisões eventualmente são concluídas.

Melhores Práticas para Adoção do Bugbot

Comece em Modo Somente Leitura

Ao ativar o Bugbot pela primeira vez em um repositório existente, comece em modo somente leitura (sem bloqueio de mesclagem). Isso permite que a equipe veja o que o Bugbot encontra sem interromper seu fluxo de trabalho. Após uma ou duas semanas revisando as descobertas, ajuste a configuração e ative o bloqueio de mesclagem, se apropriado.

Use as Descobertas do Bugbot como Ferramentas de Aprendizado

As descobertas do Bugbot não são apenas sobre corrigir o PR atual. São oportunidades de aprendizado:

1. Rastrear tipos de descobertas recorrentes (ex.: "risco de referência nula" aparece em 30% dos PRs)
2. Criar entradas .cursor/rules para prevenir o padrão em código futuro
3. Compartilhar descobertas interessantes nos canais da equipe

Revisão Regular de Configuração

Revise sua configuração do Bugbot mensalmente:

• As exclusões de arquivos ainda são apropriadas?
• Os limites de severidade estão calibrados corretamente?
• Existem novos padrões de falso positivo para suprimir?
• O limite de comentários é apropriado para os tamanhos atuais de PR?

Resumo

O Bugbot traz revisão de código automatizada e inteligente para cada pull request em seus repositórios GitHub conectados ao Cursor. O problema mais comum, "disabled for this repository", é quase sempre resolvido verificando o escopo de instalação do GitHub App e garantindo que o repositório seja explicitamente adicionado. Configurando o roteamento de PR com CODEOWNERS, ajustando o agente de segurança e adotando uma abordagem incremental para o bloqueio de mesclagem, sua equipe pode aproveitar o Bugbot como uma primeira linha de defesa confiável contra bugs e vulnerabilidades de segurança.