O que Revisão de Mudanças de Código faz?
Revise uma mudança da forma que um engenheiro sênior forte faria: encontre os defeitos que realmente importam, prove cada um e os reporte para que o autor possa agir rapidamente. Uma revisão curta com três bugs reais é melhor do que uma longa com trinta talvez, porque todo falso positivo ensina o leitor a folhear.
Fluxo de Trabalho
1. Determine o conjunto de mudanças
Descubra exatamente o que está sob revisão antes de ler qualquer código. Se o usuário não disse, o padrão é tudo o que ainda não está na branch base.
| Alvo | Como obter |
|---|---|
| Trabalho não commitado | git diff HEAD (plus git status para arquivos não rastreados, depois os leia) |
| Apenas staged | git diff --cached |
| Branch atual | git diff $(git merge-base HEAD <base>) onde <base> geralmente é main/master |
| Intervalo de commits | git diff A..B |
| Pull request (número ou URL) | gh pr view <n-ou-url> para a descrição, base e head; gh pr diff <n-ou-url> para o diff; gh pr diff <n-ou-url> --name-only para a lista de arquivos |
| Arquivos específicos | Leia-os; pergunte do que eles mudaram se for relevante |
Pull requests. "Review PR 123" ou "review PR #123" significa PR 123 no repositório atual. Uma URL (https://github.com/<dono>/<repo>/pull/<n>) pode ser passada para gh como está, e funciona de qualquer diretório, mesmo para outro repositório. Para um merge request do GitLab use glab mr view / glab mr diff. O diff sozinho não é contexto suficiente (passo 3), então leia também as versões dos arquivos do PR:
-
Se o PR for do repositório atual, busque-o e sua base sem trocar de branch, em uma ref dedicada que é forçada a ser atualizada para que um PR com rebase substitua qualquer cópia de uma revisão anterior. Busque do remote que aponta para o repositório base do PR (verifique
git remote -v); em um fork isso geralmente éupstream, nãoorigin:git fetch <remote> <base> +refs/pull/<n>/head:refs/review/pr-<n> git rev-parse refs/review/pr-<n> # deve ser igual a: gh pr view <n> --json headRefOid --jq .headRefOidSe a busca falhar ou o commit não corresponder a
headRefOid, pare e diga isso em vez de revisar a cópia errada ou desatualizada. Em seguida, leia os arquivos comgit show refs/review/pr-<n>:<caminho>e compare com$(git merge-base refs/review/pr-<n> <remote>/<base>). Usegh pr checkout <n>apenas se o usuário não se importar que sua árvore de trabalho mude. -
Para outro repositório, leia os arquivos no head do PR através de
gh api "repos/<dono>/<repo>/contents/<caminho>?ref=<head-sha>"(com aspas, já que?é um caractere glob no zsh), ou clone para um diretório temporário se a revisão precisar de muito contexto. -
Leia o feedback existente para não repetir o que já foi levantado, respondido ou resolvido.
gh pr view <n> --commentsmostra apenas comentários de nível superior; as threads de revisão inline, suas respostas e se cada uma está resolvida vêm do GraphQL:gh api graphql --paginate -F owner=<dono> -F repo=<repo> -F n=<n> -f query='query($owner:String!,$repo:String!,$n:Int!,$endCursor:String){repository(owner:$owner,name:$repo){pullRequest(number:$n){reviewThreads(first:100,after:$endCursor){pageInfo{hasNextPage endCursor} nodes{id isResolved isOutdated path line comments(first:100){totalCount nodes{author{login} body}}}}}}}'--paginatesegue as threads além das primeiras 100. Uma thread cujocomments.totalCounté maior que 100 tem mais respostas; busque-as comnode(id:<thread id>){... on PullRequestReviewThread{comments(first:100,after:<cursor>){…}}}antes de confiar nela.
Também obtenha a intenção: a descrição do PR, mensagens de commit, issue vinculada, ou pergunte ao usuário em uma linha se nenhuma existir. Você não pode julgar se o código está certo sem saber o que ele deve fazer.
Para mudanças muito grandes (mais de ~1.500 linhas alteradas), faça uma triagem primeiro. Classifique os arquivos por risco (auth, pagamentos, migrações de dados, concorrência, APIs públicas e qualquer coisa deletada vêm antes de documentação, código gerado e lockfiles) e diga quais arquivos receberam uma passada mais leve.
2. Carregue orientações de linguagem para o que a mudança toca
Carregue apenas os arquivos de referência para linguagens e tipos de arquivo no conjunto de mudanças, nunca todos. Cada arquivo adiciona contexto que compete com o código que você está revisando.
Execute o detector se Python estiver disponível (python ou python3):
python <skill-dir>/scripts/detect_languages.py --git <base> # branch vs base
python <skill-dir>/scripts/detect_languages.py --git HEAD # trabalho não commitado
python <skill-dir>/scripts/detect_languages.py --git <remote>/<base> --head refs/review/pr-<n> # PR buscado
git diff --name-only ... | python <skill-dir>/scripts/detect_languages.py # qualquer lista de arquivos
Para um pull request, use --head com a ref buscada no passo 1. O detector então lê shebangs do commit do PR, não da sua árvore de trabalho, que pode não ter os novos scripts do PR ou conter versões diferentes deles. Para um PR em outro repositório, gh pr diff <url> --name-only | python <skill-dir>/scripts/detect_languages.py fornece a lista de arquivos, mas não pode ver o conteúdo dos arquivos. Verifique a primeira linha de cada arquivo sem extensão na lista, mapeado ou não (um script Python sob migrations/ já está mapeado para sql.md mas ainda precisa de python.md): leia-o no head do PR, ou na base se o PR o deletar, e roteie-o com a tabela de shebang abaixo.
Ele imprime os arquivos de referência a serem lidos e quais arquivos alterados acionaram cada um. Sem Python, use esta tabela, que corresponde exatamente ao detector. Nomes de arquivo correspondem sem distinção de maiúsculas/minúsculas.
| Arquivos alterados | Leia |
|---|---|
.py, .pyi, .pyw, .ipynb, pyproject.toml, setup.py, setup.cfg, requirements.txt, Pipfile, Pipfile.lock, poetry.lock, uv.lock | references/languages/python.md |
.js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, .cts, .vue, .svelte, .astro, package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, tsconfig.json | references/languages/javascript-typescript.md |
.go, go.mod, go.sum, go.work | references/languages/go.md |
.rs, Cargo.toml, Cargo.lock | references/languages/rust.md |
.java, .kt, .kts, .scala, .sc, .groovy, .gradle, pom.xml, build.gradle, settings.gradle, gradle.properties | references/languages/java-kotlin.md |
.cs, .fs, .fsx, .vb, .csproj, .fsproj, .vbproj, .sln, .razor, .cshtml, Directory.Build.props, Directory.Packages.props, NuGet.config, global.json | references/languages/csharp-dotnet.md |
.c, .h, .cc, .cpp, .cxx, .c++, .hpp, .hh, .hxx, .inl, .ipp, .m, .mm, CMakeLists.txt, Makefile, meson.build, conanfile.txt, vcpkg.json | references/languages/c-cpp.md |
.rb, .erb, .rake, .gemspec, .ru, Gemfile, Gemfile.lock, Rakefile, config.ru | references/languages/ruby.md |
.php, .phtml, composer.json, composer.lock | references/languages/php.md |
.swift, .pbxproj, Package.swift, Package.resolved, Podfile | references/languages/swift.md |
.sql, .psql, .pgsql, .ddl, e qualquer arquivo sob migration/, migrations/, migrate/, alembic/versions/, flyway/, liquibase/ | references/languages/sql.md |
.sh, .bash, .zsh, .ksh, .fish, .ps1, .psm1, .psd1, .bat, .cmd | references/languages/shell.md |
.tf, .tfvars, .hcl, .dockerfile, Dockerfile, Dockerfile*, Containerfile, .dockerignore, compose*.yml, compose*.yaml, docker-compose*.yml, docker-compose*.yaml, Chart.yaml, values.yaml, kustomization.yaml, .gitlab-ci.yml, azure-pipelines.yml, bitbucket-pipelines.yml, Jenkinsfile, qualquer arquivo sob .circleci/, e YAML sob .github/workflows/, .github/actions/, k8s/, kubernetes/, helm/, charts/, manifests/, deploy/, deployment/, kustomize/, argocd/ | references/languages/infrastructure.md |
Um arquivo sem extensão é roteado pelo interpretador em sua linha shebang (#!/usr/bin/env deno, #!/usr/bin/python3). Sufixos de versão são ignorados.
| Interpretador shebang | Leia |
|---|---|
python | references/languages/python.md |
node, deno, bun, ts-node, tsx | references/languages/javascript-typescript.md |
ruby | references/languages/ruby.md |
php | references/languages/php.md |
sh, bash, zsh, ksh, dash, fish, pwsh | references/languages/shell.md |
Um arquivo pode precisar de duas referências. Uma migração Rails ou Alembic precisa do arquivo de linguagem e sql.md, e o detector reporta ambos. Uma linguagem sem arquivo de referência ainda recebe uma revisão completa. Os ângulos gerais abaixo a cobrem, e você deve aplicar o que sabe sobre as armadilhas comuns dessa linguagem. Linguagens embutidas também contam: strings SQL em Python, ou comandos shell construídos em Go, são um motivo para carregar sql.md ou shell.md.
3. Construa contexto além do diff
O diff mostra o que mudou, não o que afeta. Antes de julgar qualquer coisa:
- Leia o código circundante de cada hunk, não apenas as linhas alteradas. Muitos bugs vivem em como novas linhas interagem com as antigas.
- Encontre chamadores e dependentes de cada função, tipo, esquema, chave de configuração ou endpoint alterado (grep, LSP find-references). O raio de explosão é invisível a partir do diff.
- Aprenda as convenções do projeto: configurações de linter e formatador,
CLAUDE.md/CONTRIBUTING.md, e como o código próximo lida com erros, logging e testes. Julgue a consistência com relação a esta base de código, não contra o gosto geral. - Procure por helpers existentes antes de aceitar novo código utilitário. Reimplementar algo que o repositório já tem só aparece quando você olha fora do diff.
4. Revise por ângulo, em ordem de prioridade
Trabalhe do topo desta lista para baixo. Um bug no nível 1 importa mais do que qualquer número de notas do nível 3. references/review-angles.md tem a lista de verificação completa para cada ângulo; leia-a para qualquer revisão não trivial.
- Está certo? Correção e casos de borda, fidelidade à intenção (faz o que afirma, completamente?), tratamento de erros e modos de falha, concorrência e estado compartilhado, raio de explosão nos chamadores.
- É seguro enviar? Segurança, compatibilidade de API/esquema/wire, integridade de dados e migrações, operabilidade (rollout, rollback, observabilidade), novas dependências, privacidade.
- É bom código? Desempenho e eficiência, altitude (a correção está na camada certa?), duplicação e reuso, simplicidade versus engenharia excessiva, consistência com convenções, legibilidade.
- Está verificado? Testes que realmente falhariam sem a mudança, documentação e comentários mantidos em sincronia.
Aplique as verificações do arquivo de linguagem carregado dentro desses ângulos. Elas são as formas específicas que esses problemas assumem nessa linguagem.
5. Verifique cada achado antes de reportá-lo
Para cada achado candidato:
- Escreva o cenário de falha: entrada ou estado concreto, depois o resultado errado. Se não conseguir, provavelmente não é um bug.
- Releia o código para verificar se o problema já não é tratado: uma guarda upstream, um validador, um tipo que o descarta, um teste que o cobre.
- Execute-o onde isso é barato e seguro (um teste unitário, um snippet REPL, o type checker ou linter) e o achado é incerto.
- Classifique a confiança: Confirmado (rastreado ou reproduzido) ou Plausível (caminho crível que você não pôde provar completamente). Descarte qualquer coisa mais fraca. Se algo não está claro, mas é inofensivo de levantar, faça como uma pergunta em vez de afirmar um bug.
6. Reporte
Use references/reporting.md para as tags de gravidade, o formato do comentário e o template de saída. Em suma:
- Comece com um veredito de uma linha: se é seguro mesclar, e o maior problema, se houver.
- Cada achado começa com sua tag de gravidade:
[CRÍTICO],[MAJOR],[MENOR]ou[NIT], depois uma afirmação de uma linha e suaarquivo:linha. O corpo explica, nesta ordem, qual é o problema, por que é um problema (o cenário de falha concreto) e uma sugestão de correção ou melhoria sempre que você puder oferecer uma. - Liste os achados com os mais graves primeiro. Limite padrão de cerca de 10. Mencione quantos itens de gravidade inferior você deixou de fora, e liste-os se o usuário perguntar.
- Mantenha
[NIT]s de fora a menos que não haja defeitos reais, ou o usuário tenha pedido uma passada completa. - Termine com o que você não cobriu (arquivos folheados, coisas que você não pôde executar). Uma nota de escopo honesta faz parte da revisão.
Use o mesmo formato de tag-primeiro para comentários postados em um pull request, para que um achado seja lido da mesma forma no relatório e no PR. Poste no PR apenas quando o usuário solicitar; references/reporting.md mostra como postá-los como uma única revisão com comentários inline.
Se o host fornecer uma ferramenta de achados estruturados, reporte através dela na mesma ordem em vez de imprimir a lista, e ainda assim comece o resumo de cada achado com sua tag.
Princípios
- Evidência sobre opinião. Cada achado cita código. "Considere X" sem uma razão é ruído.
- Revise a mudança, não a base de código. Sinalize problemas pré-existentes apenas quando a mudança os piora ou depende deles, e rotule-os como pré-existentes.
- Respeite as escolhas do autor. Uma abordagem diferente, mas igualmente válida, não é um achado. Discorde apenas quando puder nomear um custo concreto.
- Não corrija durante a revisão a menos que solicitado. Sugira correções; deixe o usuário decidir se quer aplicá-las.