沿两个维度审查 HEAD 与用户提供的固定节点之间的 diff:
- 规范(Standards) —— 代码是否符合该仓库中记录的编码规范?
- 需求(Spec) —— 代码是否忠实地实现了最初的 issue / PRD / 需求文档?
两个维度作为并行子 Agent运行,以避免互相污染上下文,然后由本 Skill 汇总其发现的问题。
Issue 追踪工具应当已提供给你 —— 如果缺少 docs/agents/issue-tracker.md,请运行 /setup-matt-pocock-skills。
流程
1. 确定固定节点
用户指定的任何固定节点 —— 提交 SHA、分支名、标签、main、HEAD~5 等。如果用户未指定,请向其询问。
确定一次 diff 命令:git diff <fixed-point>...HEAD(使用三点语法,以便针对 merge-base 进行比较)。同时通过 git log <fixed-point>..HEAD --oneline 记录提交列表。
在继续之前,确认固定节点可以解析(git rev-parse <fixed-point>)且 diff 非空。无效的引用或空的 diff 应该在此时报错 —— 而不是在两个并行子 Agent 内部才报错。
2. 确定需求来源
按以下顺序查找原始需求规范:
- 提交信息中的 Issue 引用(
#123、Closes #45、GitLab!67等)—— 通过docs/agents/issue-tracker.md中的工作流获取。 - 用户作为参数传入的路径。
docs/、specs/或.scratch/下与分支名称或功能匹配的 PRD/需求规范文件。- 如果未找到任何内容,请询问用户需求文档所在位置。如果用户表示没有需求文档,**需求(Spec)**子 Agent 将跳过并报告“无可用需求文档”。
3. 确定规范来源
仓库中任何记录代码编写规范的文件,例如 CODING_STANDARDS.md 或 CONTRIBUTING.md。
4. 并行生成两个子 Agent
发送包含两个 Agent 工具调用的单条消息。两个子 Agent 均使用 general-purpose 类型。
规范(Standards)子 Agent 提示词 —— 包含:
- 完整的 diff 命令和提交列表。
- 你在步骤 3 中找到的规范源文件列表。
- 任务简报:“在相关位置按文件/代码块报告 diff 违反已记录规范的每一处。引用相应规范(文件 + 规则)。区分硬性违规与主观判断。跳过任何已由自动化工具强制执行的内容。字数在 400 字以内。”
需求(Spec)子 Agent 提示词 —— 包含:
- diff 命令和提交列表。
- 需求文档的路径或已获取的内容。
- 任务简报:“报告:(a) 需求中要求但缺失或仅部分实现的要求;(b) diff 中未被要求的行为(范围蔓延);(c) 看起来已实现但实现方式似乎有误的要求。每项发现均需引用需求原句。字数在 400 字以内。”
如果缺少需求文档,请跳过需求子 Agent,并在最终报告中予以说明。
5. 汇总
在 ## Standards 和 ## Spec 标题下展示两份报告,保持原样输出或进行轻微整理。不要合并或重新排列发现的问题 —— 这两个维度是有意分开的(参见_为什么采用双维度_)。
以单行总结结尾:列出每个维度的发现总数,以及_各个维度内_最严重的问题(如果有)。不要跨维度评选单一的最严重问题 —— 保持分离正是为了防止跨维度的重新排序。
为什么采用双维度
一项变更可能在一个维度上通过,但在另一个维度上失败:
- 代码遵循了每一条规范,但实现的内容完全错误 → 规范通过,需求失败。
- 代码完全符合 Issue 的要求,但破坏了项目的代码约定 → 需求通过,规范失败。
分别报告这两个维度可以防止一个维度掩盖另一个维度。