code-review

代码审查——规范与规格说明

从某个固定位置（提交、分支、标签或合并基点）开始审查变更，分两个维度进行：规范（代码是否遵循此代码库记录的编码规范？）和规格说明（代码是否符合最初问题／规格说明的要求？）。通过并行子 Agent 同时执行两项审查，并并列报告结果。适用于用户希望审查某个分支、PR、进行中的变更，或要求“审查自 X 以来的变更”的情况。

此技能引自 mattpocock/skills（MIT），上游通过模型调用。

何时使用此技能

• 从某个固定位置（提交、分支、标签或合并基点）开始审查变更，分两个维度进行：规范（代码是否遵循此代码库记录的编码规范？）和规格说明（代码是否符合最初问题／规格说明的要求？）。
• 通过并行子 Agent 同时执行两项审查，并并列报告结果。
• 适用于用户希望审查某个分支、PR、进行中的变更，或要求“审查自 X 以来的变更”的情况。

说明

对比用户提供的固定位置与 HEAD，从两个维度审查差异：

• 规范：代码是否符合此代码库记录的编码规范？
• 规格说明：代码是否忠实实现了最初的问题／规格说明？

两个维度分别由并行子 Agent执行，以免彼此的上下文相互干扰，然后由此技能汇总审查结果。

问题跟踪工具信息应该已提供给你。如果缺少 docs/agents/issue-tracker.md，请告知用户运行 /setup-matt-pocock-skills。

流程

1. 确定固定位置

用户提到的任何位置都可作为固定位置（提交 SHA、分支名称、标签、main、HEAD~5 等）。如果用户未指定，请询问。

记录一次差异命令：git diff <fixed-point>...HEAD（使用三点语法，因此比较的是合并基点）。同时记录提交列表：git log <fixed-point>..HEAD --oneline。

继续之前，确认该固定位置有效（git rev-parse <fixed-point>），且差异不为空。无效引用或空差异应在此处报错，而不是在两个并行子 Agent 中报错。

2. 确定规格说明来源

按以下顺序查找最初的规格说明：

1. 提交消息中的问题引用（#123、Closes #45、GitLab 的 !67 等），并通过 docs/agents/issue-tracker.md 中的工作流获取。
2. 用户作为参数提供的路径。
3. docs/、specs/ 或 .scratch/ 下与分支名称或功能相匹配的规格说明文件。
4. 如果没有找到，请询问用户规格说明的位置。如果用户表示没有规格说明，规格说明子 Agent 将跳过审查，并报告“没有可用的规格说明”。

3. 找出标准来源

仓库中任何说明代码应如何编写的内容，例如 CODING_STANDARDS.md 或 CONTRIBUTING.md。

无论仓库记录了什么，标准维度始终包含以下代码异味基线：一组固定的 Fowler 代码异味（Refactoring，第 3 章），即使仓库没有任何文档也适用。它受两条规则约束：

• 以仓库标准为准。 已记录的仓库标准始终优先；如果标准认可了基线会标记的做法，就抑制该代码异味。
• 始终需要判断。 每种代码异味都是带标签的启发式判断（“可能存在 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. 并行启动两个子 Agent

标准子 Agent 的提示词应包括：

• 完整的差异命令和提交列表。
• 在步骤 3 中找到的标准来源文件列表，以及步骤 3 中的代码异味基线（完整粘贴，子 Agent 无法通过其他方式获取）。
• 任务说明：“按相关文件/代码块报告：(a) 差异中每一处违反已记录标准的内容：引用标准（文件 + 规则）；(b) 发现的任何基线代码异味：指出名称并引用代码块。区分硬性违规和判断性问题：违反已记录标准可能是硬性违规，但基线代码异味始终需要判断，且已记录的仓库标准优先于基线。跳过工具已强制执行的内容。少于 400 词。”

规范子 Agent 的提示词应包括：

• 差异命令和提交列表。
• 规范的路径或已获取的规范内容。
• 任务说明：“报告：(a) 规范要求但缺失或未完全实现的内容；(b) 差异中未被要求的行为（范围蔓延）；(c) 看似已实现但实现可能有误的要求。每项发现都引用相应的规范原文。少于 400 词。”

如果规范缺失，则跳过规范子 Agent，并在最终报告中注明这一点。

5. 汇总

将两份报告分别放在 ## Standards 和 ## Spec 标题下，原样呈现或稍作整理。不要合并或重新排序发现的问题，因为这两个维度有意保持独立（参见 为什么分为两个维度）。

最后用一行总结每个维度的发现总数，以及各维度内最严重的问题（如有）。不要跨维度选出单一赢家：避免重新排序正是保持维度分离的目的。

为什么分为两个维度

一项变更可能通过一个维度，却未通过另一个：

• 代码遵循所有标准，却实现了错误的内容 → Standards 通过，Spec 未通过。
• 代码准确实现了问题要求，却违反了项目约定 → Spec 通过，Standards 未通过。

分别报告可以避免一个维度掩盖另一个维度。

沿用上一版 jeo-skills 的本地路由

与仓库无关的审查路由指南（严重性等级、缺少证明的检查，以及指向 debugging、testing-strategies 和 code-refactoring 的路由）现位于 references/jeo-review-routing.md。如果请求是“我们应该如何审查”，而不是“现在运行审查”，请阅读该指南。

示例

• 先将此技能应用于一个范围较窄的任务，确认输出符合上述格式，再扩展到完整任务。
• 如果某个步骤需要了解仓库或环境中的信息，请自行查找，而不是询问用户。

最佳实践

• 保持上游流程完整；如有偏离，请明确记录，而不是默默自行变通。
• 在此技能标记为由用户决定的每个决策点，都应停下来并将控制权交还给用户。
• 优先选择小规模、可逆的变更，并明确说明假设，而不是将其隐去。

参考资料

• 上游技能：mattpocock/skills skills/engineering/code-review/SKILL.md（提交 3cca18b，MIT）
• 项目标准：.agent-skills/skill-standardization/SKILL.md
• 验证脚本：.agent-skills/skill-standardization/scripts/validate_skill.sh