Revisão de Mudanças de Código

Revise uma mudança de código (diff local, alterações em staged, branch, intervalo de commits ou pull request) quanto à correção, segurança, desempenho, confiabilidade, compatibilidade, altitude, duplicação, simplicidade e qualidade de teste, com verificações específicas de linguagem carregadas apenas para as linguagens que a mudança toca, e reporte cada achado como um comentário marcado com [CRÍTICO], [MAJOR], [MENOR] ou [NIT] com o problema, por que ele importa e uma sugestão de correção.

O que é Revisão de Mudanças de Código?

Esta skill capacita agentes de IA a realizar revisões de código completas e especializadas, imitando a abordagem de um engenheiro sênior experiente. Ela é essencial para desenvolvedores que desejam garantir que suas mudanças de código sejam corretas, seguras e bem estruturadas antes de mesclar ou implantar. A skill suporta diversas plataformas de desenvolvimento, incluindo Git, GitHub e GitLab, através de comandos como `git diff`, `gh` (GitHub CLI) e `glab` (GitLab CLI). O processo de revisão é altamente estruturado: primeiro, identifica precisamente o conjunto de mudanças (como alterações não commitadas, branch atual ou um pull request específico). Em seguida, carrega guias de referência específicos da linguagem de programação identificada nas mudanças para aplicar as melhores práticas e detectar armadilhas comuns. Cada achado é verificado rigorosamente para evitar falsos positivos, e o relatório final é organizado por gravidade, usando tags como [CRÍTICO] e [MAJOR], com explicações claras do problema e sugestões acionáveis de correção. O agente também considera o contexto além do diff, lendo código circundante, convenções do projeto e dependências, garantindo uma revisão profunda e relevante.

Funciona com✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/OMG-Software/code-change-review-skill/tree/HEAD/skills/code-change-review

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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.

AlvoComo obter
Trabalho não commitadogit diff HEAD (plus git status para arquivos não rastreados, depois os leia)
Apenas stagedgit diff --cached
Branch atualgit diff $(git merge-base HEAD <base>) onde <base> geralmente é main/master
Intervalo de commitsgit 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íficosLeia-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ão origin:

    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 .headRefOid
    

    Se 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 com git show refs/review/pr-<n>:<caminho> e compare com $(git merge-base refs/review/pr-<n> <remote>/<base>). Use gh 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> --comments mostra 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}}}}}}}'
    

    --paginate segue as threads além das primeiras 100. Uma thread cujo comments.totalCount é maior que 100 tem mais respostas; busque-as com node(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 alteradosLeia
.py, .pyi, .pyw, .ipynb, pyproject.toml, setup.py, setup.cfg, requirements.txt, Pipfile, Pipfile.lock, poetry.lock, uv.lockreferences/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.jsonreferences/languages/javascript-typescript.md
.go, go.mod, go.sum, go.workreferences/languages/go.md
.rs, Cargo.toml, Cargo.lockreferences/languages/rust.md
.java, .kt, .kts, .scala, .sc, .groovy, .gradle, pom.xml, build.gradle, settings.gradle, gradle.propertiesreferences/languages/java-kotlin.md
.cs, .fs, .fsx, .vb, .csproj, .fsproj, .vbproj, .sln, .razor, .cshtml, Directory.Build.props, Directory.Packages.props, NuGet.config, global.jsonreferences/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.jsonreferences/languages/c-cpp.md
.rb, .erb, .rake, .gemspec, .ru, Gemfile, Gemfile.lock, Rakefile, config.rureferences/languages/ruby.md
.php, .phtml, composer.json, composer.lockreferences/languages/php.md
.swift, .pbxproj, Package.swift, Package.resolved, Podfilereferences/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, .cmdreferences/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 shebangLeia
pythonreferences/languages/python.md
node, deno, bun, ts-node, tsxreferences/languages/javascript-typescript.md
rubyreferences/languages/ruby.md
phpreferences/languages/php.md
sh, bash, zsh, ksh, dash, fish, pwshreferences/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.

  1. 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.
  2. É seguro enviar? Segurança, compatibilidade de API/esquema/wire, integridade de dados e migrações, operabilidade (rollout, rollback, observabilidade), novas dependências, privacidade.
  3. É 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.
  4. 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 sua arquivo: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.

Habilidades Relacionadas