Como Configurar as Regras do sweep.yaml e as Diretrizes do Repositório para Alinhar Pull Requests Automatizados aos Padrões de Código

Quando equipes de engenharia de software adotam o Sweep AI para automatizar a correção de bugs, pequenas funcionalidades e tarefas de refatoração, o maior desafio operacional é garantir que os Pull Requests (PRs) gerados respeitem rigorosamente a arquitetura e os padrões de código pré-existentes. Sem limites claros, modelos de linguagem podem produzir trechos fora do padrão de formatação, omitir testes unitários, invocar métodos legados ou alterar indevidamente arquivos críticos de CI/CD e infraestrutura.

Para mitigar esses riscos, equipes técnicas constroem uma governança em camadas centrada no arquivo de configuração raiz sweep.yaml. Combinando instruções imperativas, descrições contextuais do projeto, bloqueio de pastas protegidas e integração em circuito fechado com o GitHub Actions, o Sweep atua como um desenvolvedor júnior disciplinado que entrega código alinhado às práticas do time.

1. Estrutura do sweep.yaml: O Manifesto Central de Controle

O arquivo sweep.yaml fica na raiz do repositório e funciona como a principal central de configuração declarativa para o Sweep AI. Cada chave definida orienta como a ferramenta navega pelo repositório, planeja alterações e submete PRs.

Abaixo estão os parâmetros principais de configuração:

2. Definindo Regras Práticas no sweep.yaml

O array rules é onde a equipe converte convenções humanas em restrições explícitas para o modelo de IA. Diretrizes abstratas como "escreva código limpo" têm baixa aderência; as instruções devem ser imperativas, objetivas e passíveis de validação estática.

Categorias essenciais de regras

1. Testes Unitários e Cobertura

   • Determinar que qualquer nova função ou lógica de negócio deve acompanhar testes unitários no diretório correspondente.
   • Exemplo: "All new business logic must include corresponding unit tests in the same directory or tests/. Use pytest and unittest.mock."

2. Tipagem Estática e Versões da Linguagem

   • Forçar o uso de anotações de tipo estritas e construções modernas.
   • Exemplo: "Annotate all function parameters and return types with type hints. Use built-in generics (list, tuple, dict) instead of importing from typing."

3. Padronização de Logs e Limpeza de Depuração

   • Homologar a biblioteca oficial de logs e banir declarações de depuração em produção.
   • Exemplo: "Use loguru for application logging. In except blocks, call logger.exception with structured f-strings. Never leave print() statements in production code."

4. Modularidade e Remoção de Dívida Técnica

   • Limitar o tamanho das rotinas e garantir que marcações temporárias de refatoração sejam finalizadas.
   • Exemplo: "Keep functions modular; refactor procedures longer than 50 lines. Remove redundant comments that merely restate the code. Handle all leftover TODOs."

3. Modelo de sweep.yaml Pronto para Produção

A seguir está um exemplo funcional de sweep.yaml configurado para um microsserviço moderno em Python com FastAPI e PostgreSQL:

# sweep.yaml - Configuração de Repositório para o Sweep AI

# Branch base para envio dos PRs
branch: main

# Descrição contextual da arquitetura e diretrizes de engenharia
description: >
  This is a Python 3.10 microservice built on FastAPI with PostgreSQL.
  The primary API routes are registered in app/api/v1/.
  Use SQLAlchemy 2.0 async sessions for database access.
  Strictly adhere to PEP 8 standards and asynchronous I/O paradigms.

# Criar PRs inicialmente como rascunho para triagem
draft: false

# Autocorreção: autoriza o Sweep a inspecionar logs de falhas do CI
gha_enabled: true

# Proteção: impede qualquer edição em esteiras de CI, migrações de banco e segredos
blocked_dirs:
  - ".github/"
  - "alembic/versions/"
  - "deploy/"
  - "config/secrets/"

# Conjunto de regras imperativas para o código gerado
rules:
  - "All new endpoints and service logic must include corresponding unit and integration tests using pytest."
  - "Annotate all function parameters and return values with strict type hints."
  - "Use structured logging via loguru; use logger.exception inside catch blocks. Never use print() statements."
  - "Use list, dict, and tuple built-ins for type annotations instead of importing from typing."
  - "Resolve any remaining TODO items created during refactoring before finalizing the PR."
  - "Follow existing repository import conventions: group external libraries first, then internal module imports."
  - "Do not modify database migrations or schema files without explicit issue instructions."

4. Governança Ampliada com SWEEP.md e Diretrizes Locais

Além das propriedades declarativas do sweep.yaml, equipes de engenharia costumam adotar o arquivo complementar SWEEP.md na raiz do projeto.

O Papel do SWEEP.md

O SWEEP.md atua de forma semelhante ao CLAUDE.md ou .cursorrules. Ele provê contexto perene que atende tanto aos PRs autônomos no GitHub quanto a desenvolvedores utilizando extensões de IDE (como o plugin do Sweep para JetBrains).

Geralmente, o arquivo é organizado em quatro seções:

• Comandos de Build e Validação: Instruções exatas para rodar testes, linters e formatadores (npm run lint, pytest tests/unit/ -v).
• Convenções de Estilo: Padrões de nomenclatura de pastas e arquivos (ex.: kebab-case), imports e bibliotecas preferidas.
• Arquitetura e Fluxo de Dados: Comunicação entre módulos, gerenciamento de estado e regras de contratos de API.
• Checklist de Revisão de Código: Formatação de títulos de PR, amarração a issues e atualização de documentação ou changelog.

As equipes podem criar uma versão inicial do arquivo acessando as configurações do Sweep em Sweep Settings > Rules e clicando em Generate SWEEP.md.

5. O Ciclo Fechado de CI/CD: Autocorreção via GitHub Actions

Mesmo com regras estruturadas, modelos generativos podem cometer deslizes em escopos maiores, esquecer de fechar delimitadores ou introduzir incompatibilidades de tipo. O recurso mais potente do Sweep para garantir conformidade técnica é a integração em circuito fechado com o GitHub Actions (gha_enabled: true).

+-------------------+         +--------------------+         +--------------------+
| Criação de Issue  | ------> | Sweep AI planeja e | ------> | Abre Pull Request  |
| no GitHub         |         | gera o código      |         | na branch de destino|
+-------------------+         +--------------------+         +--------------------+
                                                                        |
                                                                        v
                                                              +--------------------+
                                                              | GitHub Actions     |
                                                              | executa Linters,   |
                                                              | Tipagem e Testes   |
                                                              +--------------------+
                                                                        |
                                    +-----------------------------------+
                                    |
                    [CI com Sucesso]|             [CI com Falha]
                         v          |                  v
            +--------------------+  |        +--------------------+
            | Pronto para Code   |  |        | Sweep lê os logs   |
            | Review humano      |  |        | e mensagens de erro|
            +--------------------+  |        +--------------------+
                                    |                  |
                                    |                  v
                                    |        +--------------------+
                                    +--------| Aplica patch diff e|
                                             | envia commit extra |
                                             +--------------------+

Funcionamento do Ciclo Fechado:

1. Submissão Inicial: O Sweep submete o Pull Request baseando-se no Issue e nas regras de sweep.yaml.
2. Execução Automática de CI: O GitHub Actions dispara os linters (ESLint, Ruff, Trunk), checadores de tipos (tsc, pyright) e testes automatizados.
3. Coleta de Erros: Diante de falhas na esteira, o Sweep extrai os relatórios de execução e rastreamentos de pilha.
4. Resolução de Inconsistências: O assistente identifica o arquivo, a linha afetada e a natureza do erro (ex.: variável indefinida, import ausente, erro de sintaxe) e aplica um commit corretivo no mesmo branch.
5. Alívio da Revisão Humana: Os desenvolvedores revisam o PR apenas após todos os testes e linters estarem verdes, economizando tempo precioso de engenharia.

6. Boas Práticas Operacionais para Times de Engenharia

Para extrair máxima produtividade e manter o repositório estável, recomenda-se adotar as seguintes diretrizes:

1. Bloquear Diretórios Sensíveis: Inclua expressamente .github/, migrações de banco, manifestos de infraestrutura e diretórios de credenciais no blocked_dirs.
2. Restringir o Tamanho das Demandas: Mantenha issues com escopo focado. Demandas que afetam menos de 5 arquivos e até 300 linhas de código alcançam taxas de sucesso substancialmente maiores.
3. Instruções Precisas nos Issues: Especifique o arquivo a ser analisado, a mudança requerida e referências de implementação (ex.: "In app/services/billing.py, refactor discount calculation using Decimal instead of float; follow patterns in app/services/tax.py").
4. Comentários Interativos no PR: Caso ajustes sejam necessários, comente diretamente na linha do código iniciando a mensagem com sweep:. O assistente atualizará o código sem necessidade de checkout manual.
5. Adoção Inicial com Modo Draft: Ao introduzir o Sweep em bases de código existentes, configure draft: true no sweep.yaml. Isso permite validação humana preliminar antes de disparar pipelines extensos de CI.

Referências

• GitHub - sweepai/sweep: Sweep: AI coding assistant for JetBrains
• Sweep Config Documentation
• Sweep Advanced Features Guide
• Sweep Official Repository sweep.yaml
• CodeCrafters Frontend sweep.yaml Configuration
• Sweep Client Configuration Parser
• AI-powered junior dev meets Trunk, a super-linter