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

模式选择

Mode	The request looks like	Budget 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 tree	every 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 review	1 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.

It touches changed code, or code reachable from changed code.
It states a concrete impact path: what breaks, leaks, slows, or rots.
It cites an exact
```
file:line
```
.
The recommended fix is smaller than the problem it solves.
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）”。

涉及已修改代码或从已修改代码可访问的代码。
明确说明具体影响路径：什么会崩溃、泄露、变慢或腐化。
引用精确的
```
file:line
```
。
建议的修复方案比问题本身更简洁。
现有防护、类型检查或调用方未处理该问题。需说明你检查了哪些防护措施。

严重程度：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
```
规则。