Lesson 0013 · Engineering · 人和 AI 都能启动（model-invoked）· 流程课

code-review：两条轴各审各的

implement 刚把一个 Issue 建完，或者同事给你发来一个 PR——你盯着几百行 diff（两个 git 状态之间逐行对比出的改动清单），心里其实是两个独立的问题： 它写得对吗（有没有按这个仓库的规矩写代码），和它做的是那件事吗 （Issue 里要的东西是不是真做出来了）。code-review 就是把这两个问题拆成两条轴、 各派一个子代理去审、最后并排摆给你看的那个 skill。它钉在 0001 系统地图里主 build 链的末尾： implement 在 commit 之前一定会跑它一遍；你也可以随时单独启动它，审一条分支、 一个 PR、一段还没做完的改动。它只读不写——审完留下的是一份对话里的报告，不多一个文件。 学完这节课，你能说清两条轴各自吃什么原料、五个步骤每步在防什么错、报告为什么绝不合并排名， 以及行为不对时该去改 SKILL.md 的哪一段。

1. 它在整个系统里站在哪

0001 把已发布的 22 个 skill 分成配置层、编排层、纪律层。code-review 的位置一句话就能说清： 它是主 build 链的收尾审查。ask-matt 在描述主 flow 第 3 步时写得很明白： implement 逐 Issue 构建、内部驱动 tdd 走红绿循环，然后在 commit 之前 「closes out by running /code-review」——用一次两条轴的审查给这次构建收尾。 同一段还给它留了第二个入口：你想审一条分支或一个 PR 时，随时可以单独把它拿出来用。

主 build 链的收尾段：

  grill-with-docs → to-spec → to-tickets → implement
                                                │  内部驱动 /tdd，逐片构建
                                                ▼
                                           构建完成
                                                │  commit 之前
                                                ▼
                                         code-review ──→ 报告（只存在于对话里）
                                                ▲
        第二个入口：你手动 /code-review，审分支、PR、半成品改动

看依赖关系，要分两个方向数：

• 它依赖谁：首先是 setup-matt-pocock-skills——SKILL.md 开头就写着， 如果仓库里还没有 docs/agents/issue-tracker.md（这个文件告诉 agent 怎么从 Issue tracker 取 Issue 内容），先去跑 /setup-matt-pocock-skills。其次是上游的 to-spec 和 to-tickets：它们产出的 spec 和 Issue，正是 Spec 轴拿来对照的「当初要的东西」。 注意这些依赖都是软的——找不到 spec 时它不会死，只会让 Spec 轴缺席（见第 5 节）。
• 谁依赖它：implement。它的 SKILL.md 只有十来行， 其中一行就是「Once done, use /code-review to review the work」，然后才 commit 到当前分支。 也就是说，每一次走主 flow 的构建，收尾都固定经过这道审查。

它和近邻 tdd 不要搞混：tdd 是构建中的纪律（先写测试再写实现， 在约定好的接缝上测行为），code-review 是构建后的审查（diff 已经成型， 拿两把尺子量一遍）。一个管「怎么写」，一个管「写完验收」。

地图：0001 · 路由原文：ask-matt/SKILL.md 主 flow 第 3 步 · 调用方：implement/SKILL.md · 相邻课：0011 implement、0012 tdd

2. 调用方式与触发场景

先定性：code-review 是 model-invoked 的——人和 AI 都能启动。 判据有两个，都查得到：它的 SKILL.md frontmatter 里没有 disable-model-invocation: true（对比 implement、ask-matt 这些只能人启动的 skill，frontmatter 里都带着这一行）；它的 agents/openai.yaml 里也只有界面显示名「Code Review」，没有禁用隐式调用的 policy。 所以你有三种方式让它跑起来：

1. 你直接启动：输入 /code-review，最好顺手给出固定点 （比如 /code-review main）。这是审 PR、审分支、审半成品改动的标准入口。
2. AI 主动伸手：frontmatter 的 description 写明了触发条件—— 「Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X"」。你用自然语言说「帮我看看这个分支」「review 一下 main 以来的改动」， 它就会自己被加载。
3. 被别的 skill 用正文调用：implement 在收尾时通过正文里的一句 「use /code-review」把它拉进来（0001 讲过，这叫 prose 调用）。

触发场景对不对，看这张表：

触发条件原文：skills/engineering/code-review/SKILL.md 的 frontmatter · 调用面：code-review/agents/openai.yaml · 人读文档：docs/engineering/code-review.md （aihero.dev/skills-code-review）

3. 核心设计：两条轴，绝不合并

整个 skill 只围绕一个设计决定：把审查拆成两条互相正交的轴。 「轴」就是一把独立的尺子，各量各的，量完不混：

• Standards 轴——代码有没有遵守这个仓库写下来的编码标准？ 问的是「做得对吗」（is it built right）。
• Spec 轴——代码有没有忠实地实现当初那个 Issue / PRD / spec 要的东西？ 问的是「做对事吗」（is it the right thing）。PRD 是产品需求文档 （product requirements document），这里泛指一切「这次改动本该满足的需求出处」。

为什么要拆开？SKILL.md 的「Why two axes」一节给了两个足以说服人的组合：

• 代码每一条标准都遵守了，但实现的是错的东西 → Standards 过，Spec 挂。
• 代码做的正是 Issue 要的，但把项目的约定踩了个遍 → Spec 过，Standards 挂。

如果两把尺子的读数揉成一句「总体不错」，这两种情况都会被平均掉——一条轴的失败被另一条轴的通过掩盖。 所以这个 skill 把「分开报告」上升为硬性纪律，并在聚合步骤里明文禁止合并与跨轴排名（第 7 节细讲）。

权威原文：code-review/SKILL.md 开篇与「Why two axes」一节 · 叙事版：docs/engineering/code-review.md 的「Two axes, never merged」

4. 第 1 步：钉死固定点，错了就地失败

审查总得有个对比基准。固定点（fixed point）就是你指定的一个 git 参照物—— 一个 commit 的 SHA、分支名、tag、main、HEAD~5 都行； diff 的另一端永远是 HEAD（你当前分支的最新提交）。 用户说了什么，什么就是固定点；用户没说，这一步必须开口问，不许猜。

钉死之后，立刻把两样东西一次性抓在手里：

git diff <fixed-point>...HEAD          # 三点：对比 merge-base
git log <fixed-point>..HEAD --oneline   # 两点：列出这段范围内的提交
git rev-parse <fixed-point>             # 先验证这个参照物真的存在

三点的写法是考点。merge-base 是你的分支和固定点所在分支的分叉点 ——三点 diff 比的是「分叉点 → 你现在的 HEAD」，所以你看到的只是这条分支自己引入的变化。 如果误用两点（..），主干上别人后来提交的代码也会被算进 diff， Standards 和 Spec 两个子代理就会去审查一堆根本不是这次工作的代码。

这一步最后一条纪律是 fail fast（快速失败）：先用 git rev-parse 确认固定点解析得出来，再确认 diff 非空。参照物写错了、或者 diff 是空的， 必须在这里就报错停下——不能等到两个子代理已经并行撒出去了， 才在它们各自的环境里分别炸一次。错误发现得越早，定位成本越低，这是整个第 1 步存在的理由。

原文：code-review/SKILL.md「### 1. Pin the fixed point」

5. 第 2 步：Spec 轴的原料从哪来

Spec 轴要回答「做对事吗」，前提是找得到「当初要做的事」。 这里用上 0001 和 CONTEXT.md 的统一词汇：Issue tracker 是存放 Issue 的工具 （GitHub Issues、Linear、或本地 .scratch/ 目录下的 markdown 约定）， Issue 是里面一条被跟踪的工作单元。这个 skill 按固定顺序找 spec， 找到即停：

还有一个前置条件要记牢：第一级「去 Issue tracker 取 Issue」依赖 docs/agents/issue-tracker.md 这个文件——它是 setup-matt-pocock-skills 在配置阶段写进你的仓库的。SKILL.md 开头明说：这个文件缺失就先跑 /setup-matt-pocock-skills（0002 那节课讲的就是它）。

原文：code-review/SKILL.md「### 2. Identify the spec source」 · 前置配置：0002 setup-matt-pocock-skills · spec 的生产者：0009 to-spec、0010 to-tickets

6. 第 3 步：Standards 轴的两层来源与 12 条异味基线

Standards 轴要回答「做得对吗」，它的尺子由两层叠成：

1. 仓库自己写下来的标准：任何记录「这个仓库的代码该怎么写」的文件， 比如 CODING_STANDARDS.md、CONTRIBUTING.md。这层因仓库而异。
2. 异味基线（smell baseline）：一组固定携带、开箱即用的代码异味清单， 出自 Fowler《重构》（Refactoring）第 3 章。代码异味 （code smell）是那本书提出的一类启发式信号——「看着不对劲、多半该改」， 是提醒而不是报错。哪怕仓库什么文档都没写，这层也永远在。

两层之间靠两条规则绑死，缺一条这套机制就会咬人：

• The repo overrides（仓库优先）：仓库写下来的标准永远赢。 如果仓库明文认可某种做法，而基线把它当异味，就压掉这条异味提示—— 基线是默认值，不是圣旨。
• Always a judgement call（永远是裁量项）：每条异味在报告里都是一个带标签的启发式提示， 写法是「可能的 Feature Envy」（possible Feature Envy），永远不是硬性违规。 硬性违规（hard violation）只留给违反仓库明文标准的情况。 还有半句附带规则：工具（linter、formatter）已经在强制的事，两条轴都跳过——别报告机器早就管了的东西。

6.1 12 条异味，每条都是「是什么 → 怎么修」

基线的 12 条异味逐条列在下面，按 SKILL.md 原文压缩。 每条的结构都一样：先说什么算这条异味，再给修复方向。子代理拿到 diff 后逐 hunk （hunk：diff 里一段连续的改动块）对照这张表。

原文：code-review/SKILL.md「### 3. Identify the standards sources」 · 呼应：0005 codebase-design

7. 第 4、5 步：并行子代理与聚合红线

7.1 第 4 步：一条消息，两个子代理

两条轴各派一个子代理（sub-agent：主 agent 派出去、各自独立干活的 agent）， 而且是并行的——SKILL.md 的原文是「Send a single message with two Agent tool calls」，一条消息里同时发出两个调用，两个都用 general-purpose 类型的子代理。并行的理由不是省时间，是隔离： 两个子代理各自抱着干净的上下文进场，Standards 的结论不会影响 Spec 的判断，反过来也一样—— 这正是第 3 节「绝不合并」在执行层面的落实。

每个子代理的 prompt 里必须装什么，SKILL.md 列得很细：

两个细节值得记住：其一，400 词上限写在两个任务书里，是防止子代理把 「审查报告」写成「重构论文」的缰绳；其二，第 2 步如果已经确定没有 spec， Spec 子代理根本不派，只在最终报告里注明——省一次调用，也堵住编需求的路。

7.2 第 5 步：聚合的两条红线

两个子代理交回报告后，主 agent 只做整理，不做裁决：

1. 把两份报告分别放在 ## Standards 和 ## Spec 两个标题下， 原文照摆，最多轻度清理排版。
2. 结尾给一行总结：每条轴各有多少条 findings、本轴内部最严重的是哪条（如果有）。

两条红线明文写在 SKILL.md 里：不合并、不重排（do not merge or rerank findings）， 以及不跨轴选总赢家（don't pick a single winner across axes）。 跨轴排名正是两条轴之所以要分开的理由想要防的事——一旦说一句「总体还行」， 一条轴的失败就被另一条轴的通过平均掉了（第 3 节的两种失败组合）。 总结行里「每轴最严重一条」是允许的，因为那是轴内的比较，没有跨轴。

原文：code-review/SKILL.md「### 4. Spawn both sub-agents in parallel」与「### 5. Aggregate」

8. 跑完一次长什么样

把五步串起来看一个虚构的例子。假设你在分支 feature/invite-emails 上， 输入 /code-review main：

1. 钉固定点：git rev-parse main 通过；git diff main...HEAD 拿到 3 个文件、约 200 行的 diff；git log main..HEAD --oneline 列出 4 个提交， 其中一个提交信息里写着 Closes #45。
2. 找 spec：命中第一级——按 docs/agents/issue-tracker.md 的流程 取回 Issue #45，正文里有一条「invite links expire after 7 days」。
3. 找标准：仓库里有 CODING_STANDARDS.md，其中一条是 「错误必须包一层领域错误再抛出」；再叠上 12 条异味基线。
4. 派子代理：一条消息发出两个 general-purpose 子代理， Standards 的 prompt 里照贴了基线全文，Spec 的 prompt 里是 Issue #45 的内容。
5. 聚合：两份报告并排摆出，结尾一行总结。

最终报告的形状大致是（以下为教学用虚构示例）：

## Standards
- src/invite/send.ts:42 — 违反 CODING_STANDARDS.md「错误必须包一层领域错误」：
  直接把 axios 的原始错误抛给了调用者。（硬性违规）
- src/invite/send.ts:88 — 可能的 Feature Envy：buildEmail() 读了 user 对象的
  7 个字段，自己所在模块的字段一个没用。（裁量项）

## Spec
- 缺失：Issue #45 要求「invite links expire after 7 days」，
  diff 中没有任何与过期时间相关的实现。
- 范围蔓延：新增了 spec 未要求的 Slack 通知开关
  （spec 中无对应行）。

—— Standards 2 条（最重：错误未包装）；Spec 2 条（最重：过期时间未实现）

注意这份报告的形状纪律：两节分开、每条都带出处（标准的文件名加规则、spec 的原文行）、 异味标着「可能的」、总结行按轴分开说、没有一句跨轴的总评。 拿到它之后怎么行动是你或下一个流程的事——这个 skill 到此为止。

9. 会留下什么、用完接什么、想微调改哪里

9.1 副作用：只读，一个字都不写

9.2 用完之后，下一步去哪

1. 报告里有 findings → 逐条修掉，然后固定点不变、指着新的 HEAD 再跑一次 /code-review，直到两轴都干净或你都认了。
2. 它是在 implement 流程里被自动跑的 → 通过之后，commit 是 implement 的职责（它的 SKILL.md 最后一行：「Commit your work to the current branch」），不是 code-review 的。
3. Spec 轴报了 "no spec available" → 如果这次改动本该有需求出处， 回头用 to-spec（0009）补一份 spec 再审；如果只是随手小改， 接受只有 Standards 轴的结果就好。
4. 审的是别人的 PR → 报告贴不贴回 PR、怎么贴，由你决定； 这个 skill 不替你对外发任何东西。

9.3 行为不对时，去改哪个文件的哪一段

这个 skill 的全部行为都装在唯一一个 SKILL.md 里（没有 sibling 参考文件）， 所以微调入口很好找——按下表对号改对应小节，别去改无关的地方：

10. 检索练习

先别往回翻，凭记忆答。选项的长度刻意对齐，不会从版式泄题。答错的题号回到对应小节重读后再选。

11. 下一课与一手材料

本课主一手材料（请打开原文读，不要只背本页摘要）：

• skills/engineering/code-review/SKILL.md —— 首选 primary source。五步流程、12 条异味基线、两个子代理的任务书原文、聚合红线、Why two axes，全部在这一个文件里。
• docs/engineering/code-review.md —— 给人看的叙事版（aihero.dev/skills-code-review）： 「什么时候伸手」「前置条件」「它在哪」三节是本课的骨架。
• 上下游对照： implement/SKILL.md（唯一的调用方，commit 前收尾跑它）· ask-matt/SKILL.md（主 flow 第 3 步的定位句）。

速查页（本课同步）： reference/code-review.html

导航： 上一课 0012 tdd （构建中的纪律：先写测试再写实现，活在接缝上）。 总览仍回 0001 系统地图。

建议下一课（0014）： 0014 triage。 code-review 是主 build 链的收尾；triage 是另一条 on-ramp 的入口—— 别人的 bug 报告和功能请求堆进 Issue tracker 时，它把原始 Issue 分拣成 agent 可以直接接手的成品 Issue，然后交给 implement 走回主链， 最后又会来到你刚学完的这道审查。