review-code

review-code — 每次调用检查一个维度

沿一个审查维度审查变更并报告发现项。仅加载该维度的参考资料。

输入

$ARGUMENTS 包含维度和可选范围，例如 dimension=code-bugs 或 code-bugs src/foo.ts。调用方若要求给出门禁结论，还应提供待评估的声明，以及任何明确要求的严重性、类别或审批策略。Manifest 门禁包含其声明和来源权威性；其 Evidence 指明维度。如果未提供维度，列出可用维度并询问选择哪一个——一次调用，一个维度。如果无人可询问，则报告 BLOCKED：未指定维度；指定一个即可解决此问题。

维度

在审查项目中的变更之前，先阅读项目上下文文件中指向原则技能的内容——原则技能是名为 <area>-principles 的项目技能，说明项目成员希望如何完成某个领域的工作——并为变更涉及的每个领域加载相应技能（../setup-project/references/PRINCIPLES_SKILLS.md → Using one）。加载请求维度对应的 references/<dimension>.md 并遵循其中的要求。其标准是带有明确倾向的默认值：如果用户在会话或上下文文件中说明的规则、已加载原则技能中的原则，或项目明确说明或记录的惯例（而非仅仅是代码中重复出现的模式）与某项标准不同，则以该规则为准；遵循该规则的变更不应产生发现项，报告中应说明所采用的规则——但下文等级划分中的 Critical 发现项仍须报告，并注明产生该发现项的规则。根据后果对发现项分类；由调用方选择验收阈值和处理策略。

维度	参考资料	职责
change-intent	references/change-intent.md	缺陷发现
code-bugs	references/code-bugs.md	缺陷发现
contracts	references/contracts.md	缺陷发现
type-safety	references/type-safety.md	缺陷发现
defect-class	references/defect-class.md	缺陷发现
operational-readiness	references/operational-readiness.md	建议
code-design	references/code-design.md	建议
code-maintainability	references/code-maintainability.md	建议
code-simplicity	references/code-simplicity.md	建议
code-testability	references/code-testability.md	建议
test-quality	references/test-quality.md	建议
docs	references/docs.md	建议
prose-value	references/prose-value.md	建议
context-file-adherence	references/context-file-adherence.md	建议

职责决定检查重点。缺陷发现维度报告偏差、缺陷、契约不匹配和类型漏洞，并说明触发原因。建议维度评估产品和质量方面的差距。两类维度都使用通用严重性等级；都不决定调用方必须处理哪些发现项。

部分维度有适用条件，调用方应在请求前决定是否适用：变更涉及 API 接口或持久化数据契约时适用 contracts；类型化代码适用 type-safety；修复缺陷时适用 defect-class。defect-class 是唯一一个以缺陷为输入而非产出缺陷的维度——它会根据已证实的机制评估修复的防护能力，并考虑受影响位置，因此对于未修复任何问题的变更，它没有输入，也无从评估。即使仍然请求该维度也不会报错；它会报告范围内未发现修复，并应用任何已提供的验收策略。

确定范围（适用于所有维度）

对于请求的后续审查，调用方会提供先前评估的状态和标准、发现的问题、支持的处置结论、已验证的修复，以及自该次评估以来的变更；请使用适用的信息。若标准自该次评估以来发生变化，则应按下文所述重新审查，因为旧标准未覆盖的工作从未经过审查。否则，报告尚未解决的问题，以及中间变更引入或暴露的故障，并提供证据说明哪些先前的问题已修复。按需广泛阅读上下文；某个旧问题出现在修改过的行上，并不意味着它仅因该行发生变化就成了新问题。如果缺少必要的先前状态，请找回该状态，或报告 BLOCKED 并说明缺少什么，而不是悄悄重新审查全部变更。新的 ID 或重复的断言不会重新开启已有证据支持的处置结论；代码、标准、论据或证据发生变化则可能重新开启。请独立评估其依据是否充分，而不要求与先前审查者的意见一致。

对于重新审查（包括已有早期报告时进行的新独立审查），请按以下方式确定范围：

1. 调用方指定文件／路径 → 仅审查这些文件／路径。
2. 否则 → 审查完整变更。根据 PR 目标分支或仓库的远程默认分支确定比较基准；只有在两者都无法确定时才询问。若无人可询问，则报告 BLOCKED，并指出无法确定的基准。检查已提交的变更，使用 git diff <base>...HEAD；检查已暂存的变更，使用 git diff --cached；检查未暂存的变更，使用 git diff；并检查相关的新文件，使用 git ls-files --others --exclude-standard。阅读每个新文件的内容；仅列出路径并不等同于查看其差异。
3. 差异为空／不可审查 → 请调用方明确范围。若无人可询问，则报告 BLOCKED：已确定的范围内没有可审查的变更；若范围包含可审查的变更，则可解决此问题。

请勿超出范围——除非明确要求，否则绝不审查整个项目。跳过生成的副本、锁文件、供应商依赖项和二进制文件。根据仓库的所有权或构建规则确定哪些文件是生成的；名为 dist/ 或 build/ 的目录也可能包含由源代码所有者维护、需要审查的文件。

阅读范围 ≠ 报告范围。 差异限定了你报告的内容（默认情况下，仅报告由变更引入或暴露的问题）。它不限制你阅读的范围——应沿着机制继续追踪，无论追踪到哪里（现有调用方、共享状态、上游写入方），以便发现变更代码与未变更代码之间的边界问题。广泛阅读；聚焦报告。在已确定的范围内，依据已加载参考资料列出的每个类别检查每个文件——不得走捷径或跳过任何方面——并且仅报告达到其报告门槛的问题（其可采取行动性筛选标准；对于缺陷类，则遵循其验收规则）。

仅在受要求时列出既有问题。 如果调用方在一次全量重新审查中要求列出，则添加 ## Pre-existing 部分：列出你在阅读变更时查看的代码中注意到、由已加载维度负责、既未由该变更引入也未被该变更暴露，且除范围条件外符合其可采取行动性标准的问题：缺陷查找者需有明确的触发条件；建议性维度中的 Medium 级问题需有明确的成本。遵循调用方要求的严重级别和类别；由调用方决定如何处理此列表。这些不是发现的问题：绝不计入判定或摘要计数。除非调用方要求，否则不要添加此部分；对于每次后续审查，即使调用方要求，也不要添加：后续审查的范围仍仅限于尚未解决的问题，以及中间变更引入或暴露的问题。

此技能为只读：绝不修改仓库文件；仅在仓库之外的主机临时位置写入分析材料。作者会根据你的报告实施修复。

严重程度阶梯（通用）

• Critical — 数据丢失、损坏、安全漏洞，或所有用户都无法使用；且没有变通方案。
• High — 正确性、安全性、违背承诺或行为错误。问题罕见、前置条件特殊或存在变通方案，都不能把实质性缺陷降格为润色问题。
• Medium — 明确的产品或质量缺口，谨慎的评审者会坚持要求在发布前修复；请指出具体代价。
• Low — 任何类型的润色或小问题：风格、命名、结构或其他方面。

按后果分级，而非按置信度或发生频率分级。各维度示例适用此阶梯，不能降低严重程度。若根据证据发现，在任何调用方筛选前，正确性或安全性问题或具有约束力的承诺违背被评为 Low，应重新分级。具有约束力的要求可以涉及风格、命名或结构。严重程度不决定某项发现是否会被处理、发布或阻断：这些属于调用方策略，并非 Low 定义的一部分。

调用方策略

Manifest 或其他调用方负责验收。对于基于声明的门禁，若证据证实具体违反了该声明或适用的来源义务（包括在产物受支持的用途或预期维护中造成重大质量代价），则该发现会导致门禁不通过。严重程度描述后果，不能取代上述论证。缺少某项标准并不会消除所请求的结果或其来源义务：也要报告覆盖缺口。不要把缺乏依据的改进偏好变成新的义务。

明确提供的严重程度或类别策略仍然适用。相同的 Low 发现可以导致某调用方的包含 Low 的门禁不通过，也可以通过另一调用方的 Medium 及以上门禁，而严重程度不变。选择处理 Low 不会提高其严重程度。未要求给出结论时，只报告分类。若要求给出结论，但无法从声明或明确的处理说明中还原验收策略，则应询问，或报告 BLOCKED；不要自行设定门槛。批量处理、修复范围和最终发现处置均由调用方决定。调用方有理有据的驳回不会改变你评估的声明；在后续跟进中，除非新证据重新开启该问题，否则该驳回属于有依据的处置。若证据表明声明本身有误，应报告给负责该声明的调用方，由其修改；真实存在的问题或必要但缺失的证据仍未解决。

报告格式（通用）

# Code Review — <dimension>

**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 finding]: repaired | rejected with support | unresolved — [evidence; new evidence that reopens it, if any]

## Findings
### 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]

## Pre-existing (only when the caller asked, on a fresh full look)
- [title] — `file:line` — [the issue, with its trigger or cost] — [recommended fix]

## Summary
- Critical: N | High: N | Medium: N | Low: N
- Verdict (requested gates only): apply the caller's acceptance policy to the classified findings.

空报告是有效且预期的结果。不要为了填充报告而凭空编造发现。

验证器约定（PASS / FAIL / BLOCKED）

作为门禁调用时，应依据调用方的验收策略，以以下一种结论结束：

• PASS — 证据支持按调用方策略评估的声明，且不存在尚未解决的矛盾性发现或重大不确定性。
• FAIL — 证据证实不符合该策略；指出被否定的声明或明确要求的门槛。发现只是供调用方评估的证据，无权据此增加要求。
• BLOCKED — 缺少必要证据或权限（例如无法定位变更，或无法访问所需的外部文档）。说明哪些内容尚未核实，以及需要什么才能确定。仅有一份空的发现列表，并不能证明该声明成立。

注意事项

• 每次只加载一个参考。 针对所请求的维度，恰好加载对应的参考。加载多个参考会破坏渐进式披露，并模糊各维度与相邻维度之间的正交边界。
• 先分类，再应用策略。 Low 标签不能免除正确性或安全性问题，也不能弥补未兑现的绑定承诺。应用调用方的策略前，先检查后果。
• 可报告性取决于明确陈述的触发条件，而非置信度（缺陷发现者）。指出缺陷出现的条件：“当 X 时，这一定会失败”，并明确写出 X。如果缺陷是静态的，而非顺序相关的——例如每次调用都不正确的契约或签名不匹配——那么触发条件就是能够触达它的调用或使用方路径。无法指出触发条件的发现不能报告，无论你有多怀疑——“这可能是个 Bug”“这看起来很脆弱”“高负载下可能会出问题”都不符合要求。只阅读该发现的人必须能够判断它是否达到这一门槛；这样才能让不同审查者遵循同一标准，而不是让标准随着阅读者而变化。明确陈述触发条件是必要条件，而非充分条件——仍须满足各维度自身的报告门槛（可操作性筛选标准，或缺陷类的验收规则）。
• Medium 代表明确指出的代价，而非主观感受的强烈程度（适用于所有维度）。在发现中指出代价——具体说明这项更改会增加什么难度、会妨碍什么任务，或行为会在什么条件下退化；细致到只阅读该发现的人就能判断这个等级是否合理。若某项发现的依据只是“可以更简洁”“感觉不对”或“不够理想”，就没有指出代价，应归为 Low。除此之外，仍须遵循各维度自身的校准标准。
• 不要超出已加载维度的范围。 每份参考都会列出自身负责的内容，以及属于相邻维度的内容。可维护性问题不等于 Bug；类型缺口不等于设计批评。只报告已加载维度负责的内容；其余问题留给其他维度的调用来发现。