review-code
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinesereview-code — one dimension per invocation
review-code — 每次调用仅审查一个维度
Audit a change along one review dimension and report findings. Load only that dimension's reference.
沿一个审查维度审计变更并报告发现。仅加载该维度的参考文档。
Input
输入
$ARGUMENTSdimension=code-bugscode-bugs src/foo.ts$ARGUMENTSdimension=code-bugscode-bugs src/foo.tsDimensions
维度
Before reviewing a change in a project, read the project context file's pointers to principles skills — project skills named holding how the project's people want one area's work done — and load each one for an area the change touches ( → Using one). Load for the requested dimension and follow it. Its standards are opinionated defaults: where a rule the user stated, in the session or a context file, a principle in a loaded principles skill, or a convention the project states or documents (not a pattern its code merely repeats) differs, that rule governs, a change following it raises no finding, and the report names the rule applied — except a Critical finding on the ladder below, which is still reported, naming the rule that produced it. Classify findings by consequence; the caller chooses the acceptance threshold and handling policy.
<area>-principles../setup-project/references/PRINCIPLES_SKILLS.mdreferences/<dimension>.md| Dimension | Reference | Role |
|---|---|---|
| | defect-finder |
| | defect-finder |
| | defect-finder |
| | defect-finder |
| | defect-finder |
| | advisory |
| | advisory |
| | advisory |
| | advisory |
| | advisory |
| | advisory |
| | advisory |
| | advisory |
| | advisory |
Roles define what to look for. Defect-finders report divergences, defects, contract mismatches and type holes with a stated trigger. Advisory dimensions assess product and quality gaps. Both use the shared severity ladder; neither role decides which findings the caller must address.
Some dimensions are conditional, and the caller decides whether they apply before requesting them: where the change touches API surfaces or durable data contracts, on typed code, and where the change fixes a defect. is the one dimension that takes a defect as input rather than producing one as output — it judges the repair's protection against the demonstrated mechanism and accounts for affected sites, so on a change that fixes nothing it has no input and nothing to judge. Requesting it anyway is not an error; it reports no fix found in scope and applies any supplied acceptance policy.
contractstype-safetydefect-classdefect-class在项目中审查变更前,先读取项目上下文文件中指向 principles skills 的指针——这些项目 skill 名为 ,用于说明项目团队希望如何完成某一领域的工作——并针对变更涉及的每个领域加载相应 skill( → 使用一个原则)。加载所请求维度对应的 并遵循其中的说明。其标准是带明确立场的默认值:如果用户在当前会话或上下文文件中声明的规则、已加载 principles skill 中的原则,或项目明示或记录过的约定(不包括代码只是恰好重复的既有模式)与这些标准不同,则以该规则为准;遵循该规则的变更不产生发现,并且报告必须注明所采用的规则——但下文严重性阶梯中的 Critical 发现仍须报告,并注明产生该发现的规则。按后果对发现进行分级;由调用方选择验收阈值和处理策略。
<area>-principles../setup-project/references/PRINCIPLES_SKILLS.mdreferences/<dimension>.md| 维度 | 参考文档 | 角色 |
|---|---|---|
| | defect-finder |
| | defect-finder |
| | defect-finder |
| | defect-finder |
| | defect-finder |
| | advisory |
| | advisory |
| | advisory |
| | advisory |
| | advisory |
| | advisory |
| | advisory |
| | advisory |
| | advisory |
这些角色决定审查内容。Defect-finder 报告差异、缺陷、契约不匹配和类型漏洞,并给出明确的触发条件。Advisory 维度评估产品和质量缺口。两者都使用共享的严重性阶梯;任何一种角色都不决定调用方必须处理哪些发现。
部分维度是有条件的,是否适用由调用方在请求前决定: 适用于变更触及 API surface 或 durable data contract 的场景, 适用于 typed code, 适用于变更修复缺陷的场景。 是唯一以缺陷为输入而非以缺陷为输出的维度;它评估修复对已证实机制的保护效果,并考虑受影响的位置,因此对于未修复任何问题的变更,它没有输入,也没有可评估的内容。即使仍请求该维度也不属于错误;它会报告范围内未发现修复,并应用任何已提供的验收策略。
contractstype-safetydefect-classdefect-classDetermining scope (shared across dimensions)
确定范围(所有维度共用)
For a requested follow-up, the caller supplies the prior assessed state and criteria, findings,
supported dispositions, verified repairs, and changes since that evaluation; use what applies. Criteria
that changed since that evaluation make this a fresh review, scoped as below, since work the old
criteria did not reach has never been reviewed. Otherwise report outstanding findings
and failures introduced or exposed by the intervening changes, with evidence for which prior
findings are repaired. Read context as widely as needed; an old issue on a touched line is not
new merely because the line changed. If the needed prior state is missing, recover it or report
BLOCKED with what is missing, rather than silently reviewing the complete change again. A new ID
or repeated assertion does not reopen an evidenced disposition; changed code, criteria, argument or
evidence can. Assess its support independently rather than requiring agreement with a previous reviewer.
For a fresh review — including a new standalone review when an earlier report exists — resolve its scope as follows:
- Caller specifies files/paths → review exactly those.
- Otherwise → review the complete change. Resolve the comparison base from the PR target or the repository's remote default branch; ask only if neither can be established, and with no one to ask report BLOCKED naming the base that could not be established. Inspect committed changes with , staged changes with
git diff <base>...HEAD, unstaged changes withgit diff --cached, and relevant new files fromgit diff. Read each new file's contents; a path listing alone is not its diff.git ls-files --others --exclude-standard - Empty / non-reviewable diff → ask the caller to clarify scope. With no one to ask, report BLOCKED: the resolved scope holds no reviewable change, and a scope that holds one settles it.
Stay within scope — never audit the whole project unless explicitly asked. Skip generated copies, lock files, vendored dependencies and binaries. Establish which files are generated from the repository's ownership or build rules; a directory named or may also contain source-owned files that need review.
dist/build/Reading scope ≠ reporting scope. The diff bounds what you report (defaults: only issues introduced or exposed by the change). It does not bound what you read — trace mechanisms wherever they lead (existing callers, shared state, upstream writers) so boundary issues between changed and unchanged code stay visible. Read widely; report narrowly. Within the resolved scope, examine every file against every category the loaded reference lists — do not cut corners or skip areas — and report only the findings that clear its bar for reporting (its actionability filter, or for defect-class its acceptance rules).
The Pre-existing list, only when asked. When the caller asks for it on a fresh full look, add a section: issues the loaded dimension owns that you noticed in code you read for the change, that the change neither introduced nor exposed, and that would clear its actionability criteria other than scope: a stated trigger on a defect-finder and a stated cost for a Medium on an advisory dimension. Honor the caller's requested severities and categories; the caller decides how to handle this list. They are not findings: they never count toward the verdict or summary counts. Leave the section out unless asked, and on every follow-up even when asked: a follow-up's scope stays outstanding findings and what the intervening changes introduced or exposed.
## Pre-existingThis skill is read-only: never modify repository files; write analysis artifacts only outside the repository, in the host's temporary location. The author implements fixes from your report.
对于请求的后续审查,调用方会提供先前评估的状态和标准、发现、有证据支持的处置结论、已验证的修复,以及自该次评估以来的变更;其中适用的内容应予采用。如果评估后标准发生变化,则应按下文所述范围将其视为一次全新审查,因为旧标准未覆盖的工作从未被审查过。否则,应报告尚未解决的发现,以及后续变更引入或暴露的失败,并提供证据说明哪些先前发现已得到修复。根据需要广泛读取上下文;触及行发生变更并不会自动使其中的旧问题成为新问题。如果缺少所需的先前状态,应找回该状态,或报告 BLOCKED 并说明缺少什么,而不是悄然重新审查完整变更。新的 ID 或重复的主张不会重新打开已有证据支持的处置;代码、标准、论证或证据发生变化则可以。独立评估其支持依据,而不是要求与上一位审查者达成一致。
对于全新审查——包括已有早期报告时发起的新独立审查——按以下方式确定范围:
- 调用方指定文件或路径 → 仅审查这些文件或路径。
- 否则 → 审查完整变更。从 PR 目标或仓库远端默认分支确定比较基线;仅当两者都无法确定时才询问调用方。若无法询问任何人,则报告 BLOCKED,并说明无法确定的基线。已提交的变更使用 检查,已暂存的变更使用
git diff <base>...HEAD检查,未暂存的变更使用git diff --cached检查,相关新文件使用git diff检查。读取每个新文件的内容;仅列出路径并不等于其 diff。git ls-files --others --exclude-standard - 空白或不可审查的 diff → 请调用方澄清范围。若无法询问任何人,则报告 BLOCKED:解析出的范围不包含可审查变更,而只要范围中存在变更即可解决此问题。
始终留在范围内——除非明确要求,否则绝不审计整个项目。跳过生成副本、锁文件、vendored dependencies 和二进制文件。根据仓库的所有权或构建规则确定哪些文件是生成的;名为 或 的目录也可能包含需要审查的仓库自有源文件。
dist/build/阅读范围 ≠ 报告范围。 diff 限定的是应当报告的内容(默认仅报告变更引入或暴露的问题),而不是可以阅读的内容——应沿着机制追踪至其延伸之处(现有调用方、共享状态、上游写入方),使变更代码与未变更代码交界处的问题保持可见。读取要广泛,报告要聚焦。在解析出的范围内,必须依据已加载参考文档列出的每个类别检查每个文件——不得偷工减料或跳过任何领域——并且只报告达到其报告门槛的发现(即可操作性筛选标准;对于 defect-class,则为其验收规则)。
仅在被要求时提供 Pre-existing 列表。 在调用方要求对全新完整审查提供该列表时,添加 部分:列出你在为变更阅读的代码中注意到的、属于已加载维度且既非由变更引入、也非由变更暴露的问题,并且除范围限制外还满足其可操作性标准——对于 defect-finder,必须有明确的触发条件;对于 advisory 维度,Medium 发现必须指出明确成本。遵循调用方要求的严重性和类别;由调用方决定如何处理此列表。这些内容不属于发现:绝不计入门禁结论或摘要统计。除非调用方明确要求,否则省略该部分;在每次后续审查中,即使调用方提出要求,也应省略,因为后续审查的范围始终限于尚未解决的发现,以及后续变更引入或暴露的问题。
## Pre-existing此 skill 是只读的:绝不修改仓库文件;分析产物只能写入仓库之外的宿主临时位置。修复由报告作者根据审查结果实施。
Severity ladder (shared)
严重性阶梯(共用)
- Critical — data loss, corruption, security breach, or complete failure for all users; no workaround.
- High — correctness, safety, a broken promise, or wrong behavior. Rarity, unusual preconditions and a workaround do not turn a substantive defect into polish.
- Medium — a clear product or quality gap a careful reviewer would insist on fixing before shipping; name the concrete cost.
- Low — polish or a nit of any kind: style, naming, structure, or otherwise.
Grade by consequence, not confidence or frequency. Dimension examples apply this ladder; they cannot lower it. Regrade a correctness or safety failure or broken binding promise received as Low from the evidence before any caller filtering. A binding requirement can concern style, naming or structure. Severity does not decide whether a finding is addressed, posted or blocking: those are caller policies, not part of the Low definition.
- Critical — 数据丢失、数据损坏、安全漏洞,或所有用户完全无法使用;没有变通方案。
- High — 正确性或安全性问题、违背承诺或错误行为。罕见性、不寻常的前置条件或变通方案,都不能将实质性缺陷降格为打磨项。
- Medium — 明确的产品或质量缺口,严谨的审查者会坚持在发布前修复;必须指出具体代价。
- Low — 任何打磨项或吹毛求疵的小问题,例如样式、命名、结构或其他事项。
按后果分级,而不是按信心或频率分级。各维度中的示例均适用此阶梯,但不能借此降低严重性。在调用方筛选之前,应依据证据将任何被定为 Low 的正确性或安全性故障,或违背有约束力承诺的问题重新定级。有约束力的要求也可以涉及样式、命名或结构。严重性不决定某项发现是否需要处理、是否应提交或是否阻塞;这些属于调用方策略,而不属于 Low 的定义。
Caller policy
调用方策略
The Manifest or another caller owns acceptance. For a claim-based gate, a finding fails it when
the evidence establishes a concrete violation of that claim or an applicable source obligation,
including a material quality cost in the artifact's supported use or expected maintenance.
Severity describes consequence; it does not substitute for that argument. A missing criterion
does not erase the requested result or its source obligations: report the coverage gap as well.
Do not turn an unsupported improvement preference into a new obligation.
A deliberately supplied severity or category policy still applies. The same Low may fail a
caller's Low-inclusive gate and pass a different caller's Medium+ gate without changing severity.
Choosing to address a Low does not raise its severity. Report classifications without a verdict
when no gate is requested. If a verdict is requested without an acceptance policy recoverable
from claims or explicit handling instructions, ask for it or report BLOCKED; do not invent a
threshold. Batching, repair scope and final finding dispositions belong to the caller. A caller's
reasoned rejection does not change the claim you assess; on a follow-up it is a supported
disposition unless new evidence reopens it. Evidence that the claim itself is wrong is reported
for the caller, who owns the claim, to change; a real failure or necessary missing evidence
remains unresolved.
Manifest 或其他调用方掌握验收标准。对于基于 claim 的门禁,当证据确立某项发现具体违反了 claim 或适用的来源义务时,该发现即导致门禁失败;这包括产物在实际支持的用途或预期维护中存在实质性质量成本。严重性描述的是后果,不能替代这一论证。缺少某项标准不能消除所请求的结果或其来源义务:还必须报告覆盖缺口。不要将缺乏依据的改进偏好转化为新的义务。
明确提供的严重性或类别策略仍然适用。同一个 Low 可以使包含 Low 的调用方门禁失败,也可以通过另一个 Medium+ 门禁,而无需改变其严重性。选择处理某个 Low 并不会提高其严重性。未请求门禁时,只报告分类结果,不给出结论。如果请求了结论,但无法从 claims 或显式处理说明中恢复验收策略,则应询问调用方或报告 BLOCKED;不得自行设定阈值。批量处理、修复范围和最终发现处置均归调用方所有。调用方有理由地拒绝某项发现,并不会改变所评估的 claim;在后续审查中,该拒绝属于有证据支持的处置,除非新证据将其重新打开。如果证据表明 claim 本身有误,应将其报告给拥有该 claim 的调用方修改;但真实失败或必要证据缺失仍未解决。
Report format (shared)
报告格式(共用)
undefinedundefinedCode Review — <dimension>
Code Review — <dimension>
Dimension: <dimension>
Acceptance policy: [caller-supplied, for a requested gate]
Status: PASS | FAIL | BLOCKED [requested gates only]
Files analyzed: [...]
Dimension: <dimension>
Acceptance policy: [caller-supplied, for a requested gate]
Status: PASS | FAIL | BLOCKED [requested gates only]
Files analyzed: [...]
Prior findings (follow-ups only)
Prior findings (follow-ups only)
- [prior finding]: repaired | rejected with support | unresolved — [evidence; new evidence that reopens it, if any]
- [prior finding]: repaired | rejected with support | unresolved — [evidence; new evidence that reopens it, if any]
Findings
Findings
Finding #1: [title]
Finding #1: [title]
- Location:
file:line - Severity: Critical | High | Medium | Low
- Description: [what's wrong]
- Acceptance basis: [the claim or source obligation contradicted, or the concrete quality cost; identify a proposed improvement as such]
- Trigger: [the condition under which the defect manifests — the concrete input, state, or sequence that produces the failure, or for a static mismatch such as a contract or signature divergence, the call or consumer path that reaches it — required on defect-finder dimensions]
- Impact: [what it breaks / why it matters — a Medium finding must name the concrete cost that earns that grade: the future change it makes harder, the reader or operator task it defeats, or the condition under which behavior degrades]
- Recommended fix: [specific change]
- Location:
file:line - Severity: Critical | High | Medium | Low
- Description: [what's wrong]
- Acceptance basis: [the claim or source obligation contradicted, or the concrete quality cost; identify a proposed improvement as such]
- Trigger: [the condition under which the defect manifests — the concrete input, state, or sequence that produces the failure, or for a static mismatch such as a contract or signature divergence, the call or consumer path that reaches it — required on defect-finder dimensions]
- Impact: [what it breaks / why it matters — a Medium finding must name the concrete cost that earns that grade: the future change it makes harder, the reader or operator task it defeats, or the condition under which behavior degrades]
- Recommended fix: [specific change]
Pre-existing (only when the caller asked, on a fresh full look)
Pre-existing (only when the caller asked, on a fresh full look)
- [title] — — [the issue, with its trigger or cost] — [recommended fix]
file:line
- [title] — — [the issue, with its trigger or cost] — [recommended fix]
file:line
Summary
Summary
- Critical: N | High: N | Medium: N | Low: N
- Verdict (requested gates only): apply the caller's acceptance policy to the classified findings.
An empty report is a valid, expected outcome. Do not invent findings to fill it.- Critical: N | High: N | Medium: N | Low: N
- Verdict (requested gates only): apply the caller's acceptance policy to the classified findings.
空报告是有效且预期的结果。不要为填充报告而编造发现。Verifier contract (PASS / FAIL / BLOCKED)
验证器契约(PASS / FAIL / BLOCKED)
When invoked as a gate with the caller's acceptance policy, end with one verdict:
- PASS — the evidence supports the assessed claims under the caller's policy, with no unresolved contradictory finding or material uncertainty.
- FAIL — evidence establishes a failure under that policy; name the defeated claim or explicitly required threshold. The findings are evidence for the caller to assess, not authority to add requirements.
- BLOCKED — necessary evidence or authority is missing (e.g., the change can't be located, a needed external doc is unreachable). Say what remains unverified and what would settle it. An empty findings list alone does not prove the claim.
使用调用方的验收策略作为门禁调用时,最后必须给出一个结论:
- PASS — 在调用方策略下,证据支持所评估的 claims,且不存在尚未解决的矛盾性发现或实质性不确定性。
- FAIL — 证据确立了该策略下的失败;指出被违反的 claim 或明确要求的阈值。各项发现是供调用方评估的证据,而不是添加要求的权威。
- BLOCKED — 缺少必要的证据或权威,例如无法定位变更,或无法访问所需的外部文档。说明仍未验证的内容以及什么条件可以解决此问题。仅凭发现列表为空不能证明 claim 成立。
Gotchas
注意事项
- One ref only. Load exactly the reference for the requested dimension. Loading several defeats progressive disclosure and blurs the orthogonality boundaries each dimension defines against its neighbors.
- Classify before policy. A Low label never discharges a correctness or safety failure or a broken binding promise. Check the consequence before applying the caller's policy.
- Reportability is a stated trigger, not a confidence level (defect-finders). Name the condition under which the defect manifests: "this WILL fail when X", with X written down. Where the defect is static rather than sequential — a contract or signature mismatch that is wrong on every call — the trigger is the call or consumer path that reaches it. A finding that cannot name its trigger is not reportable however strongly you suspect it — "this might be a bug", "this looks fragile", "this could break under load" all fail the test. Someone reading only the finding must be able to tell whether it clears this bar, which is what holds the bar in one place across reviewers rather than moving it with whoever is reading. A stated trigger is necessary rather than sufficient — each dimension's own bar for reporting (its actionability filter, or for defect-class its acceptance rules) still applies on top of it.
- A Medium is a stated cost, not a strength of feeling (all dimensions). Name the cost in the finding — the change made harder, the task defeated, the condition under which behavior degrades — specifically enough that someone reading only the finding can tell the grade is earned. A finding whose case rests on "could be cleaner", "feels off", or "not ideal" has not named one, and sits at Low. Each dimension's own calibration still applies on top.
- Stay inside the loaded dimension. Each reference lists what it owns and what belongs to a sibling dimension. A maintainability smell is not a bug; a type hole is not a design critique. Report only what the loaded dimension owns; let the other dimensions' invocations catch the rest.
- 只加载一个 ref。 仅加载所请求维度对应的参考文档。加载多个文档会破坏渐进式披露,并模糊每个维度与相邻维度之间所定义的正交边界。
- 先分类,再应用策略。 Low 标签绝不能豁免正确性或安全性故障,也不能豁免违背有约束力承诺的问题。应用调用方策略前,先检查后果。
- 可报告性取决于明确触发条件,而不是信心水平(defect-finder)。必须指出缺陷出现的条件:“这将在 X 时失败”,并明确写出 X。如果缺陷是静态而非顺序相关的——例如每次调用都不匹配的契约或签名差异——触发条件就是到达该差异的调用或消费路径。无法指出触发条件的发现不可报告,无论对其问题的怀疑有多强烈——“这可能是个 bug”“这看起来很脆弱”“这在负载下可能会出错”均未达到该标准。仅阅读发现内容的人必须能够判断它是否达到这一标准,而这正是审查者之间不随人员变化而漂移的固定门槛。明确触发条件是必要条件,但并非充分条件——还必须满足各维度自身的报告门槛,即可操作性筛选标准,或 defect-class 的验收规则。
- Medium 意味着明确代价,而不是感觉强烈(所有维度)。必须在发现中指出代价——变更让什么变得更困难、破坏了读者或操作人员的什么任务,或行为在什么条件下会退化——并具体到仅阅读该发现的人就能判断这一等级是否成立。依据“可能不够整洁”“感觉不对”或“不太理想”而成立的问题,应归为 Low。各维度自身的校准规则仍需在此基础上适用。
- 留在已加载维度的范围内。 每个参考文档都列出了其负责的内容以及属于其他维度的内容。可维护性异味不是 bug,类型漏洞也不是设计批评。只报告已加载维度负责的问题;其余问题应由其他维度的调用处理。