code-review

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

对 `HEAD` 与用户给出的固定点之间的 diff 做双轴审查：

- **Standards** — 代码是否符合本仓库已文档化的编码标准？
- **Spec** — 代码是否忠实地实现了发起它的 issue / spec？

两个轴作为 **并行 subagent** 运行，以免污染彼此的 context，然后由本 skill 汇总它们的发现。

Issue tracker 应当已经提供给你 — 若缺少 `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 应在这里失败 — 而不是在两个并行 subagent 内部失败。

### 2. 识别 spec 来源

按此顺序寻找发起它的 spec：

1. Commit message 中的 issue 引用（`#123`、`Closes #45`、GitLab `!67` 等）— 按 `docs/agents/issue-tracker.md` 中的工作流获取。
2. 用户作为参数传入的路径。
3. `docs/`、`specs/` 或 `.scratch/` 下与分支名或功能匹配的 spec 文件。
4. 若什么都找不到，问用户 spec 在哪。若他们说没有，**Spec** subagent 将跳过并报告 "no spec available"。

### 3. 识别 standards 来源

仓库中任何文档化「代码应如何写」的东西，例如 `CODING_STANDARDS.md` 或 `CONTRIBUTING.md`。

在仓库已文档化的内容之上，Standards 轴始终携带下面的 **smell 基线** — 一套固定的 Fowler 代码 smell（《Refactoring》，第 3 章），即使仓库什么都没文档化也适用。两条规则约束它：

- **仓库优先。** 已文档化的仓库标准永远胜出；若它认可基线会标出的东西，就压制该 smell。
- **永远是判断题。** 每个 smell 都是带标签的启发式（"possible Feature Envy"），绝不是硬性违规 — 并且，和这里的任何标准一样，跳过工具已经强制的东西。

每个 smell 读作 *它是什么* → *怎么修*；对照 diff 匹配：

- **Mysterious Name** — 函数、变量或类型的名字没有揭示它做什么或持有什么。→ 重命名；若想不出诚实的名字，设计本身就浑浊。
- **Duplicated Code** — 同一逻辑形状出现在本次变更的多个 hunk 或文件中。→ 抽出共享形状，两边都调用它。
- **Feature Envy** — 一个方法伸进另一个对象的数据比伸进自己的还多。→ 把方法挪到它羡慕的数据上。
- **Data Clumps** — 同样的几个字段或参数总是一起旅行（一个想要诞生的类型）。→ 把它们捆成一个类型，传那个。
- **Primitive Obsession** — 用原语或字符串顶替一个配得上自己类型的领域概念。→ 给这个概念一个小类型。
- **Repeated Switches** — 对同一类型的同一个 `switch`/`if` 级联在本次变更中反复出现。→ 换成多态，或两边共享的一张 map。
- **Shotgun Surgery** — 一次逻辑变更迫使 diff 里许多文件被零散编辑。→ 把一起变的东西收进一个 module。
- **Divergent Change** — 一个文件或 module 因几个不相关的理由被编辑。→ 拆开，让每个 module 只因一个理由而变。
- **Speculative Generality** — 为 spec 并不具备的需求加上的抽象、参数或 hook。→ 删掉；内联回去，直到真正的需求出现。
- **Message Chains** — 调用方不该依赖的长 `a.b().c().d()` 导航。→ 把这段走法藏到第一个对象上的一个方法后面。
- **Middle Man** — 一个类或函数大部分只是往下委托。→ 砍掉它，直接调用真正的目标。
- **Refused Bequest** — 一个子类或实现者忽略或覆盖了它继承的大部分东西。→ 丢掉继承，用组合。

### 4. 并行拉起两个 subagent

**Standards subagent 提示** — 包含：

- 完整的 diff 命令和 commit 列表。
- 你在第 3 步找到的 standards 来源文件列表，**外加第 3 步的 smell 基线全文粘贴** — subagent 没有别的途径拿到它。
- 简报：「按相关的 file/hunk 报告 — (a) diff 违反已文档化标准的每一处：引用该标准（文件 + 规则）；以及 (b) 你发现的任何基线 smell：点名并引用该 hunk。区分硬性违规与判断题 — 已文档化标准的违反可以是硬性的，但基线 smell 永远是判断题，且已文档化的仓库标准覆盖基线。跳过工具已强制的东西。400 词以内。」

**Spec subagent 提示** — 包含：

- Diff 命令和 commit 列表。
- Spec 的路径或已获取的内容。
- 简报：「报告：(a) spec 要求但缺失或不完整的需求；(b) diff 中未被要求的行为（范围蔓延）；(c) 看起来已实现但实现看起来不对的需求。每条发现引用 spec 对应行。400 词以内。」

若 spec 缺失，跳过 Spec subagent，并在最终报告中注明。

### 5. 汇总

在 `## Standards` 和 `## Spec` 标题下呈现两份报告，原文或略作清理。**不要** merge 或重新排序发现 — 两个轴是刻意分开的（见 _为什么是两个轴_）。

以一行摘要结束：每个轴的发现总数，以及 _每个轴内部_ 最严重的问题（若有）。不要跨轴挑一个总冠军 — 那正是这种分离要防止的重新排序。

## 为什么是两个轴

一次变更可以通过一个轴而失败于另一个：

- 代码遵循每一条标准，但实现的是错的东西 → **Standards 通过，Spec 失败。**
- 代码恰好做了 issue 要求的事，但打破了项目约定 → **Spec 通过，Standards 失败。**

分开报告能阻止一个轴掩盖另一个。

From shenjunjian/matt-skill-cn, MIT.

More from shenjunjian/matt-skill-cn