Como configurar o Sweep para transformar Issues do GitHub em Pull Requests automatizados de correção de bugs

Em equipes de desenvolvimento de software, a constante sobrecarga de tarefas de manutenção rotineiras consome horas valiosas de engenheiros seniores. Correções de NullPointer, atualizações de dependências depreciadas, ajustes em expressões regulares e a escrita de testes unitários pendentes frequentemente permanecem estagnados no backlog durante semanas, desviando o foco de entregas estratégicas de produto.

O Sweep foi criado exatamente para resolver esse gargalo, atuando como um desenvolvedor júnior autônomo baseado em inteligência artificial (AI Junior Developer). Conectado como um GitHub App ao repositório, o Sweep monitora novas Issues, compreende o código por meio de embeddings vetoriais e análise de árvore sintática abstrata (AST), implementa alterações em múltiplos arquivos e submete Pull Requests (PRs) completos e formatados. Além disso, ele fecha o ciclo de engenharia inspecionando falhas no pipeline de CI do GitHub Actions para se autocorrigir e respondendo a revisões de código de desenvolvedores humanos.

Este guia detalha como configurar o Sweep em ambiente profissional, estruturar o arquivo sweep.yaml, elaborar prompts eficazes em Issues e aplicar barreiras de proteção de código.

1. O fluxo de transformação de Issues em Pull Requests

Antes de criar os arquivos de configuração, é indispensável compreender o ciclo de vida operacional do Sweep:

1. Disparo do evento: Um engenheiro abre uma Issue no GitHub com o prefixo Sweep: (por exemplo, Sweep: Fix KeyError when user metadata payload is missing), aplica o rótulo sweep ou menciona @sweepai em um comentário.
2. Recuperação de contexto do repositório: A função de entrada do webhook do Sweep (on_ticket) é executada. Ela utiliza busca vetorial e particionamento de código para identificar arquivos, classes e testes relacionados ao problema reportado.
3. Plano de execução detalhado: O Sweep responde na própria Issue com um plano de trabalho, discriminando os arquivos que serão alterados e a lógica a ser aplicada.
4. Geração de código e ramificação: Em uma branch exclusiva (como sweep/fix-...), o Sweep gera os patches de código respeitando as regras do projeto.
5. Abertura do Pull Request: O Sweep submete um PR formal contendo a vinculação de resolução (Fixes #<id>), um resumo técnico das mudanças e um checklist de validação.
6. Ciclo de feedback e refinamento:
   • Autocorreção via CI: Com o GitHub Actions integrado (gha_enabled: true), caso os testes unitários falhem, o Sweep analisa os logs de erro e envia commits de correção automaticamente.
   • Revisão humana contínua: Quando um revisor deixa comentários linha por linha no diff do PR, o Sweep processa os pedidos e realiza novos commits corretivos na mesma branch.

2. Instalação e permissões no GitHub

Para habilitar o Sweep em sua organização:

1. Instalar o GitHub App: Acesse a página de instalação do Sweep no GitHub e selecione os repositórios autorizados.
2. Definir permissões obrigatórias:
   • Repository Contents (Leitura e Escrita): Necessário para ler o código-fonte e criar branches com commits.
   • Issues (Leitura e Escrita): Necessário para processar descrições, gerenciar rótulos e publicar atualizações de status.
   • Pull Requests (Leitura e Escrita): Necessário para abrir PRs, examinar diffs e iterar sobre revisões de código.
   • Actions / Checks (Leitura): Necessário para obter os logs de erro quando os pipelines de teste falharem.
3. Modo rascunho (Draft PR): Em fases iniciais de adoção, recomenda-se configurar a abertura de PRs como rascunho (draft: true), evitando notificações excessivas nos canais do time até que uma triagem inicial seja concluída.

3. Configuração de regras com sweep.yaml

O comportamento central do Sweep é regido pelo arquivo sweep.yaml (ou .sweep/config.yaml), localizado na raiz do projeto. Ele estabelece limites técnicos, previne importações inexistentes e padroniza a arquitetura do código gerado.

Modelo de produção para sweep.yaml

# sweep.yaml - Configuração para resolução automatizada de Issues

# Branch base a partir da qual o Sweep cria as branches de trabalho e abre PRs
branch: 'main'

# Abrir PRs como rascunho (recomendado no início da implementação)
draft: false

# Habilitar leitura de logs de falha do GitHub Actions para autocorreção
gha_enabled: true

# Visão geral da arquitetura para orientar a compreensão do modelo
description: >
  API REST de backend desenvolvida com Python 3.10 e FastAPI.
  Persistência de dados utilizando SQLAlchemy 2.0 e PostgreSQL.
  Lógica de negócio centralizada em services/, modelos em models/ e rotas em api/v1/.
  Todas as importações devem ser absolutas (ex: `from services.auth import verify_token`).

# Diretórios e arquivos que o Sweep JAMAIS deve ler ou modificar
blocked_dirs:
  - "deploy/"
  - "terraform/"
  - ".github/workflows/"
  - "migrations/"
  - "*.env*"
  - "security/"

# Comandos de sandbox executados antes da abertura do Pull Request
sandbox:
  install:
    - "poetry install --no-root"
  check:
    - "poetry run ruff check {file_path}"
    - "poetry run pytest tests/unit"

# Diretrizes estritas de código injetadas no prompt do agente
rules:
  - "Toda correção de bug deve incluir ou atualizar testes unitários com pytest em tests/."
  - "Proibido o uso de importações coringa (`from module import *`)."
  - "Validações de requisições e respostas de API devem usar schemas Pydantic v2."
  - "Registrar logs estruturados com loguru; incluir tracebacks em exceções com logger.exception()."
  - "Não alterar schemas de banco de dados nem gerar migrações alembic sem instrução explícita."
  - "Adicionar anotações de tipo completas em todas as assinaturas de função."

Análise dos principais parâmetros

• branch: Indica a branch alvo de integração. Deve ser alinhada caso a equipe utilize estratégias como Git Flow com a branch develop.
• blocked_dirs: Barreira de contenção indispensável. Garante que o agente não altere configurações de infraestrutura, pipelines de CI, credenciais ou migrações de dados.
• gha_enabled: Ativa o ciclo de cura autônoma ao analisar o retorno das esteiras de integração contínua do GitHub Actions.
• rules: Instruções expressas em linguagem natural que norteiam as decisões do agente, mantendo aderência ao padrão da base de código.
• sandbox: Especifica os comandos de instalação (install) e checagem estática/testes (check) rodados em container isolado antes do envio do PR.

4. Como estruturar Issues para obter PRs precisos

A assertividade do código gerado pelo Sweep depende diretamente do detalhamento fornecido na Issue do GitHub. Diferente de desenvolvedores humanos, a IA não participa de reuniões de alinhamento e depende exclusivamente das instruções fornecidas.

Estrutura recomendada de Issue

Título: Sweep: Fix 400 Bad Request on empty user metadata payload in /api/v1/profile

### Descrição do problema
Ao atualizar o perfil de usuário via `PUT /api/v1/profile`, o envio de um dicionário vazio em `metadata` dispara um ValidationError em vez de inicializar os dados com valores padrão.

### Passos para reproduzir
1. Enviar uma requisição PUT para `/api/v1/profile` contendo o payload `{"metadata": {}}`.
2. Notar que a API responde com HTTP 400 e a mensagem `Value error, metadata must contain required fields`.

### Comportamento esperado
A API deve aceitar o dicionário `metadata` vazio, preencher os campos com valores predefinidos (`{"theme": "light", "notifications": true}`) e salvar no banco com sucesso.

### Arquivos e funções relevantes
- `api/v1/profile.py`: Manipulador da rota `update_profile`.
- `schemas/profile.py`: Modelo Pydantic `UserProfileUpdate`.
- `services/profile_service.py`: Função utilitária `save_profile_metadata`.

### Critérios de aceitação
- Corrigir a validação em `schemas/profile.py` para permitir dicionários vazios com valores de fallback.
- Criar um teste unitário em `tests/unit/test_profile_api.py` validando o cenário de payload vazio.
- Garantir que toda a suíte de testes em `tests/unit/` continue passando.

Prefixos de título e modos de execução

O analisador de títulos do Sweep (strip_sweep) aceita prefixos específicos para modular a execução:

• Sweep: <título>: Fluxo padrão de processamento de tarefas.
• Sweep(sandbox): <título>: Obriga a execução e validação completa no sandbox antes do PR.
• Sweep(fast): <título>: Prioriza velocidade e menor latência para correções simples.
• Sweep(slow): <título>: Amplia a profundidade de análise para problemas que envolvem múltiplos módulos.
• Sweep(lint): <título>: Executa varredura rigorosa de formatação e análise estática.
• Sweep(subissues): <título>: Divide tarefas amplas em sub-issues independentes.

5. Revisão de código e iterações no PR

Após a abertura do Pull Request pelo Sweep, a equipe colabora diretamente pela interface do GitHub:

[GitHub Issue] ──> Disparo do Sweep ──> PR Aberto ──> CI (GitHub Actions)
                                                            │
                         ┌──────────────────────────────────┴─────┐
                         ▼                                        ▼
                   CI Falha (gha_enabled)                     CI Sucesso
                         │                                        │
                         ▼                                        ▼
               Sweep envia commit de ajuste                Revisão Humana
                         │                                        │
                         └─────────► PR Atualizado ◄──────────────┘
                                           │
                               (Comentário no Diff:
                             "@sweepai utilize a função
                                utilitária existente")

Comentários inline no diff

Os engenheiros não precisam clonar a branch localmente para pequenos ajustes. Basta adicionar um comentário na linha de código relevante:

@sweepai Utilize a função utilitária DateUtils.formatIso() existente em vez de implementar um novo formatador de datas.

O Sweep captura o evento de comentário, analisa o trecho indicado e publica um novo commit na mesma branch do PR.

Regeneração de PR

Se as diretrizes da Issue original forem alteradas ou o caminho de solução precisar ser redefinido, basta editar o título ou a descrição da Issue original no GitHub. O Sweep detecta a alteração, descarta a branch anterior e regenera um PR totalmente novo.

6. Boas práticas de segurança e governança de engenharia

Para manter a integridade da base de código ao utilizar agentes autônomos:

1. Aprovação humana indispensável: Nunca habilite a mesclagem automática (Auto-merge) nos PRs gerados pelo Sweep. Mantenha regras de proteção de branch exigindo a aprovação de pelo menos um engenheiro sênior e a aprovação de todos os testes de CI.
2. Isolamento de diretórios sensíveis: Configure blocked_dirs com rigor para proteger arquivos de infraestrutura (terraform/, k8s/), esteiras de CI (.github/), scripts de migração de banco de dados e arquivos de variáveis de ambiente.
3. Delimitação de escopo: Reserve o Sweep para correções cirúrgicas de bugs, criação de testes unitários e refatorações pontuais. Não utilize o agente para reformulações arquiteturais complexas sem especificações exatas.
4. Base sólida de testes: A eficácia da autocorreção do Sweep depende diretamente da clareza das mensagens de erro do CI. Quanto maior a cobertura de testes automatizados, mais seguro e confiável será o trabalho do agente.

Referências

• GitHub - sweepai/sweep: Sweep: AI coding assistant for JetBrains
• GitHub - sweepai/sweep: sweep.yaml configuration file
• GitHub - sweepai/sweep: sweepai/config/client.py
• GitHub - sweepai/sweep: sweepai/handlers/on_ticket.py
• GitHub - sweepai/sweep: sweepai/utils/str_utils.py
• sweepai · PyPI
• Launch YC: Sweep: JetBrains AI Coding Assistant | Y Combinator