code-review

代码审查

根据用户提供的固定点审查差异，依据如下：

• 标准 — 已接受的工程／架构指南和仓库标准。
• 规范 — 所选待办项在 Epic 上下文中的预期变更和验收标准。

默认使用一名组合审查者。仅在涉及安全／身份验证、破坏性迁移或可信的数据丢失风险，或公共 API 兼容性时，才使用独立并行的标准审查者和规范审查者。wiki 代表已接受的当前状态；待办事项代表预期变更。

需要拆分审查时，使用 $parallel-execution，调用两个只读判断单元。此上下文负责权限裁定、综合结论、问题发现和交接。组合审查只使用一名审查者，不加载共享调度器。

在深度为 1 的临时工作者下，绝不启动其他工作者：在本地执行所选简报，依次审查拆分的维度，并报告缺少的并行能力。

流程

1. 固定审查点

使用用户提供的任意值（SHA、分支、标签、main、HEAD~5）；如果未指定，则询问。发现权限来源前，先使用 git rev-parse --verify <fixed-point>^{commit} 和 git merge-base <fixed-point> HEAD 解析；任一命令失败时，停止并给出可操作的错误信息。一次性记录：

• 差异：git diff <fixed-point>...HEAD（三点语法，以合并基点为准）；
• 提交：git log <fixed-point>..HEAD --oneline；
• 变更路径：git diff --name-only <fixed-point>...HEAD。

如果差异为空，报告这一点并停止。无效引用和空差异在此处处理，绝不在并行审查中处理。

2. 阅读项目治理文件

解析仓库根目录，并读取所有适用的 AGENTS.md、CLAUDE.md 和嵌套指令。如果存在 setup-project 脚手架，还需读取 docs/wiki/index.md、docs/wiki/maintenance.md、docs/backlog/index.md、docs/backlog/maintenance.md，以及最近的相关 wiki 和待办索引。若项目本地维护规则更严格，则以其为准。审查期间不得修改 wiki、待办事项、声明或状态。

3. 选择待办工作项

当调用方请求 Epic 范围审查时，Epic 是主要规范依据，其所有子项均作为上下文。这是常规的全面审查范围。

否则，选择一个 WORK-NNN：

1. 用户提供的 ID、路径或完整记录优先。如果某个临时子项属于一个有效 Epic 验收单元，则该子项无效，应交还调用方；改为一次性审查整个组合后的 Epic。作为独立验收单元调用的 WORK-NNN，进行一次独立审查。
2. 否则，检查有效记录中是否恰有一条有效声明，或与当前分支／提交完全匹配的链接。忽略终止状态的记录和已过期的声明；若没有匹配项或有多个匹配项，则询问。
3. 独立事项自身构成全面审查范围。Epic 子项仍属临时项，不能通过此审查获得验收。

如果没有待办项，必须先明确确认不存在规范，然后仅审查标准。

4. 构建权威资料包

当调用工作流提供已解析的资料包路径和角色时，将其作为资料包；不要从目录索引重新发现权威来源，也不要重新读取调用方在本次调用链中已按其新鲜度规则读取过内容的路径。仅发现并读取调用方未提供的内容。

启动任何一个子 Agent 之前，确保所有权威资料均已由调用方或在此处读取：

• 所选工作项：结果／变更、验收标准、关系、Wiki 引用、Research、Decisions、Execution、子任务；
• 当 parent 不为 none 时，完整的父 Epic：结果、标准、范围、排除项、约束、Wiki 引用、研究、执行上下文；
• 针对 Epic 范围的审查：Epic 及其每条子记录——将每项变更和标准标记为子项上下文；
• 所有与变更相关的已链接当前状态 Wiki 概念（通过 wiki_refs 或 Epic），以及所有权判定所需的最近索引；
• 工作项或 Epic 中与提案相关的研究，以及直接链接的本地证据；
• docs/wiki/engineering/ 和 docs/wiki/architecture/ 下已采纳的指导，以及仓库标准来源（说明文件、CONTRIBUTING.md、CODING_STANDARDS.md）；
• docs/wiki/engineering/technologies/ 和 docs/wiki/engineering/standards/ 下所有适用的指导页面——根据目录索引和变更路径，针对每项涉及的技术和横切标准各确定一页。

记录每个来源路径及其角色。当前状态 Wiki 事实描述基线和约束；它们不能满足或消除缺失的预期变更。子工作项的变更、标准和排除项是主要 Spec 权威；Epic 上下文不得扩大或取代子项范围。针对 Epic 范围的审查中，Epic 自身的结果和标准是主要 Spec 权威，子项范围仅作上下文；任何子项范围都不得扩大 Epic 范围。积压事项范围不能免除遵循仓库或已采纳的 Wiki 标准。

5. 选择审查模式

仅当所审查的变更涉及安全／身份验证、破坏性迁移或可信的数据丢失风险，或公共 API 兼容性时，才使用两名并行审查者。兼容性要求存在已更改或移除的现有契约，或其他可能导致使用方受损的情况；纯粹新增导出项不会触发该条件。仅有隐私措辞、常规持久化、并发、构建／发布基础设施或 ADR 重要性，不会触发拆分审查。其他情况使用一名综合审查者。记录具体触发条件，或记录 combined default。

6. 准备标准依据

采用第 4 步中的所有适用且已采纳的工程／架构 Wiki 指引和仓库标准。产品当前状态概念和待办事项需求属于上下文，不是标准规则。

适用的指引页面是硬性标准依据，具体约束力以每条规则根据 docs/wiki/maintenance.md § Adopted guidance 所标注的强度为准：违反 Requirements 规则属于有据可查的标准违规，须引用页面路径和规则；偏离 Recommendations 属于判断事项；Conventions 作为有据可查的实践具有约束力。已记录的 Deviations 条目优先于其所偏离的上游指引；在 Known gaps 区域中编写新代码仍然违反该规则。如果页面记录的已安装版本与清单中的版本不再一致，该页面就不可靠：应将版本过时报告为一项发现，而不是执行该版本特定的规则。

当 Wiki 定义了重要性测试时，标准依据还包括 ADR 检查。阅读 ADR 索引 docs/wiki/architecture/decisions/index.md、docs/wiki/maintenance.md 中的重要性测试，以及工作项的 decisions 字段和 ## Decisions 部分；只有当某项生效中的 ADR 的主题与已更改路径或拟定决策相关时，才打开该 ADR。若 diff 作出的决策符合该测试，但记录中既没有涵盖该决策的拟定 ADR，也没有解释为何不存在符合条件 ADR 的已记录 none，则报告一项发现；若 diff 与生效中的 ADR 相矛盾，且未拟定取代该 ADR 的决策，也应报告一项发现。重要性测试属于判断事项——应将其标注为判断事项，绝不能将缺少 ADR 视为代码缺陷。

除有据可查的规则外，标准依据还包括 references/smell-baseline.md 中的 代码异味基线。评审者会在第 7 步阅读该文件；父级不会。

7. 启动评审者

阅读 references/sub-agent-briefs.md。默认：启动一名综合评审者。高风险且范围较窄时：让 $parallel-execution 将一项标准评审和一项规格评审作为同一次全面评审来执行。没有规格评审时，只执行标准评审。适用时加入 Epic 补充项。

8. 汇总

说明 Review mode: 及其原因。提供 ## Standards 和 ## Spec：分别列出每个评审维度的发现数量及附有引用的可执行发现，切勿逐字照搬 Agent 报告。评审维度标签和数量须彼此独立。即使由综合评审者执行，也要分别报告两个维度。

添加 Next step: — 对于可执行的发现，修复一次，直接检查修复结果，仅重跑受影响的检查，然后继续验收单元的代表性套件门禁，无需再次评审；$implement 中通过后，继续该门禁；Epic 通过后，继续原子化收尾；独立项通过后，继续单项验收。