PR tidy (Limpeza de PR)
Uma varredura de consistência de um branch antes de ele se tornar um pull request. Ela analisa o que o diff mudou e, em seguida, tudo o que o diff também deveria ter mudado.
Trabalhe nas próprias alterações do branch. Deixe intacta a dívida técnica não relacionada em outras partes do repositório, a menos que o diff a torne incorreta.
0. Escopo
-
Leia primeiro as instruções do repositório:
AGENTS.md,CLAUDE.md,CONTRIBUTING*,README*e quaisquer documentos para os quais eles apontam. -
Encontre a base e o diff:
base=$(git merge-base origin/main HEAD) # ou o branch padrão do repositório git log --oneline "$base"..HEAD git diff --stat "$base"...HEAD git diff --name-only "$base"...HEAD -
Verifique a árvore de trabalho (
git status). Mantenha as alterações não commitadas. Se uma edição que você faria se sobrepor a elas, pare e pergunte. -
Se você estiver no branch padrão sem nada para comparar, pare e informe.
1. Classifique o diff
Classifique as alterações em:
- Novo: arquivos, comandos, funções, opções, flags, chaves de configuração, variáveis de ambiente, scripts, skills.
- Alterado: comportamento, padrões, APIs, assinaturas, regras e design: um guia ou especificação que agora diz algo diferente.
- Removido ou renomeado: qualquer coisa deletada, renomeada, movida ou substituída.
- Infraestrutura: build, CI, testes, ferramentas.
A partir disso, liste a superfície: cada nome, caminho, flag, opção, termo e regra que um leitor ou outro arquivo poderia referenciar. Para mudanças de design, liste também as frases-chave da ideia antiga, não apenas seu nome (um "check por nível" removido pode ainda ser descrito como "uma verificação em cada nível").
2. Referências desatualizadas
Para cada item removido, renomeado ou redesenhado, pesquise em todo o repositório, não apenas nos arquivos alterados:
git grep -n -w "nome_antigo" # nomes, caminhos, flags
git grep -n -i "frase do design antigo"
Procure em código, comentários, testes, documentos, READMEs, exemplos, notebooks, templates, arquivos de skill, diagramas (Mermaid e ASCII) e configuração. Cada ocorrência é atualizada ou sinalizada com um motivo.
Em seguida, construa um mapa de cobertura para cada item novo ou alterado: onde ele está documentado?
Mapa de cobertura:
item referência how-to exemplo explicação
--new-flag README - - -
check_levels.py scripts/ - - -
Um item sem cobertura é uma lacuna; relate-a. Não escreva páginas de documentação inteiras sem solicitação.
3. Testes e documentação para novo comportamento
Para cada comportamento novo ou alterado:
- Um teste o exercita, na camada que o possui, e seu caminho de falha onde isso mudou. Prefira o padrão de teste existente do repositório e o teste mais restrito que pegaria a regressão.
- Documentação o descreve onde quer que o comportamento antigo fosse descrito: referência, exemplos e qualquer guia que ensinasse o caminho antigo.
- Relate um teste ausente apenas quando puder nomear a falha concreta que ele pegaria. Pule especulação e dívida de cobertura não tocada.
4. Verificadores falham ruidosamente
Para cada verificador, linter, validador ou script de verificação novo ou alterado:
- Conectado. Encontre todos os pontos de entrada que o repositório usa:
.pre-commit-config.yaml,.github/workflows/*,Makefile,justfile,noxfile.py,tox.ini,pyproject.tomlou scriptspackage.json, e qualquer validador que chame outras verificações. Confirme que o verificador é chamado por pelo menos um. Se não, conecte-o da mesma forma que seus semelhantes são, ou sinalize-o. - Falha em entrada ruim. Execute-o em uma entrada deliberadamente quebrada; ele deve sair com código não zero.
- Falha em nada. Execute-o em entrada vazia ou ausente (sem arquivos, sem correspondências, nada parseado); ele deve sair com código não zero ou dizer claramente que não verificou nada, nunca passar silenciosamente.
- Tem um teste cobrindo 2 e 3.
Para manter isso verdadeiro depois, adicione um teste de conexão como references/test_checkers_wired.py.
5. Números, versões e exemplos
Liste cada número, versão, data, URL, citação, comando e exemplo de código nos arquivos que o diff tocou ou nos documentos que os descrevem. Para cada um:
- Nomeie sua fonte: o código ou comando que o produz, um valor de configuração, um conjunto de dados ou um artigo com sua versão exata (arXiv
v3, um DOI). - Re-verifique-o: execute novamente o comando ou releia a fonte. Corrija-o ou sinalize-o se não puder verificar.
- Mantenha sua condição junto: o conjunto de dados, configuração, máquina ou tempo para o qual um número é válido ("N pontos em T horas na máquina M", não "N pontos").
- Fixe fontes externas a uma versão.
- Números que continuarão mudando são melhor gerados a partir de código (por exemplo, com
cog, verificado porcog --check) do que digitados à mão; sugira isso.
6. Informações pessoais e credenciais
Verifique tudo o que o branch adiciona e todos os arquivos não rastreados prestes a serem adicionados, antes de saírem da máquina. Isso é bloqueante: nada abaixo é "corrigido" ao prosseguir.
git diff "$base"...HEAD # commitado no branch
git diff; git diff --cached # ainda não commitado
git status --short # arquivos não rastreados que podem ser adicionados
Procure por:
- Credenciais: chaves de API, tokens, senhas, strings de conexão com senhas, chaves privadas (
-----BEGIN … PRIVATE KEY-----), segredos de nuvem e CI, cookies de sessão. - Arquivos que as contêm:
.env*,*.pem,*.key,id_rsa*,credentials*,secrets*,*.p12, JSON de contas de serviço,.npmrcou.pypirccom tokens, arquivos de configuração local. - Informações pessoais: endereços de email, números de telefone, endereços residenciais ou postais, nomes reais em exemplos ou dados de teste, números de conta ou ID, e dados identificadores de outras pessoas.
- Detalhes da máquina: caminhos home absolutos (
/Users/<nome>,/home/<nome>,C:\Users\<nome>), nomes de host internos, endereços IP privados, nomes de usuário em logs ou saídas de notebook. - Lugares ocultos: saídas e metadados de notebook, logs, capturas de tela, fixtures, relatórios gerados, mensagens de commit e o histórico completo do branch, não apenas seu estado final.
Execute um scanner se o repositório tiver um (gitleaks, detect-secrets, pre-commit run --all-files), e leia o diff você mesmo também; scanners perdem dados pessoais.
Quando encontrar algo:
- Nunca repita o valor no relatório ou em uma mensagem de commit. Nomeie o arquivo, a linha e o tipo de item (
chave AWS,endereço de email). - Ainda não commitado: remova-o, mova-o para um arquivo ignorado ou variável de ambiente, e adicione o padrão ao
.gitignorese for um arquivo. - Já commitado no branch: pare e informe o usuário. Uma credencial que já foi commitada deve ser revogada e substituída, mesmo após reescrever o histórico, porque pode já ter sido copiada. Não reescreva histórico compartilhado sem o usuário.
- Informações pessoais que o usuário colocou ali de propósito (seu próprio nome público em uma licença, por exemplo): pergunte, não remova.
7. Corrigir ou sinalizar
Edite minimamente, na voz, estrutura e terminologia do próprio arquivo. Leia um arquivo completamente antes de editá-lo.
Corrija sem perguntar:
- correções factuais que seguem diretamente do diff;
- nomes, caminhos, contagens, versões e referências cruzadas desatualizados;
- adicionar um novo item a uma tabela ou lista existente;
- conectar um verificador onde seus semelhantes mostram o padrão.
Sinalize ou pergunte antes de alterar:
- texto narrativo, de design ou política, e qualquer coisa que contradiga a intenção aparente do branch;
- remoções e reescritas grandes;
- alterações sensíveis à segurança;
- entradas de
CHANGELOGe bumps de versão; - arquivos de propriedade de outra pessoa ou equipe;
- novos testes que exigem uma decisão de design.
Nunca: reescreva ou regenere entradas de changelog existentes, faça bump de versão silenciosamente, edite manualmente arquivos gerados (use seu gerador), ou cole segredos ou credenciais reais.
8. Verifique com evidências
Nenhuma afirmação sem evidência atualizada desta sessão, após a última edição relevante:
- Nomeie o comando que prova a afirmação.
- Execute-o por completo.
- Leia toda a saída e o código de saída.
- Declare o resultado com essa evidência, ou declare o status real.
Execute o que o repositório já possui: seus testes, linters, pre-commit run --all-files, build da documentação e verificações de links. Uma ferramenta que não está instalada ou um serviço que está indisponível é uma lacuna de verificação, relatada como tal, nunca uma aprovação. "Deve passar" e um "pronto" do agente não são evidências.
9. Relatório
Escopo: <base>..HEAD, N arquivos, M commits
Bloqueante
- path:line — tipo de credencial ou informação pessoal (valor não mostrado), e o que é necessário
Alterado
- path:line — o que mudou e por que o diff exigiu
Sinalizado (não corrigido)
- path:line — o problema, por que não foi corrigido, a correção sugerida
Lacunas de cobertura
- item — onde deveria ser documentado ou testado
Verificado
- `comando` → resultado (código de saída)
Não verificado
- o quê e por quê (ferramenta ausente, serviço externo, precisa de uma decisão)
A camada mecânica
A maior parte das seções 2–6 exige julgamento, mas parte dela pode ser executada em todo commit. Para um repositório sem isso, ofereça a configuração inicial em references/pre-commit-config.yaml: higiene de arquivos, ruff, codespell, detecção de chaves privadas e segredos (gitleaks), e pytest com diff-cover no push. Verificações de link lychee e CI por caminho são melhores em um workflow do que em um hook de commit.
Créditos
Adaptado, com alterações, de skills licenciadas sob MIT: docs-sync e review-test-coverage por Jakub Merta (jMerta/codex-skills); a classificação de diff, mapa de cobertura e regras de corrigir ou sinalizar de document-release por Garry Tan (garrytan/gstack); e a regra de evidência de verification-before-completion por Jesse Vincent (obra/superpowers). Ideias, não texto, dos agentes pr-review-toolkit da Anthropic (anthropics/claude-plugins-official). Licenças: THIRD_PARTY_NOTICES.md.