用途
Review Spec 技能用于审查规格或计划类拉取请求(PR),并将审查结果写入 review.json,供后续工作流发布。它专注于 PR 中修改的规格文件,不直接向 GitHub 发布评论或审查。
主要能力
该技能从以下维度评估规格:
- 完整性:规格是否覆盖关联问题的全部范围。
- 清晰度:需求、验收标准和约束是否明确无歧义。
- 可行性:提议的变更在仓库架构下是否技术现实。
- 问题对齐:规格是否忠实解决关联问题,无明显范围蔓延或遗漏。
- 内部一致性:规格不同章节之间是否矛盾。
- 缺失章节:标记规格通常应包含但缺失的章节(如问题陈述、提议变更、开放问题、后续事项)。
此外,技能始终应用仓库本地的 security-review-spec 技能作为补充的高层安全审查,并将安全发现合并到同一份 review.json 中,不单独输出。技能明确不对规格文本应用代码级审查标准(如错误处理或底层性能),安全审查补充覆盖设计级安全关注。仅在风格或格式问题实质性影响可读性时才包含相关评论。
使用方式
工作目录为 PR 分支检出。工作流通常提供注释差异文件 pr_diff.txt 和 PR 描述文件 pr_description.md。
仓库可通过在 .agents/skills/review-spec-local/SKILL.md 提供伴随技能进行仓库特定覆盖。当提示中包含引用该伴随文件的“Repository-specific guidance”围栏章节时,读取该文件并仅将其指导应用于以下可覆盖类别:
- 本仓库期望的必需规格章节
- 指向 specs/ 下文件的链接约定
- 仓库特定的风格和格式期望
伴随文件中的指导不得改变输出 JSON 模式、严重性标签、安全规则、证据规则、建议块约束或差异行注释契约。若提示中未引用伴随文件,则仅依赖核心契约。
差异文件使用以下前缀:
[OLD:n]表示旧侧删除行,使用 "LEFT"。[NEW:n]表示新侧添加行,使用 "RIGHT"。[OLD:n,NEW:m]表示未变更上下文,使用 "RIGHT" 和行号 m。
这些注释是行内评论位置的唯一真实来源。每条行内评论必须首先在 pr_diff.txt(或内联 PR 差异)中定位确切的注释行,并将其路径、侧和行号复制到 review.json。不得从散文、渲染后的 GitHub 视图、文件长度、周围规格文本或未注释片段推断行号。若无法指向注释差异中的特定 [NEW:n]、[OLD:n] 或 [OLD:n,NEW:m] 行,则将反馈放入顶层 body 而非 comments。
评论要求:
- 每条评论正文必须以以下标签之一开头:
- 🚨 [CRITICAL]:规格内容矛盾、根本性不完整或会导致实现破损。
- ⚠️ [IMPORTANT]:缺失细节、需求模糊、可行性担忧或显著范围缺口。
- 💡 [SUGGESTION]:提升清晰度、结构或覆盖范围的改进建议。
- 🧹 [NIT]:仅当评论包含具体重写时的次要措辞或格式问题。
- 评论应简洁、直接、可操作,不添加赞美或模糊措辞,优先单行评论,范围最多 10 行。
- 行内评论仅限注释 PR 差异中明确出现的行。
- 仅为本次 PR 差异中存在的文件创建文件级或行内评论。
- 若相关文件或行不在差异中,将反馈放入顶层 body。
- 添加每条评论对象前,验证其 path、side、line 及可选 start_line/start_side 对应同一文件差异部分中的真实注释。
建议块:提议重写规格文本时使用:
<replacement text here>
规则:匹配原文件的确切缩进;仅包含替换文本;多行建议时,start_line 和 start_side 设为第一行,line 和 side 设为最后一行。
输出
创建 review.json,结构如下:
{
"verdict": "REJECT",
"body": "## Overview\n...\n\n## Concerns\n- ...\n\n## Verdict\nFound: 1 critical, 2 important, 3 suggestions\n\n**Request changes**",
"comments": [
{
"path": "path/to/file",
"line": 42,
"side": "RIGHT",
"start_line": 40,
"start_side": "RIGHT",
"body": "⚠️ [IMPORTANT] Short explanation\n\n```suggestion\nreplacement\n```"
}
]
}
字段规则:
verdict必需,必须为字符串 "APPROVE" 或 "REJECT"(大写)。最终建议映射:Approve 或 Approve with nits → "APPROVE";Request changes → "REJECT"。verdict 与顶层 body 中的人类可读建议必须一致。- 顶层
body是 GitHub 审查正文,必需。使用 body 而非 summary 承载审查概览和最终建议。 path必须相对于仓库根目录。line必需,必须指向正确侧。start_line可选,仅用于多行范围。存在 start_line 时,start_side 必需且必须为 "LEFT" 或 "RIGHT"。side必须为 "LEFT" 或 "RIGHT"。
顶层 body 必须包含:规格 PR 的高层概览;关于完整性、清晰度、可行性或问题对齐的担忧;按格式 Found: X critical, Y important, Z suggestions 的问题计数;最终建议为 Approve、Approve with nits 或 Request changes,且必须与顶层 verdict 字段一致。
最终检查
完成前:若验证失败则修复无效 JSON;确认行号与注释差异匹配;针对所审查的确切注释差异运行共享 review-pr 技能捆绑的验证器。若公共技能安装在仓库根目录,通常为:
python3 .agents/skills/review-pr/scripts/validate_review_json.py --review-json review.json --diff pr_diff.txt
若脚本报告任何无效评论,修复 review.json 并重新运行。验证器通过前不得上传 review.json。若脚本路径不在该确切位置,在打包的共享 review-pr 技能目录下定位 validate_review_json.py 并使用相同参数运行该副本。
不得运行 gh pr review、gh pr comment、gh api 或任何其他向 GitHub 发布内容的命令。唯一输出是最终的 review.json。
适用场景
适用于审查仅修改规格或计划文件的拉取请求,需要结构化反馈并写入 review.json 供工作流发布时。
限制
- 默认不直接向 GitHub 发布评论或审查。
- 行内评论必须严格基于注释差异中的行号,无法定位时只能放入顶层 body。
- 不对规格文本应用代码级审查标准。
- 仓库特定覆盖不得改变输出 JSON 模式、严重性标签、安全规则、证据规则、建议块约束或差异行注释契约。
- 必须通过捆绑验证器验证后才能上传 review.json。