Back to Details

evidence-backed-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Evidence-Backed Review

基于证据的代码评审

Core principle. Every finding cites what you observed. Every axis you did not inspect is named.
  • A review that inspected nothing reads like a review that found nothing. Only the first line of the report separates them.
  • The weight sits in Verify before critiquing and Finding eligibility. Everything else routes to them, or reports what they produced.
  • You opened this in the middle of something. This is how to do that work, not a replacement for it.
核心原则：每个问题都需引用你的观察结果。需明确列出所有未检查的维度。
  • 未检查任何内容的评审，看起来和未发现问题的评审几乎一样。只有报告的第一行能区分二者。
  • 关键在于「验证后再评判」和「问题筛选标准」。其他所有环节都围绕这两点展开，或是输出它们的结果。
  • 你是中途开启这项工作。这是完成该工作的方法，而非替代原有工作。

The request sets the floor

需求设定评审底线

Write the request down as the task list before matching a single row. One item per thing it named, in its words. Rows from the table below are added to that list, never substituted for it.
  • A list built from this gate answers this gate. Six things were asked for and the table has ten rows, so a list built from rows is complete and wrong.
  • Everything the request named is owed back by name, each one found or each one reported as not inspected. An axis it named with no rule here is still owed.
  • Read the list again before the report. By then the range, the diff and ten rules have been in front of you, and those six things have not.
  • Cheap evidence crowds out what matters. A local run is one command away and a pipeline is not, so the near one gets cited and the far one dropped. Distance is not a reason, and a green suite says it ran, not that the change was worth making.
先将需求转化为任务清单，再匹配任何规则条目。需求中提到的每一项单独列为一条，保留原表述。仅将下表中的条目添加到该清单中，绝不替换原有内容。
  • 基于规则生成的清单只能回应规则本身。如果需求包含6项内容，而表格有10条规则，那么仅基于规则生成的清单看似完整实则偏离需求。
  • 需求中提到的所有内容都需逐一反馈，要么说明已发现问题，要么说明未检查该内容。即使需求提到的维度没有对应规则，也需反馈。
  • 撰写报告前再次核对需求清单。此时你已查看过变更范围、diff和十条规则，很可能已遗忘需求中的6项内容。
  • 易获取的证据会掩盖关键问题。本地运行只需一条命令，而流水线验证则不然，因此人们往往会引用本地结果而忽略流水线结果。距离远近不能成为理由，测试套件显示通过仅代表运行完成，不代表变更有价值。

Read-only guard

只读防护规则

  • You MUST NOT mutate anything: not the working tree, the index, the current commit, or a branch. Inspect another revision in a separate worktree.
  • Send nothing. No comment on the change request, no work item, no notification, no commit.
  • Report a finding, never apply it. This holds when the fix is one character.
  • 严禁修改任何内容：包括工作区、索引、当前提交或分支。如需检查其他版本，请在独立工作区进行。
  • 不发送任何内容：不针对变更请求发表评论、不创建工作项、不发送通知、不提交代码。
  • 仅报告问题，绝不直接修复：即使修复只需修改一个字符也需遵守此规则。

Mode selection

模式选择

ModeThe request looks likeBudget and output
review
judging a change that already exists as commits: a branch, an open change request, "review since 
<point>
", including your own		every gated axis → verify each finding → severity-ordered, for a reader who did not write the code
pre-commit
work not yet committed: "check this before I commit", a dirty or staged treeevery gated axis, most reshapable first → re-verify after each code move → blocking-first actions
focused
another task surfaced one review risk and nobody asked for a review1 rule → no status → findings plus the axes left uninspected
  • Stay quiet on a range already reviewed with nothing changed since.
  • Stay quiet on a 
    focused
    risk the user already declined.
模式需求特征预算与输出
review
评审已提交为commit的变更：分支、已开启的变更请求、“评审自
<point>
以来的内容”，包括你自己的变更		检查所有 gated 维度 → 验证每个问题 → 按严重程度排序，面向未编写代码的阅读者
pre-commit
未提交的工作内容：“提交前帮我检查”、未提交或已暂存的代码检查所有 gated 维度，优先处理可重构内容 → 每次代码调整后重新验证 → 优先列出阻塞性操作
focused
其他任务暴露了一个评审风险，但无人要求完整评审仅检查1条规则 → 不输出整体状态 → 报告问题及未检查的维度
  • 对于已评审过且未发生变更的范围，无需重复评审。
  • 如果用户已拒绝
    focused
    模式下的风险点，无需再提及    。

Detect the range before anything else

先确定变更范围

  • Never ask what the revision history answers. Base is the point named in the request, otherwise the trunk merge-base.
  • Read the range as 
    <point>...<tip>
    .     Three dots compares against the merge-base.
  • In 
    pre-commit
    the range is the staged content against the current commit.
  • Name unstaged edits separately. Never judge them as if they were landing.
  • Confirm the point resolves and the range is non-empty before any further work.
  • Read the declared build and test result for this range first, then open 
    rules/execution-and-pipeline.md
    for what to do with it.
    • A failure is the review's first finding, labelled relayed. It was reported to you, not observed by you.
    • A check nobody ran is a Gap.
  • 绝不询问可通过修订历史回答的问题。基准点为需求中指定的点，否则默认为主干的合并基准点。
  • 将变更范围读作
    <point>...<tip>
    。三个点表示与合并基准点对比。
  • 在
    pre-commit
    模式下，变更范围为已暂存内容与当前commit的对比    。
  • 单独列出未暂存的修改。绝不将其视为即将落地的变更进行评判。
  • 先确认基准点可解析且变更范围非空，再开展后续工作。
  • 先查看该范围的已声明构建和测试结果，再打开
    rules/execution-and-pipeline.md
    了解后续操作。
    • 测试失败是评审的第一个问题，标记为“转述”。该结果是他人报告给你的，而非你亲自观察到的。
    • 未执行的检查项属于“空白项（Gap）”。

Which rules to read

需阅读的规则

This table is a gate, not a checklist. Match the left column against the diff and the request.
  • Read every rule whose signal is present in this range.
  • Report an axis whose signal is absent as not-applicable. Name the signal that would have triggered it.
  • Where a signal is ambiguous you SHOULD read the rule. Under-reading is the expensive mistake, and a range that changed a boundary and produced nothing was scoped wrong.
  • You MAY read a second row whose signal is weaker when the change looks larger than it reads.
  • Escalate coverage mid-run when something turns up. Never reduce it.
  • focused
    reads one matched row     whatever the signals say, names the rest as uninspected, and says so.
  • The unconditional walk is the waste, not the checks it protects. Reading every rule on every change spends nine reads on a three-line diff.
If you see...Read
the request is "before I commit" / "check this first"; nothing pushed, tree dirty or staged
rules/pre-commit-self-review.md
authentication, a permission or role check, user input reaching a query, path, command or template, a file upload, an ownership check, a secret-shaped literal, or a new outbound call
rules/security-and-abuse-paths.md
any hunk changing a condition, a bound, an assignment, or an error path; lines deleted or replaced
rules/correctness-in-the-diff.md
the range is pushed or open as a change request, the repository declares a workflow, build, or deploy, or the request named execution, a run, or a pipeline
rules/execution-and-pipeline.md
the diff adds a capability nobody asked for in the request, issue, or spec
rules/motivation-and-necessity.md
one diff both restructures and adds behaviour; unrelated files, or ~1000 changed lines in one change
rules/scope-and-slicing.md
new code deviating from a written convention, in this repository or one the organisation documents elsewhere
rules/standards-conformance.md
a quoted requirement with no matching code, code no requirement mentions, or a changed behaviour whose only proof is that a test did not throw
rules/spec-conformance.md
a changed exported signature, route, schema, event payload, config key, or a removed field
rules/contracts-and-consumers.md
a README, doc page, example, comment, or repository-local instruction file still describing behaviour this diff changed
rules/docs-and-skills-freshness.md
callers of that changed contract living outside this package who must act, or feature-specific logic landing in a shared module
rules/dependent-teams.md
a security, network, data-handling, or cost question this repository never answers; a surface another team documents or consumes elsewhere
rules/external-sources.md
Discriminators.
  • Standards against security: a convention departed from, against a caller who can reach what they should not.
  • Standards against docs: which side is wrong, the new code or the prose gone stale behind it.
  • Contracts against dependent teams: is the boundary change safe, against who outside must act.
  • Standards against spec: what was written down, against what was asked.
  • Standards against external sources: where the rule lives, never whether it counts.
Default stance.
  • Report, never edit. The working tree ends the run exactly as it started.
  • Every finding lands at 
    file:line
    , and every axis you did not inspect is named as not inspected.
  • One status, decided by the weakest axis, never by the count of clean ones.
此表是筛选门限，而非检查清单。将左列内容与diff和需求匹配。
  • 阅读所有信号出现在当前变更范围内的规则。
  • 将信号未出现的维度报告为“不适用”。需说明触发该维度的信号类型。
  • 若信号模糊，应阅读对应规则。漏读会导致严重错误，若变更涉及边界调整却未产生任何结果，说明范围界定有误。
  • 当变更实际规模大于表面显示时，可阅读第二条信号较弱的规则。
  • 评审过程中发现问题时，需扩大覆盖范围。绝不缩小范围。
  • focused
    模式仅阅读匹配的一条规则    ，无论信号如何，其余维度均标记为未检查并说明。
  • 无差别阅读所有规则是浪费时间，而非必要检查。每次变更都阅读所有规则，对于三行代码的diff来说，会浪费九次规则阅读的时间。
若你发现...阅读对应规则
需求为“提交前帮我检查”/“先检查这个”；代码未推送、工作区未提交或已暂存
rules/pre-commit-self-review.md
身份验证、权限或角色检查、用户输入传入查询/路径/命令/模板、文件上传、所有权检查、类似密钥的字面量、或新的外部调用
rules/security-and-abuse-paths.md
任何代码块修改了条件、边界、赋值或错误路径；存在代码删除或替换
rules/correctness-in-the-diff.md
变更范围已推送或作为变更请求开启，仓库声明了工作流、构建或部署流程，或需求提到了执行、运行或流水线
rules/execution-and-pipeline.md
diff添加了需求、工单或规格中未提及的功能
rules/motivation-and-necessity.md
单次diff同时重构代码并添加新行为；涉及无关文件，或单次变更修改了约1000行代码
rules/scope-and-slicing.md
新代码偏离了书面约定（本仓库或组织其他文档中记录的约定）
rules/standards-conformance.md
引用的需求无对应代码实现，代码实现无对应需求描述，或变更行为仅通过测试未报错来证明
rules/spec-conformance.md
已导出的签名、路由、 schema、事件 payload、配置项被修改，或字段被移除
rules/contracts-and-consumers.md
README、文档页面、示例、注释或仓库本地说明文件仍描述着已被diff修改的行为
rules/docs-and-skills-freshness.md
被修改契约的调用方位于当前包外且必须做出调整，或特定功能逻辑被加入共享模块
rules/dependent-teams.md
本仓库未明确的安全、网络、数据处理或成本问题；涉及其他团队维护或使用的接口
rules/external-sources.md
判别准则
  • 规范 vs 安全：偏离规范的代码是否会导致调用方访问到不应访问的内容。
  • 规范 vs 文档：新代码与过时文档哪一方存在错误。
  • 契约 vs 依赖团队：边界变更是否安全，哪些外部方必须做出调整。
  • 规范 vs 需求：书面约定与实际需求是否一致。
  • 规范 vs 外部资源：规则的来源，而非规则是否有效。
默认立场
  • 仅报告，绝不修改。工作区在评审结束时需与开始时完全一致。
  • 所有问题均标注
    file:line
    ，所有未检查的维度均需明确说明。
  • 整体状态由最薄弱的维度决定，而非无问题维度的数量。

Verify before critiquing

验证后再评判

  • Confirm a finding before reporting it. Reproduce it, or read the actual code path.
  • Emit exactly one label: 
    confirmed-with-code-path
    , 
    plausible-mechanism
    , 
    not-reproduced
    , 
    insufficient-detail
    .
  • plausible-mechanism
    is a defect you can name a path to but cannot run here:     a race, a nil on a rare but reachable branch, zero treated as absent, an off-by-one on a bound nothing excludes.
  • Report it with the state that would produce it. Never refute it for failing to reproduce; that is what the label is for.
  • not-reproduced
    and 
    insufficient-detail
    are Gaps or Questions.
  • 报告问题前需先确认。重现问题，或阅读实际代码路径。
  • 仅输出一个标签：
    confirmed-with-code-path
    、
    plausible-mechanism
    、
    not-reproduced
    、
    insufficient-detail
    。
  • plausible-mechanism
    指可描述问题路径但无法在此处重现的缺陷    ：竞态条件、罕见分支上的空值、零被视为缺失、边界上的差一错误等。
  • 报告时需说明触发问题的状态。绝不能因无法重现就否定问题，标签已对此做出区分。
  • not-reproduced
    和
    insufficient-detail
    属于空白项（Gap）或疑问    。

Finding eligibility

问题筛选标准

  • Candidates MUST be gathered without this gate. Apply the gate only when you decide what to report.
  • Filtering while you look is the dominant cause of misses. The same pass that finds a defect talks itself out of it.
  • All five hold, or it is not reported at all, and it is not downgraded to a Nit.
  1. It touches changed code, or code reachable from changed code.
  2. It states a concrete impact path: what breaks, leaks, slows, or rots.
  3. It cites an exact 
    file:line
    .
  4. The recommended fix is smaller than the problem it solves.
  5. No existing guard, type, or caller already handles it. Say which one you checked.
Severity: Critical (fix now), Important (before merge), Optional, Nit, Question.
  • A Nit is never Critical.
  • Important covers dead code, a test asserting only that nothing threw, and gratuitous 
    any
    .
  • One structural problem plus ten nits means the structural problem is the review.
  • 候选问题必须在门限筛选前收集。仅在决定报告内容时应用门限。
  • 边检查边筛选是遗漏问题的主要原因。发现缺陷的同时又自我说服忽略该缺陷。
  • 必须同时满足以下五点才会被报告，且不能降级为“小问题（Nit）”。
  1. 涉及已修改代码或从已修改代码可访问的代码。
  2. 明确说明具体影响路径：什么会崩溃、泄露、变慢或腐化。
  3. 引用精确的
    file:line
    。
  4. 建议的修复方案比问题本身更简洁。
  5. 现有防护、类型检查或调用方未处理该问题。需说明你检查了哪些防护措施。
严重程度：Critical（立即修复）、Important（合并前修复）、Optional（可选修复）、Nit（小问题）、Question（疑问）。
  • Nit永远不会是Critical。
  • Important包括：死代码、仅断言未报错的测试、不必要的
    any
    类型。
  • 一个结构性问题加十个小问题，意味着评审重点是结构性问题。

The four words for a claim

表述结论的四个术语

  • Confirmed. Observed directly, cited.
  • Inference. Reasoned from something Confirmed.
  • Gap. Not found or not verified. State the next concrete observation and nothing else.
  • Recommendation. Never proof.
  • Where nothing records the fact at all, say so and name who could answer. A gap no observation can close is a question, not a search.
  • A claim at one layer is never evidence for a deeper one. The ladder is owned by 
    rules/contracts-and-consumers.md
    , and authority written outside this repository by 
    rules/external-sources.md
    .
  • Quantify every claim: a count, a 
    file:line
    , a measured value.
  • Evidence has to reach the reader. A path is evidence only if the person reading the report can open it. Otherwise quote the line.
  • Confirmed（已确认）：直接观察到并引用的事实。
  • Inference（推断）：基于已确认事实推理得出的结论。
  • Gap（空白项）：未发现或未验证的内容。仅说明下一步需观察的具体内容。
  • Recommendation（建议）：绝非证据。
  • 完全无记录的事实：需说明情况及可回答的人员。无法通过观察填补的空白项属于疑问，而非待搜索内容。
  • 某一层级的结论不能作为更深层级的证据。层级关系由
    rules/contracts-and-consumers.md
    定义，仓库外的权威内容由
    rules/external-sources.md
    定义。
  • 所有结论需量化：数量、
    file:line
    、测量值。
  • 证据需能被读者获取。代码路径只有在报告阅读者可打开查看时才属于证据，否则需引用具体代码行。

End with exactly one status

最终输出一个状态

  • PASS
    .     Every gated axis was inspected and nothing eligible was found.
  • ISSUES_FOUND
    .     At least one eligible finding.
  • INCOMPLETE
    .     Something in scope could not be inspected. Name it, name what blocked it, and list what you tried before calling it blocked.
  • There is no partial pass. A false 
    PASS
    ships broken code. A false 
    ISSUES_FOUND
    costs one more human look, and the asymmetry is not close.
  • One item you cannot resolve stops the run.
  • focused
    emits no overall status.     It reports its findings, names the axes it did not inspect, hands the interrupted task back, and offers a full mode when a second risk appears.
  • Zero findings is a scope error on a range that changed a boundary, altered a convention, or passed ~300 lines. Re-scope and re-run.
  • PASS
    ：所有gated维度均已检查，未发现符合标准的问题。
  • ISSUES_FOUND
    ：至少发现一个符合标准的问题。
  • INCOMPLETE
    ：部分范围内内容无法检查。需说明无法检查的内容、阻塞原因及你尝试过的解决方法。
  • 不存在部分通过的情况。错误的
    PASS
    会导致有问题的代码上线。错误的
    ISSUES_FOUND
    仅需多一次人工检查，二者的影响差异极大。
  • 无法解决的问题会终止评审。
  • focused
    模式不输出整体状态    。仅报告发现的问题、未检查的维度，将未完成的任务交回，并在出现第二个风险点时建议切换为完整模式。
  • 若变更涉及边界调整、修改约定或超过300行代码却未发现任何问题，属于范围错误。需重新界定范围并重新评审。

Output contract

输出约定

review        Scope: base…tip, file count, commit summary
              Axes: reviewed | not-applicable + the absent signal | evidence-unavailable
              Findings: severity · file:line · impact path · fix
              Gaps: each stating the next observation that would close it
              Teams to notify: who and why, identified, not notified
              Sound: what was checked and found sound
pre-commit    Actions: blocking first, each with file:line
              Draft description: claim · source of the requirement · alternative rejected · what is out of scope
focused       Risk inspected, findings, and the axes left out: no verdict
  • Report two channels, not one. Findings pass the gate. Noticed is ungated: if it made you pause, it goes there, unranked and unresolved.
  • Every finding is location, impact, fix.
  • Every mode closes asserting nothing was mutated: no file, comment, work item, commit, deployment, or mirror synced.
  • A full mode also closes with the run status.
review        Scope: base…tip, file count, commit summary
              Axes: reviewed | not-applicable + the absent signal | evidence-unavailable
              Findings: severity · file:line · impact path · fix
              Gaps: each stating the next observation that would close it
              Teams to notify: who and why, identified, not notified
              Sound: what was checked and found sound
pre-commit    Actions: blocking first, each with file:line
              Draft description: claim · source of the requirement · alternative rejected · what is out of scope
focused       Risk inspected, findings, and the axes left out: no verdict
  • 报告分为两个部分：符合门限的问题；Noticed（注意到）：未通过门限但引起你注意的内容，无需排序和解决。
  • 每个问题需包含位置、影响、修复方案。
  • 所有模式结束时需声明未修改任何内容：无文件、评论、工作项、提交、部署或镜像同步被修改。
  • 完整模式结束时需输出运行状态。

Delegating a check

委托检查

  • A subagent receives the pre-built diff, pinned range, and explicit constraint. Never your conclusion, never pre-judged bias, and never session history.
  • Mandate anti-suppression: its prompt instructs reporting all observations and modifying nothing.
  • What returns is evidence to re-check against the code, never a verdict.
  • It opens no further seat. Re-running an unchanged artifact past a fresh reviewer is stalling, not diligence.
  • 子代理需接收预生成的diff、固定的范围和明确的约束。绝不传递你的结论、预判断的偏见或会话历史。
  • 强制要求反压制：提示需指示子代理报告所有观察结果且不修改任何内容。
  • 返回的内容是需与代码重新核对的证据，绝非最终结论。
  • 无需重复委托。将未变更的内容交给新评审者重新检查属于拖延，而非尽职。

Do not skip this when

以下情况绝不能跳过评审

  • The change is three lines. A three-line diff removes a guard as easily as a large one.
  • You wrote it yourself. That is the case the reader trusts most and checks least.
  • The tests are green. They may not reach the changed line.
  • You are in a hurry. That is when a false clean bill costs the most.
  • 变更仅涉及三行代码。三行代码的diff同样可能移除安全防护，与大规模变更无异。
  • 代码由你自己编写。这种情况最容易被读者信任且最少被检查。
  • 测试全部通过。测试可能未覆盖到变更的代码行。
  • 你时间紧迫。此时错误的无问题报告代价最大。

Routing

流程指引

  • Read a selected rule in full. Say which one you opened, in one line, and interpret it yourself.
  • A direct instruction from the user outranks anything here, including a 
    hard-gate
    .
  • 完整阅读选定的规则。用一句话说明你打开了哪条规则，并自行解读。
  • 用户的直接指令优先级高于任何内容，包括
    hard-gate
    规则。