code-review

核心能力

双轴并行代码审查

对指定 git 范围（commit / branch / tag / merge-base 到 HEAD）的变更进行差异化审查，沿两个独立维度并行执行：

• Standards 轴 — 代码是否遵循仓库文档化的编码标准
• Spec 轴 — 代码是否忠实实现了原始需求/PRD/规格说明

两个轴各自运行在隔离的子代理中，避免相互污染上下文。最终并排呈现两份报告，不做合并或重排序，防止一个维度的问题被另一个维度掩盖。

审查流程

Step 1 · 固定基准点

用户指定比较的固定点（commit SHA、branch 名、tag、main、HEAD~5 等）。执行 git diff <fixed-point>...HEAD（三-dot 语法，基于 merge-base 比较），同时获取 git log <fixed-point>..HEAD --oneline 的提交列表。

前置校验：确认固定点可解析（git rev-parse）且 diff 非空。坏引用或空 diff 在此阶段直接失败，避免浪费子代理资源。

Step 2 · 识别 Spec 来源

按优先级查找原始需求规格：

1. Commit message 中的 issue 引用 — #123、Closes #45、!67 等，通过 docs/agents/issue-tracker.md 工作流抓取
2. 用户直接传入的路径
3. 仓库内匹配文件 — docs/、specs/、.scratch/ 下与 branch 名或功能相关的 PRD/spec 文件
4. 询问用户 — 若以上均未命中，询问用户 spec 位置；若用户确认无 spec，Spec 轴跳过并报告"无可用规格"

Step 3 · 识别 Standards 来源

搜集仓库内所有编码规范文档（如 CODING_STANDARDS.md、CONTRIBUTING.md 等）。

在此之上，Standards 轴始终携带 Fowler 代码异味基线 —— 一套固定启发式规则，即使仓库未文档化任何标准也能执行审查。

两条绑定规则：

• 仓库标准优先 — 文档化的仓库标准覆盖基线；若仓库认可某实践而基线会标记，则抑制该异味
• 始终为判断调用 — 每个异味均为标注式启发（"可能的 Feature Envy"），非硬违规；工具已强制执行的项目跳过

12 项 Fowler 代码异味基线

异味	识别标准	修复方向
Mysterious Name	函数/变量/类型名无法揭示其功能	重命名；若找不到诚实名称，说明设计本身模糊
Duplicated Code	相同逻辑形状出现在多个 hunk 或文件中	提取共享形状，两处复用
Feature Envy	方法频繁操作其他对象的数据而非自身	将方法移至被操作数据所属对象
Data Clumps	相同字段或参数成组出现	捆绑为新类型，统一传递
Primitive Obsession	原始类型或字符串代替本应独立的领域概念	为概念创建小型类型
Repeated Switches	对同一类型的 switch/if 级联反复出现	以多态替代，或共享一个映射表
Shotgun Surgery	单一逻辑变更迫使 diff 中多处分散修改	将相关变更聚集到单一模块
Divergent Change	单一文件/模块因多个无关原因被修改	拆分，使每个模块只因一种原因变更
Speculative Generality	为 spec 未要求的需求添加抽象/参数/钩子	删除；内联直到真实需求出现
Message Chains	长链式调用a.b().c().d() 使调用者过度依赖导航路径	隐藏遍历，在第一对象上封装方法
Middle Man	类或函数主要只做转发	删除中间层，直接调用真实目标
Refused Bequest	子类或实现者忽略/覆盖大部分继承内容	放弃继承，改用组合

并行子代理执行

Standards 子代理

输入：完整 diff 命令、提交列表、standards 来源文件列表 + 上述异味基线全文。

任务简报：逐文件/hunk 报告 (a) 违反文档化标准的位置（引用标准文件及具体规则）；(b) 发现的基线异味（命名并引用 hunk）。区分硬违规与判断调用 —— 文档标准违反可为硬违规，基线异味始终为判断调用，文档标准覆盖基线，跳过工具已强制执行项。报告控制在 400 字内。

Spec 子代理

输入：diff 命令、提交列表、spec 路径或内容。

任务简报：报告 (a) spec 要求但未实现或实现不完整的需求；(b) diff 中未在 spec 中要求的额外行为（范围蔓延）；(c) 看似已实现但实现方式有误的需求。每条发现引用 spec 原文。报告控制在 400 字内。

若 spec 缺失，跳过 Spec 子代理，最终报告中标注"无可用规格"。