Back to Details

code-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Review

代码评审

Use this capability whenever you review a code change — a pull request, a branch or commit-range diff, or your own work before you call it done — whatever the change type, language, or domain. The skill is self-contained: every rule it needs lives here, so it stays correct when installed on its own without any companion skill. When the host project ships its own code-review guideline or posted-review policy, defer to it for project-specific rules and precedence; the methodology here still applies in full wherever that project guidance is silent.
A review has one job — decide whether a change is safe to merge and say why, with evidence — and one output: a report. It does not rewrite the code. Keep finding problems separate from fixing them.
Review target. The target is the change already under review: the working tree against the base branch by default, or a specific pull-request reference, branch name, or commit range when one is named. Establish the diff for that target before reading anything else (see scoping.md).
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
每当你评审代码变更时均可使用此能力——无论是pull request、分支或提交范围差异，还是在完成工作前对自己的成果进行评审——无论变更类型、语言或领域如何。该技能独立封装：所需的所有规则均包含于此，因此无需搭配其他技能，单独安装即可正常使用。若宿主项目有自己的代码评审指南或已发布的评审政策，则项目特定规则和优先级以其为准；在项目指南未提及的场景下，本方法论完全适用。
评审的核心目标只有一个——判断变更是否可以安全合并，并给出循证依据——输出形式为一份报告。评审不涉及代码重写，需将问题排查与代码修复分开进行。
评审目标：评审对象为已提交的变更内容：默认情况下是基于基准分支的工作树，若指定了具体的pull request引用、分支名称或提交范围，则以指定内容为准。在查看其他内容前，先确定该目标的差异范围（详见 scoping.md）。
本文档中的关键词「MUST」「MUST NOT」「REQUIRED」「SHALL」「SHALL NOT」「SHOULD」「SHOULD NOT」「RECOMMENDED」「MAY」和「OPTIONAL」的解释遵循 RFC 2119。

The Review Loop

评审循环

Every review runs the same loop: reset into reviewer mode, scope the change from its diff, assess that diff through the review lenses, classify each finding by severity, report with evidence, and escalate anything too risky to self-approve. The reset is what makes the rest trustworthy — the reviewer inspects what the code does, as if someone else wrote it, instead of re-affirming the reasoning that produced it; this matters most in self-review, where the author and reviewer are the same agent. Do not read any code before the reset — it is the first normative step, owned by scoping.md. The sections below route to the reference that owns each step, ordered as a review applies them.
每次评审都遵循相同流程：切换至评审模式、从差异中界定变更范围、通过评审视角评估差异、按严重程度分类每个问题、循证报告、将高风险问题升级至无法自行批准的层级。模式切换是确保后续评审可信度的关键——评审者需审视代码的实际功能，仿佛代码由他人编写，而非重复验证自己编写代码时的思路；这在自我评审中尤为重要，因为此时作者与评审者为同一人。在完成模式切换前，请勿查看任何代码——这是首个规范性步骤，具体内容由 scoping.md 定义。以下章节按评审流程顺序，指向各步骤对应的参考文档。

Review Scoping

评审范围界定

See scoping.md for:
  • performing the reviewer-mode reset and establishing scope from 
    git status
    / 
    git diff
    / a PR diff
  • distinguishing in-scope (the diff) from out-of-scope (pre-existing) code
  • reading the full file and every caller/callee around a changed hunk
  • handling untracked files, an empty or unclear diff, and generated / tool-managed files
详见 scoping.md：
  • 执行评审模式切换，并通过 
    git status
    / 
    git diff
    / PR差异确定范围
  • 区分范围内（差异部分）与范围外（已存在）的代码
  • 阅读完整文件及变更代码块的所有调用方/被调用方
  • 处理未跟踪文件、空或不清晰的差异，以及生成/工具管理的文件

Severity Classification

严重程度分类

See severity.md for:
  • the Critical / Major / Minor / Nit definitions, each pairing a merge impact with a defect class
  • the fixed severity floors for categories such as committed secrets, missing access control, unsanitized input, and introduced test or lint failures
  • mapping severity counts to an Approve / Approve with Nits / Request Changes verdict
  • resolving uncertain severity by escalating upward and stating the assumption
详见 severity.md：
  • 关键/主要/次要/细微问题（Critical / Major / Minor / Nit）的定义，每个级别对应合并影响与缺陷类型
  • 针对已提交密钥、缺失访问控制、未净化输入、引入测试或 lint 失败等类别的固定严重程度下限
  • 将严重程度计数映射为「批准/带细微问题批准/要求修改」的评审结论
  • 通过向上升级并说明假设来解决不确定的严重程度

What to Flag: Review Lenses

需标记的内容：评审视角

See review-lenses.md for:
  • the correctness lens: logic errors, edge cases, error and async handling, contract changes
  • the maintainability lens: naming, organization, abstraction boundaries, complexity, dead code, scope discipline
  • the security and privacy lens: secrets, input validation, access control, injection, SSRF, auth, data exposure, supply chain
  • the testing and verification lens: coverage, stable test hooks, snapshots, flakiness, manual checks
  • the performance and reliability lens: data-access cost, concurrency, caching, asset and bundle weight, failure modes
详见 review-lenses.md：
  • 正确性视角：逻辑错误、边缘情况、错误与异步处理、契约变更
  • 可维护性视角：命名、组织、抽象边界、复杂度、死代码、范围规范
  • 安全与隐私视角：密钥、输入验证、访问控制、注入攻击、SSRF、认证、数据泄露、供应链
  • 测试与验证视角：覆盖率、稳定测试钩子、快照、不稳定测试、人工检查
  • 性能与可靠性视角：数据访问成本、并发、缓存、资源与包体积、故障模式

Evidence and Reporting

证据与报告

See evidence-and-reporting.md for:
  • the mandatory 
    file:line
    citation on every finding and quoting the offending code
  • diff-style (
    -
    /
    +
    ) fix snippets for every Critical and Major finding
  • the exact review-report section order, from Summary through Recommended Actions
  • what counts as evidence versus assertion, and how to mark findings the reviewer could not verify
详见 evidence-and-reporting.md：
  • 每个问题必须包含 
    file:line
    引用，并引用有问题的代码
  • 所有关键和主要问题需提供差异格式（
    -
    /
    +
    ）的修复片段
  • 评审报告的确切章节顺序，从摘要到建议操作
  • 区分证据与断言，以及如何标记评审者无法验证的问题

Review Tone

评审语气

See tone.md for:
  • addressing the code, not the author, and stating the concrete risk behind each finding
  • acknowledging real strengths without inflating trivial ones
  • keeping style and preference out of blocking severities
  • flagging assumptions explicitly and leaving human-authored copy to its authors
详见 tone.md：
  • 针对代码而非作者，说明每个问题背后的具体风险
  • 认可真正的优势，而非夸大无关紧要的优点
  • 避免将风格和偏好列为阻塞性严重程度问题
  • 明确标记假设，将人工撰写的文案交由原作者处理

Escalation and Decisions

升级与决策

See escalation.md for:
  • keeping the review reporting-only — no code mutation, no delegating the review away
  • making each fix trivially applicable and pairing it with its verification step
  • escalating high-risk changes to an external gate instead of self-approving them
  • deferring genuine trade-offs back to the caller as enumerated Decision-needed entries
详见 escalation.md：
  • 评审仅负责报告——不修改代码，不委托评审工作
  • 确保每个修复易于应用，并搭配对应的验证步骤
  • 将高风险变更升级至外部审批环节，而非自行批准
  • 将真实的权衡问题以「需决策」条目形式反馈给发起方

Posted and CI Reviews

已发布与CI评审

See posted-review-policy.md for:
  • when a review is posted to a pull request (a CI reviewer or a managed review product) rather than kept as internal self-review
  • collapsing the internal four-tier triage to a two-label Important / Nit report with a one-line tally
  • running the repository's mandatory checks and honoring its do-not-report exclusions
  • keeping a posted review advisory: comment-only, never an approving or blocking formal review
详见 posted-review-policy.md：
  • 何时将评审发布至pull request（由CI评审工具或托管评审产品执行），而非仅作为内部自我评审
  • 将内部四级分类简化为「重要/细微问题」双标签报告，并附上一行摘要
  • 运行仓库的强制检查，遵守其不报告的排除规则
  • 已发布的评审仅作为建议：仅可添加评论，不得给出批准或阻塞的正式评审结论