code-review

代码审查

沿两个相互独立的维度审查差异，每个维度由自己的子 Agent 执行：

• 规范 — 代码是否遵循此仓库记录的约定，并避免基线中列出的常见问题？
• 规格 — 代码是否按要求逐项实现了各项需求？

这两个维度刻意分开，因为一项变更可能通过其中一个维度，却未能通过另一个：代码无懈可击，却实现了错误的功能；或者实现忠实于需求，却违背了仓库约定。合并报告会让一个维度掩盖另一个维度的问题。

1. 固定范围 — 尽早失败

使用调用方提供的基准引用（sha、分支、标签或 merge-base）。确认它能解析——git rev-parse <base>——且 git diff <base>...HEAD 非空。错误的引用或空差异必须在这里失败，而不能等到两个并行子 Agent 开始运行时才失败。另请获取 git log <base>..HEAD --oneline。如果没有提供基准引用，请询问。完成条件：引用可解析，且差异非空。

2. 定位规格

按以下顺序查找适用的需求：

1. 提交中的需求 ID 尾注（Implements:、Guards:）——功能代码通过 docs/specs/INDEX.md 对应到规格文件夹。
2. 与分支或功能名称匹配的 docs/specs/<date>-<feature>/requirements.md。
3. 调用方提供的路径。
4. 否则询问用户。如果用户确认不存在规格，则跳过规格维度，并在最终报告中说明。

完成条件：拿到 requirements.md 路径，或明确确认“无规格”。

3. 收集规范来源

收集所有说明此处代码应如何编写的文档：CLAUDE.md、lint 和 formatter 配置、CONTRIBUTING 类文档，以及记录仓库规范用语的 CONTEXT.md。如果缺少 docs/agents/project.md，请注明并建议运行 setup-repo，然后根据现有内容继续。如果存在 ## Team，且其中包含非空的 roster 或 band 覆盖项，则从该部分读取 band 和 packaging：双维度审查始终适用；Solo 报告需针对独立作者；Small/Multi 需重点关注路径归属，并在存在归属说明时加以参考。缺少 Team → 使用功能开发前的默认设置。

除仓库自身文档外，规范维度始终包含与本文件同目录的 standards-baseline.md——其中列出十二种代码质量常见问题，即使仓库未记录任何规范也适用；此外还包含一个在差异跨越信任边界时适用的安全章节。以下两条规则具有约束力：仓库中记录的规范始终优先于基线；每项基线问题都只能作为带标签的判断意见，绝不能视为硬性违规。跳过工具已强制执行的内容——审查者重复 linter 的检查只会制造噪声。完成条件：已掌握来源列表和基线文件路径。

3a. 检查是否与现有功能重复

针对差异中变更的源文件（取自第 1 步固定的范围），在 docs/specs/ 中搜索已提及这些路径的规格——对 design.md/tasks.md 执行 grep -rl <changed-file> docs/specs，并在 requirements.md 中搜索与差异关键概念相关的术语。阅读任何匹配项，并将其整理成摘要卡片（功能代码、所属路径、范围外内容）。从 docs/specs/INDEX.md 开始查阅注册表。此步骤绝不会阻止审查：如果任何规格都未提及变更文件，请说明没有现有功能与此差异的作用范围重叠，且不要向第 4 步注入任何内容；如果 docs/specs/ 不存在，请注明并继续。完成条件：已掌握重叠功能的摘要卡片，或明确确认“无重叠”。

3b. 不变量符合性（建议性）

当 docs/architecture/ 存在时，必须使用 check-invariants 检查差异——它会针对每个 Respects: ARCH-N 给出判定（符合 / 违反 / 不明确）。将“违反”或“不明确”的判定留待第 5 步处理。此检查路径在设计上仅供参考，且不属于两个硬性维度——绝不会成为合并阻塞因素。如果 docs/architecture/ 不存在，则跳过此步骤，不注入任何内容。完成条件：已掌握不变量判定，或明确确认“无架构主干”。

4. 并行调度两个子 Agent

发送一条消息，其中包含两项调度，让它们并发运行，且彼此的上下文互不干扰。两者都必须只读：不得修改工作树、索引、HEAD 或分支状态；如需检查其他修订版本，请使用临时工作树（git worktree add <tmpdir> <sha>），绝不要移动 HEAD。每份简报不得超过 400 个单词。调度时不得预判结果——不要写“不要标记”，也不要预先评定严重程度。

标准子 Agent需获得：diff 命令和提交列表；标准来源路径；standards-baseline.md 的路径。它必须先阅读该文件，再逐一对照其中的十二种代码异味检查 diff；对于跨越信任边界（不可信输入、机密处理、特权操作）的任何代码块，还要对照 Security 部分。简报要求报告：(a) diff 中每处违反已记录标准的内容，并引用文档和规则；(b) 针对十二种基准代码异味，报告发现的每一处问题，注明异味名称并引用代码块；(c) 报告 diff 触发的 Security 部分中的每项安全问题，注明条目及其跨越的信任边界。违反文档的情况可能构成明确问题；基准代码异味和安全条目始终需要酌情判断；仓库文档优先于基准；跳过由工具强制执行的内容；还要检查 CONTEXT.md 中的术语是否发生偏移（diff 重命名或更换术语来指代词汇表概念，即属问题）。

规格子 Agent需获得：diff 命令和提交列表；requirements.md 路径。简报要求：逐项检查需求并报告 (a) 缺失或仅部分实现的 ID；(b) diff 中没有任何需求要求的行为（范围蔓延）；(c) 看似已实现但实现错误的 ID。每项发现都要引用需求 ID；还要依据 docs/agents/project.md 中的约定，核实每个已覆盖 ID 是否都有标注该 ID 的测试，并标记未标注的覆盖。如果步骤 3a 发现了功能重叠，规格子 Agent 还需获得相关邻接功能卡（包含其所有权路径和 Out-of-Scope），并在简报中要求：凡是 diff 重新实现了共享表面邻接功能已负责的行为，都应报告为 reuse-miss 问题，并引用邻接功能代码。

完成条件：两份报告均已返回。

5. 汇总

在 ## Standards 和 ## Spec 标题下分别呈现报告，最多只做轻微整理。不得合并、跨维度去重，也不得将一个维度的发现重新排序以对照另一个维度；隔离维度的目的正是避免这种重新排序。如果步骤 3b 产生了不变量判定，应在单独的 ## Invariants (advisory) 标题下呈现，作为第三个独立类别，绝不能与 Standards/Spec 合并或相互比较排序。

每项发现都必须包含：严重程度（Critical / Important / Minor）、文件:行号、其重要性，以及建议的修复方案（除非显而易见）。

最后给出判定：

Ready to merge? Yes | No | With fixes
[1–2 sentences of technical reasoning]

完成条件：交付两个维度的报告和最终判定。

内联备用流程（不支持子 Agent 时）

如果此运行环境不支持子 Agent，请在同一上下文中自行依次完成两个维度：先检查标准——阅读 standards-baseline.md，逐项对照 diff 检查其中的十二种代码异味及 Security 部分；再检查规格——逐条检查需求 ID。必须先完整完成并记录一个维度，再开始下一个；最终仍须分别放在 ## Standards 和 ## Spec 标题下呈现，不得相互比较排序。这样做会失去两个子 Agent 所提供的上下文隔离，因此，严格按照先后顺序完成各维度，才能避免它们彼此影响。