code-review

沿两个轴审查 HEAD 与用户提供的固定点（fixed point）之间的差异：

• 规范（Standards）：代码是否符合本仓库记录的编码规范？
• 规格（Spec）：代码是否忠实实现了来源议题或规格？

两个轴都由**并行子智能体（parallel sub-agents）**运行，避免彼此污染上下文；随后由本技能汇总它们的发现。

你应当已经获得议题跟踪器（issue tracker）。如果没有，请提醒用户运行 /setup-matt-pocock-skills。

流程

1. 固定比较点

用户指定的内容就是固定点：可以是提交 SHA、分支名、标签、main、HEAD~5 等。如果用户没有指定，就询问用户。

一次性记录差异命令：git diff <fixed-point>...HEAD（三个点，因此比较基于 merge-base）。同时通过 git log <fixed-point>..HEAD --oneline 记录提交列表。

继续之前，确认固定点能够解析（git rev-parse <fixed-point>），并且差异不为空。无效引用或空差异应当在此处失败：不要等到两个并行子智能体内部才失败。

2. 确定规格来源

按以下顺序查找原始规格：

1. 提交消息中的议题引用（#123、Closes #45、GitLab !67 等）：通过跟踪器文档中的工作流获取。
2. 用户作为参数传入的路径。
3. docs/、specs/ 或 .scratch/ 下与分支名或功能匹配的规格文件。
4. 如果找不到，就询问用户规格在哪里。如果用户表示不存在规格，**规格（Spec）**子智能体将跳过审查并报告“没有可用规格（no spec available）”。

3. 确定规范来源

搜索仓库中所有记录代码编写方式的文件。只要 CODING_STANDARDS.md 或 CONTRIBUTING.md 存在，就必须将其列入规范来源。

除仓库自身记录的规范外，规范轴始终携带以下坏味道基线（smell baseline）：一组固定的 Fowler 代码坏味道（Refactoring 第 3 章），即使仓库没有任何说明也适用。它受两条规则约束：

• **仓库规范优先（The repo overrides）。**有文档记录的仓库规范始终优先；如果仓库规范认可了基线原本会标记的做法，就不要报告该坏味道。
• **始终需要判断（Always a judgement call）。**每项坏味道都是带标签的启发式判断（例如“可能存在 Feature Envy”），绝不是硬性违规；与这里的任何规范一样，跳过工具已经强制执行的事项。

每项坏味道都按它是什么 → 如何修复的形式描述；将其与差异进行匹配：

• 神秘命名（Mysterious Name）：函数、变量或类型的名称无法揭示其作用或所保存的内容。→ 重命名；如果找不到诚实准确的名称，说明设计仍然含混。
• 重复代码（Duplicated Code）：同一种逻辑形态出现在变更的多个冲突块或文件中。→ 提取共享形态，并让两处共同调用。
• 依恋情结（Feature Envy）：方法访问另一个对象的数据多于访问自身数据。→ 将方法移动到它所依恋的数据上。
• 数据泥团（Data Clumps）：相同的几个字段或参数总是结伴出现（一个等待诞生的类型）。→ 将它们组合成一个类型并传递该类型。
• 基本类型偏执（Primitive Obsession）：用基本类型或字符串代替值得拥有独立类型的领域概念。→ 为该概念创建自己的小型类型。
• 重复切换（Repeated Switches）：针对同一类型的相同 switch/if 级联在变更中反复出现。→ 改用多态，或者使用两处共享的单个映射。
• 霰弹式修改（Shotgun Surgery）：一项逻辑变更迫使差异中多个文件发生零散编辑。→ 将一起变化的内容集中到一个模块。
• 发散式变化（Divergent Change）：出于多个互不相关的原因编辑同一个文件或模块。→ 拆分，使每个模块只因一个原因而变化。
• 夸夸其谈的通用性（Speculative Generality）：为规格中不存在的需求添加抽象、参数或钩子。→ 删除；重新内联，直到真实需求出现。
• 消息链（Message Chains）：调用方不应依赖的长串 a.b().c().d() 导航。→ 把遍历隐藏在第一个对象的单个方法之后。
• 中间人（Middle Man）：主要工作只是继续委托的类或函数。→ 去掉它，直接调用真正目标。
• 被拒绝的遗赠（Refused Bequest）：子类或实现者忽略或覆盖了所继承内容中的大部分。→ 放弃继承，使用组合。

4. 并行启动两个子智能体

在前台同时发起两个子智能体调用，并汇总它们返回的报告。

规范子智能体提示（Standards sub-agent prompt）：包括：

• 完整差异命令和提交列表。
• 第 3 步找到的规范来源文件列表，再加上完整粘贴的第 3 步坏味道基线：子智能体无法通过其他方式访问该基线。
• 简要任务：“按相关文件或冲突块报告：(a) 差异中每一处违反已记录规范的位置，并引用规范（文件 + 规则）；(b) 发现的任何基线坏味道，写明其名称并引用冲突块。区分硬性违规和判断性结论：违反已记录规范可以是硬性违规，但基线坏味道始终属于判断性结论，且已记录的仓库规范优先于基线。跳过工具已经强制执行的事项。控制在 400 词以内。”

规格子智能体提示（Spec sub-agent prompt）：包括：

• 差异命令和提交列表。
• 规格的路径或已获取的内容。
• 简要任务：“报告：(a) 规格要求但缺失或只完成一部分的需求；(b) 差异中未经要求的行为（范围蔓延，scope creep）；(c) 看似已经实现但实现方式似乎错误的需求。每项发现都引用对应的规格行。控制在 400 词以内。”

如果缺少规格，就跳过规格子智能体，并在最终报告中说明。

5. 汇总

将两份报告分别放在 ## Standards 和 ## Spec 标题下，保持原文或仅做轻微整理。不要合并发现或重新排序：两个轴是刻意分开的（参见_为何使用两个轴_）。

最后用一行总结：每个轴的发现总数，以及_每个轴内部_最严重的问题（如果有）。不要跨轴选出一个总冠军：避免这种重新排序正是将两者分开的目的。

为何使用两个轴

一项变更可能通过一个轴却无法通过另一个轴：

• 代码遵守每一项规范，却实现了错误的功能 → 规范通过，规格失败（Standards pass, Spec fail）。
• 代码完全实现了议题要求，却破坏了项目约定 → 规格通过，规范失败（Spec pass, Standards fail）。

分别报告可以防止一个轴掩盖另一个轴的问题。