对 HEAD 与用户提供的固定点之间差异的双轴审查:
- 标准 — 代码是否符合此仓库文档化的编码标准?
- 规范 — 代码是否忠实地实现了原始议题 / PRD / 规范?
两个轴作为并行子代理运行,这样它们不会污染彼此的上下文,然后此技能汇总它们的结果。
如果尚未提供议题跟踪器,请运行 /setup-matt-pocock-skills(如果缺少 docs/agents/issue-tracker.md)。
流程
1. 确定固定点
用户所说的固定点是什么——提交SHA、分支名称、标签、main、HEAD~5 等。如果他们没有指定,请询问。
捕获一次差异命令:git diff <fixed-point>...HEAD(三点形式,因此比较是针对合并基准进行的)。同时通过 git log <fixed-point>..HEAD --oneline 记录提交列表。
在继续之前,确认固定点可以解析(git rev-parse <fixed-point>)并且差异非空。错误的引用或空的差异应在此处失败——而不是在两个并行子代理内部。
2. 确定规范来源
按以下顺序查找原始规范:
- 提交消息中的议题引用(
#123、Closes #45、GitLab!67等)——通过docs/agents/issue-tracker.md中的工作流程获取。 - 用户作为参数传递的路径。
docs/、specs/或.scratch/下与分支名称或功能匹配的 PRD/规范文件。- 如果未找到任何内容,请询问用户规范在哪里。如果用户说没有规范,则规范子代理将跳过并报告“无可用规范”。
3. 确定标准来源
仓库中任何记录代码编写方式的内容,例如 CODING_STANDARDS.md 或 CONTRIBUTING.md。
除了仓库记录的内容之外,标准轴始终附带下面的坏味道基线——一组固定的 Fowler 代码坏味道(《重构》,第3章),即使仓库没有任何文档化内容也适用。两条规则约束它:
- 仓库规则覆盖。 文档化的仓库标准始终优先;如果它认可基线会标记的内容,则抑制该坏味道。
- 始终是判断。 每种坏味道都是一个带标签的启发式方法(“可能的依恋情结”),绝不是一个硬性违反——与此处的任何标准一样,跳过工具已经强制执行的内容。
每个坏味道阅读它是什么 → 如何修复;将其与差异匹配:
- 神秘命名 — 函数、变量或类型的名称没有揭示其功能或内容。→ 重命名;如果想不到一个诚实的名称,说明设计很模糊。
- 重复代码 — 相同的逻辑结构出现在变更中的多个代码块或文件中。→ 提取共享的结构,从两个地方调用它。
- 依恋情结 — 方法访问另一个对象的数据多于其自身的数据。→ 将方法移动到它所依恋的数据上。
- 数据泥团 — 相同的几个字段或参数经常一起出现(一个等待诞生的类型)。→ 将它们捆绑成一个类型,传递该类型。
- 基本类型偏执 — 基本类型或字符串代替了应该有其自身类型的领域概念。→ 给这个概念一个自己小类型。
- 重复的 switch — 相同的
switch/if级联在变更中反复出现。→ 用多态替换,或使用两个站点共享的一个映射。 - 霰弹式修改 — 一个逻辑更改导致差异中许多文件出现分散的编辑。→ 将一起更改的内容集中到一个模块中。
- 发散式变化 — 一个文件或模块因多个不相关的原因而被编辑。→ 拆分,使每个模块因一个原因更改。
- 夸夸其谈未来性 — 为规范中没有的需求添加的抽象、参数或钩子。→ 删除;内联回来,直到出现真正的需求。
- 消息链 — 长
a.b().c().d()导航,调用者不应依赖它。→ 在第一个对象后面用一个方法隐藏遍历过程。 - 中间人 — 一个主要只是委托给其他对象的类或函数。→ 删除它,直接调用真正的目标。
- 被拒绝的遗赠 — 忽略或覆盖其继承的大多数内容的子类或实现者。→ 放弃继承,使用组合。
4. 并行生成两个子代理
发送一条包含两个 Agent 工具调用的消息。对两者都使用 general-purpose 子代理。
标准子代理提示 — 包含:
- 完整的差异命令和提交列表。
- 你在步骤3中找到的标准源文件列表,加上步骤3中的坏味道基线完整粘贴——子代理无法以其他方式访问它。
- 简要说明:“报告——在相关的每个文件/块中:(a) 差异违反文档化标准的每个地方:引用标准(文件 + 规则);以及 (b) 你发现的任何基线坏味道:命名并引用相关代码块。区分硬性违反和判断调用——文档化标准违规可能是硬性的,但基线坏味道始终是判断调用,并且文档化的仓库标准覆盖基线。跳过工具强制执行的内容。少于400字。”
规范子代理提示 — 包含:
- 差异命令和提交列表。
- 规范的路径或获取的内容。
- 简要说明:“报告:(a) 规范要求但缺失或不完整的;(b) 差异中未被要求的行为(范围蔓延);(c) 看起来已实现但实现方式错误的要求。为每个发现引用规范行。少于400字。”
如果规范缺失,跳过规范子代理并在最终报告中注明。
5. 汇总
在 ## Standards 和 ## Spec 标题下呈现两份报告,逐字或轻微清理。不要合并或重新排序发现——这两个轴是故意分开的(请参阅为什么有两个轴)。
以一行摘要结束:每个轴的总发现数,以及每个轴内最严重的问题(如果有)。不要在轴之间选一个胜者——那正是分离所要防止的重新排序。
为什么有两个轴
一个更改可能通过一个轴但在另一个轴上失败:
- 遵循每条标准但实现了错误内容的代码 → 标准通过,规范失败。
- 完全按照议题要求做了但违反了项目约定的代码 → 规范通过,标准失败。
分别报告它们可以防止一个轴掩盖另一个轴。