代码变更审查 是做什么的?
像资深工程师一样审查变更:找出真正重要的缺陷,逐个证明,并以能让作者快速行动的方式报告。一个包含三个真实错误的简短审查胜过三十个可能的问题,因为每个误报都会让读者学会略读。
工作流程
1. 确定变更集
在阅读任何代码之前,精确确认正在审查的内容。如果用户未指定,默认审查尚未合并到基础分支的所有内容。
| 审查目标 | 获取方法 |
|---|---|
| 未提交的工作 | git diff HEAD(同时使用 git status 查找未跟踪文件,然后读取它们) |
| 仅暂存的更改 | git diff --cached |
| 当前分支 | git diff $(git merge-base HEAD <base>),其中 <base> 通常是 main/master |
| 提交范围 | git diff A..B |
| 拉取请求(编号或 URL) | gh pr view <n-or-url> 获取描述、基础分支和头部;gh pr diff <n-or-url> 获取差异;gh pr diff <n-or-url> --name-only 获取文件列表 |
| 特定文件 | 读取它们;如有必要,询问它们与之前的差异 |
拉取请求。“Review PR 123”或“review PR #123”表示当前仓库中的 PR 123。URL(https://github.com/<owner>/<repo>/pull/<n>)可以直接传递给 gh,并且可以从任何目录工作,即使针对其他仓库。对于 GitLab 合并请求,使用 glab mr view / glab mr diff。仅差异不足以提供上下文(第 3 步),因此还需要读取 PR 版本的文件:
-
如果 PR 来自当前仓库,在不切换分支的情况下获取它及其基础分支,并将其放入一个专用引用中,该引用会被强制更新,以便重新整理的 PR 替换之前审查的任何副本。从指向 PR 基础仓库的远程仓库获取(检查
git remote -v);在 fork 中,这通常是upstream,而不是origin:git fetch <remote> <base> +refs/pull/<n>/head:refs/review/pr-<n> git rev-parse refs/review/pr-<n> # 必须等于:gh pr view <n> --json headRefOid --jq .headRefOid如果获取失败或提交不匹配
headRefOid,则停止并告知用户,而不是审查错误或过时的副本。然后使用git show refs/review/pr-<n>:<path>读取文件,并与$(git merge-base refs/review/pr-<n> <remote>/<base>)比较。仅当用户不介意工作目录发生变化时,才使用gh pr checkout <n>。 -
对于其他仓库,通过
gh api "repos/<owner>/<repo>/contents/<path>?ref=<head-sha>"(需要引号,因为?在 zsh 中是通配符)读取 PR 头部的文件,或者如果审查需要大量上下文,则将其克隆到临时目录。 -
阅读已有的反馈,以避免重复已提出、已回答或已解决的问题。
gh pr view <n> --comments仅显示顶级注释;内联审查线程、回复及其解决状态来自 GraphQL:gh api graphql --paginate -F owner=<owner> -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会跟进超过前 100 个线程。如果线程的comments.totalCount超过 100,则还有更多回复;在依赖它之前,使用node(id:<thread id>){... on PullRequestReviewThread{comments(first:100,after:<cursor>){…}}}获取它们。
同时获取意图:PR 描述、提交消息、关联的问题,或者如果不存在,则用一句话询问用户。如果不了解代码的预期目的,就无法判断其是否正确。
对于非常大的变更(超过约 1500 行更改),首先进行分类。按风险对文件进行排序(身份验证、支付、数据迁移、并发、公共 API 以及任何删除的内容优先于文档、生成的代码和锁定文件),并说明哪些文件仅进行了简要审查。
2. 加载变更涉及的语言参考
仅加载变更集中涉及的语言和文件类型的参考文件,绝不加载全部。每个文件都会增加上下文,从而挤占正在审查的代码。
如果 Python 可用(python 或 python3),则运行检测器:
python <skill-dir>/scripts/detect_languages.py --git <base> # 分支与基础分支比较
python <skill-dir>/scripts/detect_languages.py --git HEAD # 未提交的工作
python <skill-dir>/scripts/detect_languages.py --git <remote>/<base> --head refs/review/pr-<n> # 已获取的 PR
git diff --name-only ... | python <skill-dir>/scripts/detect_languages.py # 任何文件列表
对于拉取请求,使用第 1 步中获取的 ref 作为 --head。然后检测器从 PR 的提交中读取 shebang,而不是从你的工作目录中读取,因为工作目录可能缺少 PR 的新脚本或包含不同版本。对于其他仓库中的 PR,gh pr diff <url> --name-only | python <skill-dir>/scripts/detect_languages.py 提供文件列表,但无法查看文件内容。检查列表中每个无扩展名文件的第一行,无论是否已映射(migrations/ 下的 Python 脚本已映射到 sql.md,但仍需要 python.md):在 PR 头部读取它,或者如果 PR 将其删除,则在基础分支上读取,并对照下面的 shebang 表进行路由。
检测器会打印需要读取的参考文件以及触发每个参考文件的已更改文件。如果没有 Python,请使用此表,它与检测器完全匹配。文件名匹配不区分大小写。
| 已更改的文件 | 读取 |
|---|---|
.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, 以及 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, 以及 .circleci/, .github/workflows/, .github/actions/, k8s/, kubernetes/, helm/, charts/, manifests/, deploy/, deployment/, kustomize/, argocd/ 下的 YAML 文件 | references/languages/infrastructure.md |
没有扩展名的文件根据其 shebang 行的解释器进行路由(#!/usr/bin/env deno,#!/usr/bin/python3)。版本后缀被忽略。
| Shebang 解释器 | 读取 |
|---|---|
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 |
一个文件可能同时需要两份参考。Rails 或 Alembic 迁移需要其语言文件和 sql.md,检测器会同时报告这两者。没有参考文件的语言仍会进行完整审查。下面的通用角度涵盖了它,并且你应该应用你对该语言常见陷阱的了解。嵌入式语言也算:Python 中的 SQL 字符串,或 Go 中构建的 shell 命令,都是加载 sql.md 或 shell.md 的理由。
3. 构建差异之外的上下文
差异显示更改了什么,而不是它影响了什么。在判断任何内容之前:
- 阅读每个差异块周围的代码,而不仅仅是更改的行。许多错误存在于新行与旧行交互的方式中。
- 找到每个更改的函数、类型、模式、配置键或端点的调用者和依赖者(grep,LSP 查找引用)。影响范围在差异中是不可见的。
- 了解项目的约定:linter 和格式化程序配置、
CLAUDE.md/CONTRIBUTING.md,以及附近代码如何处理错误、日志记录和测试。根据此代码库判断一致性,而不是根据个人品味。 - 在接受新的工具代码之前搜索现有的辅助函数。重新实现仓库中已有的内容只有在你查看差异之外时才会暴露出来。
4. 按优先级顺序从不同角度审查
从列表顶部向下工作。第一层中的错误比任意数量的第三层注释都更重要。references/review-angles.md 包含每个角度的完整检查清单;对于任何非平凡的审查,都需要阅读它。
- 是否正确? 正确性和边缘情况、意图符合度(它是否完全按照声称的功能执行?)、错误处理和失败模式、并发和共享状态、对调用者的影响范围。
- 是否安全发布? 安全性、API/模式/有线兼容性、数据完整性和迁移、可操作性(推出、回滚、可观测性)、新依赖项、隐私。
- 是否是好的代码? 性能和效率、抽象层次(修复是否在正确的层次?)、重复和复用、简洁性与过度工程、与约定的一致性、可读性。
- 是否经过验证? 如果没有更改就会实际失败的测试、保持同步的文档和注释。
在这些角度内应用加载的语言文件的检查。它们是该语言中这些问题的具体形式。
5. 在报告之前验证每个发现
对于每个候选发现:
- **编写失败场景:**具体的输入或状态,然后是错误的结果。如果无法编写,则可能不是错误。
- 重新阅读代码以检查问题是否已经处理:上游的保护、验证器、排除其类型的类型、覆盖它的测试。
- 运行它(如果成本低且安全:单元测试、REPL 片段、类型检查器或 linter)并且发现不确定。
- **对置信度进行分级:**确认(追踪或重现)或合理(可信但无法完全证明的路径)。放弃任何更弱的内容。如果某些内容不清楚但提出是无害的,则将其作为问题提出,而不是断言存在错误。
6. 报告
使用 references/reporting.md 获取严重性标签、评论格式和输出模板。简而言之:
- 以一行结论开头:是否可以安全合并,以及最大的问题(如果有)。
- 每个发现都以严重性标签开头:
[CRITICAL]、[MAJOR]、[MINOR]或[NIT],然后是一行声明及其file:line。正文按此顺序解释:问题是什么,为什么它是问题(具体的失败场景),以及建议的修复或改进(如果可行)。 - 按严重性从高到低列出发现。默认上限约为 10。说明遗漏了多少较低严重性的项目,并在用户要求时列出它们。
- 除非没有真正的缺陷,或者用户要求彻底审查,否则不要包含
[NIT]。 - 以你未涵盖的内容结尾(浏览过的文件、无法运行的内容)。诚实的范围说明是审查的一部分。
在拉取请求上发布评论时,使用相同的标签优先格式,以便发现在报告中和 PR 上看起来相同。仅当用户要求时才发布到 PR;references/reporting.md 显示了如何将它们作为一次包含内联注释的审查发布。
如果审查平台提供了结构化发现工具,则按相同顺序通过该工具报告,而不是打印列表,并且仍然以标签开头每个发现的摘要。
原则
- 证据优先于意见。 每个发现都引用代码。“考虑 X”而没有原因是噪音。
- 审查变更,而不是代码库。 仅当更改使现有问题恶化或依赖于它们时,才标记现有问题,并将其标记为预先存在。
- 尊重作者的选择。 不同但同样有效的方法不是发现。仅当可以指出具体成本时才提出异议。
- 除非要求,否则不要在审查期间修复。 建议修复;让用户决定是否应用它们。