code-review

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

对 `HEAD` 与用户提供的某个固定基点之间的 diff 做双轴审查：

- **标准** — 代码是否符合本仓库记录的编码规范？
- **规格** — 代码是否忠实地实现了源头工单/规格？

两条轴都作为**并行子 agent**运行，这样它们不会污染彼此的上下文，然后本技能汇总它们的发现。

工单跟踪器应当已经提供给你——如果 `docs/agents/issue-tracker.md` 缺失，运行 `/setup-matt-pocock-skills`。

## 流程

### 1. 钉住固定基点

用户说的就是固定基点——一个 commit SHA、分支名、tag、`main`、`HEAD~5` 等等。如果他们没指定，就问。

把 diff 命令记下来一次：`git diff <fixed-point>...HEAD`（三点，这样比较是针对 merge-base）。同时通过 `git log <fixed-point>..HEAD --oneline` 记下 commit 列表。

在继续之前，确认固定基点能解析（`git rev-parse <fixed-point>`）且 diff 非空。坏的 ref 或空 diff 应该在这里失败——而不是在两个并行子 agent 内部失败。

### 2. 确定规格来源

按以下顺序寻找源头规格：

1. commit 消息中的工单引用（`#123`、`Closes #45`、GitLab `!67` 等）——通过 `docs/agents/issue-tracker.md` 中的工作流获取。
2. 用户作为参数传入的路径。
3. `docs/`、`specs/` 或 `.scratch/` 下与分支名或功能匹配的规格文件。
4. 如果什么都找不到，就问用户规格在哪里。如果他们说没有规格，**规格**子 agent 将跳过并报告「无可用规格」。

### 3. 确定标准来源

仓库里任何记录了代码应当如何编写的东西，比如 `CODING_STANDARDS.md` 或 `CONTRIBUTING.md`。

除了仓库记录的东西之外，标准轴始终携带下面这套**坏味道基线**——一组固定的 Fowler 代码坏味道（《重构》，第 3 章），即便一个仓库什么都没记录也适用。有两条规则约束它：

- **仓库优先。** 有记录的仓库标准始终胜出；当它认可某件基线本会标记的东西时，压制那条坏味道。
- **始终是判断题。** 每条坏味道都是一个带标签的启发式（「可能存在 Feature Envy」），从不是硬性违规——而且，和这里任何标准一样，跳过工具链已经强制执行的东西。

每条坏味道读作*它是什么* → *如何修*；把它对照 diff 来匹配：

- **Mysterious Name（神秘命名）** — 一个函数、变量或类型的名字没有揭示它做什么或持有什么。→ 重命名它；如果找不到诚实的名字，说明设计本身就模糊。
- **Duplicated Code（重复代码）** — 同样形状的逻辑出现在这次改动的多个 hunk 或文件中。→ 提取共享的形状，从两处调用它。
- **Feature Envy（依恋情结）** — 一个方法访问另一个对象的数据多于访问自己的。→ 把该方法移到它所依恋的数据上。
- **Data Clumps（数据泥团）** — 同样几个字段或参数总是一起出现（一个想要诞生的类型）。→ 把它们捆进一个类型，传那个。
- **Primitive Obsession（基本类型偏执）** — 一个基本类型或字符串在替代一个理应拥有自己类型的领域概念。→ 给这个概念它自己的小类型。
- **Repeated Switches（重复的 switch）** — 同样的 `switch`/`if` 级联针对同一类型在这次改动中反复出现。→ 用多态替换，或用两处共享的一个映射表。
- **Shotgun Surgery（霰弹式修改）** — 一个逻辑改动逼得你在 diff 中的许多文件里做零散的编辑。→ 把一起变化的东西聚拢进一个模块。
- **Divergent Change（发散式变化）** — 一个文件或模块因几个不相关的原因被编辑。→ 拆分，使每个模块只因一个原因而变化。
- **Speculative Generality（夸夸其谈的通用性）** — 为规格并不具备的需求添加的抽象、参数或钩子。→ 删掉它；内联回去，直到真实需求出现。
- **Message Chains（过长的消息链）** — 调用方不该依赖的长串 `a.b().c().d()` 导航。→ 把这段游走藏在第一个对象上的一个方法后面。
- **Middle Man（中间人）** — 一个大多只是向下转发的类或函数。→ 砍掉它，直接调用真正的目标。
- **Refused Bequest（被拒绝的遗赠）** — 一个子类或实现者忽略或覆盖了它继承来的大部分东西。→ 放弃继承，改用组合。

### 4. 并行派发两个子 agent

**标准子 agent 提示词** — 需包含：

- 完整的 diff 命令和 commit 列表。
- 你在第 3 步找到的标准来源文件列表，**外加第 3 步的坏味道基线**全文粘贴进去——子 agent 没有其他途径获取它。
- 简报：「逐文件/hunk（在相关处）报告——(a) diff 违反某条记录标准的每一处：引用该标准（文件 + 规则）；(b) 你发现的任何基线坏味道：命名它并引用该 hunk。区分硬性违规和判断题——记录标准的违反可以是硬性的，但基线坏味道始终是判断题，而且有记录的仓库标准覆盖基线。跳过工具链强制执行的东西。400 字以内。」

**规格子 agent 提示词** — 需包含：

- diff 命令和 commit 列表。
- 规格的路径或获取到的内容。
- 简报：「报告：(a) 规格要求但缺失或部分实现的需求；(b) diff 中没有被要求的行为（范围蔓延）；(c) 看似已实现但实现看起来有误的需求。为每个发现引用规格中的那一行。400 字以内。」

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

### 5. 汇总

把两份报告放在 `## Standards` 和 `## Spec` 标题下呈现，逐字或稍作清理。**不要**合并或重新排序发现——两条轴是有意分开的（见「为什么分两条轴」）。

以一行摘要收尾：每条轴的发现总数，以及*每条轴内*最严重的问题（若有）。不要跨轴挑出一个单一的赢家——那正是这种分离所要防止的重新排序。

## 为什么分两条轴

一个改动可以通过一条轴而在另一条上失败：

- 遵循每条标准但实现了错误的东西的代码 → **标准通过，规格失败。**
- 完全按工单要求去做但破坏了项目约定的代码 → **规格通过，标准失败。**

分开报告它们，可以阻止一条轴掩盖另一条。

From WenWuZhiDao/mattpocock-skills-zh, MIT.

More from WenWuZhiDao/mattpocock-skills-zh