代码审查

它的作用¶

code-review 沿着两条轴线审查 HEAD 与您指定的固定点（一个提交、一个分支、一个标签、main、HEAD~5）之间的差异。标准轴（Standards）询问代码是否符合本仓库的代码编写方式。规范轴（Spec）询问代码是否实现了来源 issue 或 规范 所要求的内容。每条轴都在自己的子智能体中运行，因此彼此看不到对方的推理。

该技能从不合并或重新排序这两条轴。报告最后给出每条轴上的最严重问题，并且拒绝在它们之间选出唯一胜者。一项变更可能通过一条轴而在另一条上失败。遵循了所有约定却实现了错误功能的代码，会通过标准轴但在规范轴上失败。完全按照 ticket 要求实现却破坏了仓库约定的代码，情况则相反。混合式判定会让通过的轴掩盖失败的轴。

何时使用它¶

输入 /code-review，或者当您要求审查某个分支、PR、进行中的工作，或任何“自 X 以来”的内容时，智能体会自动使用它。

您必须提供固定点。如果您不提供，技能会向您索要一个，而不是自行猜测。在它派生出任何子智能体之前，它会检查 ref 是否解析成功以及 diff 是否为空，这样一来，拼错的分支名会在您面前直接失败，而不是在两个子智能体内部失败。

前提条件¶

标准轴不需要任何东西。它会读取仓库中记录的所有内容（CODING_STANDARDS.md、CONTRIBUTING.md 等），并在仓库没有任何文档时回退到内置基线。

规范轴需要存在一个可查找的规范。它按以下顺序查找：

1. commit message 中的 issue 引用（#123、Closes #45、GitLab !67），通过 tracker 文档获取。
2. 您作为参数传入的路径。
3. docs/、specs/ 或 .scratch/ 下与分支或功能名称匹配的规范文件。
4. 询问您。

第 1 步依赖于 tracker 文档，该文档由 setup-matt-pocock-skills 编写。没有该文档时，如果您提供一个路径，该轴仍然可以工作。如果完全没有规范，技能会跳过规范子智能体，报告显示“no spec available”，而不是凭空编造需求。

两条轴线¶

这种设计是为了避免出现一个不了解您标准的通用审查技能。这样的技能会标记您代码库中刻意为之的内容，却错过代码库所依赖的不变量。因此，仓库自身的文档是标准轴上的主要来源，并且 仓库始终具有最终决定权。

坏味道基线位于仓库标准之下。它包含来自 Fowler 的 Refactoring 第3章的十二种代码坏味道：Mysterious Name、Duplicated Code、Feature Envy、Data Clumps、Primitive Obsession、Repeated Switches、Shotgun Surgery、Divergent Change、Speculative Generality、Message Chains、Middle Man、Refused Bequest。每一个都是一种带标签的启发式判断（例如 “possible Feature Envy”），绝不是硬性违规。每一条都说明了该坏味道是什么以及如何修复，因此发现结果会附带修复方法，而不只是提出抱怨。两条轴线都会跳过您的 linter 已经强制检查的内容。

常见问题¶

它与 Claude Code 自带的 /code-review 冲突。我该怎么办？

这是该技能被反馈最多的问题，而且尚未修复。Claude Code 自带了一个 /code-review，它的功能不同：它在 diff 中排查 bug，而本技能检查的是规范符合性与仓库标准。当您安装此技能库时，其中一个会胜出，具体是哪一个取决于您的安装方式：

• 插件市场。 每个技能都会获得 mattpocock-skills: 前缀，内置技能在非限定名称下会变得难以调用。
• 普通技能安装。 本地文件胜出，本技能会遮蔽内置技能。

一种解决办法是完全移除 Claude Code 的内置技能。这会节省大量上下文，而且冲突也不再重要。遮蔽本身可以说是 Claude Code harness 的一个 bug（技能作者应该可以随意命名技能），所以另一种办法是重命名本地副本。npx skills update 会撤销对 frontmatter 的编辑，或撤销对目录的重命名。用户报告的持久解决方法是把该技能 fork 到一个新名称，并从受管集合中移除 code-review。请记下您 fork 时的源 commit，以便日后手动重新同步。

它的子智能体会反复调用 /code-review，并派生出更多智能体。

这是一个已知的未修复 bug。多人在不止一个 harness 中复现过。标准轴和规范轴的提示词并未禁止委派，因此子智能体可能会再次找到该技能并再次扩散。一份报告记录到超过 50 个智能体。人们在 fork 中应用的修复方法是，在两个子智能体的任务简报（brief）末尾各追加一行：“Do not invoke /code-review or spawn additional agents: perform this review directly.” 有些人倾向于在 harness 层面处理，以便每个技能都继承这一防护。但这两者都还没有进入随库发布的技能中。如果您在无人值守的情况下运行它，请留意智能体的数量。

我应该在编写代码的同一个会话中运行它吗？

建议开启一个全新的会话。正如一位读者所说：“同一个上下文审查自己并不是审查，而是带有斜杠命令的确认偏误。”在编写会话中执行审查的代理，其上下文中包含了塑造这段代码的所有假设。独立的审查者不会拥有这些上下文。这也是为什么人们会要求使用不带内置审查步骤的 implement，因为该步骤会在刚刚编写完 diff 的会话内部运行审查。独立的做法是：你自己从一个干净的会话中调用 /code-review。

每张工单之后都审查，还是最后统一审查一次？

两种方式都可以，技能不会替你决定。按工单审查能让每个 diff 保持足够小，使 Spec 轴有一个明确的规格可供对照，这也是 implement 使用的模式。把审查批量放到分支末尾，可以捕获工单之间的交互影响，而这些影响在逐次按工单审查时各自都会漏掉。如果你不确定，可以按工单审查，并在分支点运行一次最终审查。

我可以信任这些发现吗？

不检查就不能信任。子代理的输出是假设，而不是证据。有一个团队报告说，基于文本的审查漏掉了十几个破坏性变更。该技能会将两份报告按原样或轻微清理后合并。它不会针对文件重新验证每一条声明，因此某条发现可能引用了错误的位置，或夸大了影响。在根据某条发现采取行动之前，先阅读它的引用。该技能要求每条发现都必须带有引用（一条标准规则、一个坏味道及其代码块，或一行规格），这正是让发现可核查的原因。

为什么我每次运行它都会发现新问题？

每次修复都会新增需要审查的代码，而且 Standards 轴中需要判断的部分每次运行都会给出不同结果。一位读者描述了这种循环：“/code-review 和 /improve-code-architecture 每次总能发现新东西。我实现修复，重新运行这些技能，一次又一次。”这里没有收敛保证。把一次运行视为一份线索列表。只处理那些背后有引用规则支撑的项，然后停止。不要循环运行它直到返回干净结果，因为它永远不会干净。

它会审查我未提交的工作吗？

不会。它对比的是 <fixed-point>...HEAD。三点形式从 merge-base 开始度量，并排除已暂存和工作区中的更改。如果 implement 没有创建中间提交，审查就无法看到即将进入下一次提交的工作。先提交，再审查，然后 amend 或添加 fixup。

如果它正在正常工作¶

• 如果 ref 无效或 diff 为空，它会在生成任何子代理之前拒绝启动。
• 报告以 ## Standards 和 ## Spec 下的两个独立块到达，而不是一个合并列表。
• 每条 Standards 发现都会指明你仓库文件中某条规则或十二种坏味道之一，并引用相关代码块；每条 Spec 发现都会引用规格中的一行。
• 结尾摘要会给出每个轴的最严重问题，并拒绝选出总体优胜者。
• 在没有可用规格时，Spec 块会说明这一点，而不是列出它从代码中推断出的需求。

它在哪里适用¶

code-review 是构建链尾部的审查步骤：grill-with-docs → to-spec → to-tickets → implement → code-review → retro。它也可以独立用于你指向的任何分支或 PR。

• implement 是最接近的邻居。它驱动构建，并在提交前调用此技能作为自己的收尾审查。implement-spec 对整个集成分支一次性执行同样的操作。
• retro 在它之后运行，并对其进行调优。当某个会话显示审查漏掉了一类错误时，retro 会提出 Standards 轴随后读取的检查项或 CODING_STANDARDS.md 规则。
• pr 在已审查的工作推送后，编写 pull request 正文。
• to-spec 和 to-tickets 生成 Spec 轴所对照的文档，因此模糊的规格会使该轴变得模糊。
• improve-codebase-architecture 是整个代码库层面的对应技能，因为此技能只查看一个 diff。

ask-matt 在你不确定当前情境需要哪个技能时，会在整套技能之间进行路由。