mcpField
P
pr-review

pr-review

github.com/tech-leads-club测试与质量7.1k43 次安装4 天前更新
代码仓库

关于 pr-review

pr-review 是专用于编排的技能，通过六个专项子 Agent 并行审查 GitHub 拉取请求。它会发现项目的测试、需求、约定和审查技能，让各审查者依据仓库自身规范开展工作。

主要功能

  1. 01并行协调六个子 Agent
  2. 02发现项目审查上下文
  3. 03与技术栈无关的审查编排
  4. 04按置信度筛选发现
  5. 05仅发布评论

适用场景

  1. 01协调并行拉取请求审查
  2. 02依据仓库约定调整审查
  3. 03按项目需求核对变更
  4. 04避免重复审查评论

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tech-leads-club/agent-skills --skill pr-review

安装后在 Claude Code 中输入/pr-review确认已加载。

详细介绍

PR Review — 自适应编排协议

通过 Task 工具协调 6 个专门的子 Agent，然后将它们的发现汇总为一份摘要。此技能与技术栈无关：它本身不定义任何规则，而是发现项目已有的文档内容——测试运行器、需求规范、架构约定、项目本地的审查技能——并由每个子 Agent 加载并应用该项目实际具备的内容。它绝不臆造特定技术栈的规则，也不重复项目文档。

执行约定（不可妥协）

此技能是一套仅用于编排的协议。请先阅读以下规则：

  1. 你是编排者。你绝不能分析差异、阅读源文件，或自行撰写任何审查发现。你唯一的工作是收集上下文（步骤 1）、启动子 Agent（步骤 2），以及启动负责汇总的子 Agent（步骤 3）。
  2. 六项审查必须由六个独立的通用子 Agent执行（不受工具集限制），并且必须在单个批次中并行启动。使用运行环境提供的任意子 Agent／并行任务机制（在 Claude Code 中使用 Task 工具）。
  3. 在当前对话中执行审查——哪怕只执行一部分，哪怕是“为了节省时间”，哪怕差异很小——都属于此技能的失败。差异大小不构成例外。
  4. 每个子 Agent 的提示词都必须自包含：需提供 {REPO}、{PR}、{SHA}、差异、PR 意图、现有评论位置以及 DISCOVERY MAP。子 Agent 不会共享你的上下文。

**宿主前提：**通过 gh CLI 操作 GitHub 拉取请求——以下每次获取和发布操作都使用 gh。“与技术栈无关”指与语言和框架无关，不表示与宿主平台无关：托管在 GitLab／Bitbucket 上的仓库（使用 MR 而非 PR）不在适用范围内。

仅支持显式调用（disable-model-invocation: true）。编码期间绝不自动触发。

步骤 1：初始化

1a. PR 上下文
  1. 从用户请求中确定 PR 编号；若缺失则询问。
  2. 确定仓库：gh repo view --json nameWithOwner -q .nameWithOwner → {REPO}。
  3. 获取差异：gh pr diff {PR}。获取 head SHA：gh pr view {PR} --json headRefOid -q .headRefOid → {SHA}（这是为行内评论指定位置所必需的）。
  4. 加载现有行内评论：gh api repos/{REPO}/pulls/{PR}/comments — 建立 {id, path, line} 记录集合：使用 {path, line} 避免重复发布评论，保留每条评论的正文以识别已解决的问题，并保留每条评论的 id 以发布串联回复。
  5. 阅读 PR 意图：gh pr view {PR} --json title,body,headRefName。
1b. 项目发现（自适应骨干）

探查一次代码仓库，并记录一份项目概况——下方的 DISCOVERY MAP——逐字传递给每个子 Agent。在这一步投入足够精力；这是让审查贴合当前项目的关键。**优先采用项目明确声明的证据，而非猜测。**只检测实际存在的内容；缺少的内容标记为 none。

  • 测试运行器 + 布局——查找 CI 实际运行的命令。按以下顺序检查：CI 工作流（.github/workflows/*——或代码仓库使用的任何 CI 配置，例如 .gitlab-ci.yml，仅用于找出实际测试命令），将其视为权威来源；然后再参考清单文件（package.json 脚本、pyproject.toml/tox.ini/pytest.ini、go.mod、Cargo.toml、Gemfile、Makefile、*.gradle）。根据现有测试推导测试文件 glob（例如 *.spec.ts、*_test.go、test_*.py、*_spec.rb），并记录代码仓库采用的单元测试与集成测试/e2e 测试划分。
  • 需求来源——(A) 分支名称或 PR 正文中的问题跟踪器编号（例如 Jira/Linear 的 [A-Z]+-\d+、GitHub issue 的 #\d+ 或 owner/repo#\d+、完整工单 URL）；(B) 代码仓库内的规范/需求文件：.specs/ 树、docs/、*-spec.md、*-tasks.md、PRD 文件，或 ADR/RFC 目录。
  • 架构/约定文档——记录说明项目规则的文件：CONTRIBUTING*、ARCHITECTURE*、CONVENTIONS*、docs/** 中的约定文件、AGENTS.md、CLAUDE.md，以及代码仓库保留的任何编码/集成/安全模式文档。记录路径；暂时不要阅读，负责的子 Agent 会阅读。
  • 项目本地审查技能——扫描技能目录（.claude/skills/、.cursor/skills/、.codex/skills/、.github/），查找涵盖测试、架构/模块化或安全的技能。记录其 SKILL.md 路径，以便子 Agent 加载项目自身的参考资料，而非自行猜测。

简洁记录该映射，并逐字传递给每个子 Agent：

TEST:          <command> | globs: <...> | unit vs e2e: <split | none> | none-found
REQS:          tracker=<Jira KEY-123 | GH #42 | Linear ABC-7 | none> ; specs=<paths | none>
CONVENTIONS:   <doc/skill paths that state rules | none-found>
REVIEW_SKILLS: <project-local test/arch skill paths | none>

每个子 Agent 只能加载映射中列出的内容；若某个类别为 none，则回退到该部分的通用检查清单，并注明这一点。

第 2 步：并行启动子 Agent

发送一条消息，其中包含六个 Task 工具调用，并同时启动。每个子 Agent 都是独立的——它无法看到此对话，因此其提示词必须包含完整上下文：{REPO}、{PR}、{SHA}、差异、现有的 {id,path,line} 评论集、PR 意图，以及项目概况（上方的 DISCOVERY MAP）。六个子 Agent 全部完成后，执行第 3 步。

严重程度标签（所有子 Agent 均使用）

  • 🚨 严重 — 会导致故障的 Bug 或逻辑错误
  • 🔒 安全 — 漏洞或数据泄露
  • ⚡ 性能 — 重大性能问题
  • ⚠️ 警告 — 代码异味或可维护性问题
  • 💡 建议 — 可选改进

通用规则（每个子 Agent 和整合步骤都必须遵守）

  1. 评论发布机制 — 切勿发布格式损坏的正文。 对于任何多行评论或摘要，先将正文写入临时文件，再使用 --body-file 或 -F body=@file 发布。请参阅下方的准确命令。这是最常见的失败原因 — 务必正确操作。
  2. 评论允许列表： 仅在以 + 开头的差异行上发布行内评论（绝不在 +++ 上评论）。将评论锚定到作为证据的确切 + 行。
  3. 跳过重复评论： 如果 {path, line} 周围 ±3 行内已有评论，则跳过。
  4. 标记已解决： 对于差异中已修复其问题的现有评论，回复 [RESOLVED] This appears resolved by the recent changes. — 使用下方的回复端点在该评论线程中发布，并使用步骤 1a.4 中该评论的 id。
  5. 置信度门槛： 仅报告置信度 ≥80% 的发现。不确定时保持沉默。
  6. 正面亮点： 每个子 Agent 在列出问题前，至少指出一个做得好的方面。
  7. 仅发表评论，绝不执行破坏性操作： 绝不使用 --approve 或 --request-changes，也绝不修改文件。仅使用 --comment。
  8. 不提及归属： 评论正文中绝不提及 AI、助手、模型或任何工具。以评审者的身份撰写。
  9. 标记： 每条行内评论正文都必须以 `` 开头（渲染后不可见；整合步骤会解析它）。{type} ∈ security | requirements | tests | architecture | regression | performance。
  10. 语气： 具体、可操作、友善协作。始终解释原因。
评论发布命令（原样复制）

先将正文写入临时文件（例如 body.md），然后：

对新增行发布行内评审评论：

gh api repos/{REPO}/pulls/{PR}/comments \
  -F [email protected] -f commit_id={SHA} -f path={path} -F line={N} -f side=RIGHT

line={N} 是头文件 RIGHT 侧的 从 1 开始的行号 — 从 hunk 标题中的 +c 起始行开始计数，并包含新增行和上下文行。它不是差异或 hunk 的相对偏移；使用差异相对位置会返回 422 错误，或将评论发到错误行上。

在现有评论线程中回复（针对规则 4 [RESOLVED]），使用步骤 1a.4 中的 {COMMENT_ID}：

gh api repos/{REPO}/pulls/{PR}/comments/{COMMENT_ID}/replies -F [email protected]

PR 级摘要（Requirements 子 Agent 和整合步骤）：

gh pr review {PR} --comment --body-file body.md

-F/--field 会将 @file 展开为文件内容，并将数字字段识别为数字；-f/--raw-field 不会 — -f [email protected] 会发布字面字符串 @body.md，而不是你的评论。因此：正文使用 -F body=@file，行号使用 -F line=N，普通字符串字段（commit_id、path、side）使用 -f。绝不要使用 -f body=@file。如果不确定正文该如何传递，优先使用 --body-file。

子 Agent 1：安全 — ``

如果配置文件列出了安全或集成规范文档，或安全专项项目技能（来自 CONVENTIONS / REVIEW_SKILLS），请加载这些内容，并先按照其中的规则评审差异。然后无论如何都要执行以下通用检查：硬编码的密钥或凭据；新端点缺少身份验证或授权；日志中包含个人身份信息或机密；缺少 webhook 或回调签名验证；CORS 权限过于宽泛；未经净化的输入被用于查询、命令或模板（注入）；不安全的反序列化；用户拥有的资源存在访问控制缺陷；响应载荷泄露敏感字段；内部客户端或密钥跨模块边界导出。

第二轮检查（必须执行）： 从头到尾重新阅读完整差异。列出所有未发表评论的文件或代码块。针对每一项，询问：“是否违反我职责范围内的任何安全规则？”只有在能够明确说明文件为何没有问题时，才可跳过该文件。

评论格式：


🔒 Security — [Short title]
[What the issue is and why it matters]
**Recommendation:** [Specific fix]

子 Agent 2：需求与完成定义 — ``

仅发布一条 PR 级摘要评论 — 不发布行内评论。

通过两种途径发现需求（从配置文件的 REQS 获取）。两种途径都要执行；采用能够获取到内容的途径。

跟踪路径 A — 问题跟踪器

从分支名称或 PR 正文中提取工单／问题编号，然后使用环境允许的方式获取相关内容。根据项目使用的问题跟踪器进行调整：

  • GitHub 问题 #N → gh issue view {N} --json title,body（或使用 owner/repo#N 格式）。
  • Jira KEY-123 → 使用项目已配置的 Jira CLI 或 Atlassian MCP（问题摘要 + 描述 + 验收标准）。只能使用环境中已配置的主机／凭据，绝不要编造或硬编码 Jira 主机。
  • Linear／其他 → 使用项目文档中指定的方式。

解析验收标准、用户故事和 DoD 项目。如果没有编号或凭据，则跳过跟踪路径 A，转到跟踪路径 B。

跟踪路径 B — 仓库内的规范文件

扫描 PR 标题／正文，查找引用的规范／任务文件（明确路径、Markdown 链接、spec:／tasks: 提及）。还要检查项目配置中的 .specs/、docs/、ADR／RFC 目录，查找与分支、工单或功能名称匹配的文件（按文件名主体进行模糊匹配）。阅读每个候选文件，提取验收标准、任务清单项以及声明的目标／非目标。ADR／RFC 中的“Decision”和“Consequences”部分也视为需求。

判定逻辑
含有内容的跟踪路径操作
A 和 B 都有合并需求；注明每项的来源
只有 A使用跟踪器需求
只有 B使用规范文件需求
都没有发布：⚠️ No issue ticket or spec file found — requirements verification skipped. 并停止

逐项评估，以证据为依据。 对每项标准，定位实现代码并标记为 ✅ 已实现（引用 path:line）、🟡 部分实现（缺少有意义的子句）或 ❌ 未实现。没有找到证据 ⇒ 不算实现——绝不要仅凭 PR 描述重述了意图就判定为已实现。测试只执行某项行为、但未断言该行为，不算验证通过。

第二轮检查（必须）： 逐项重新阅读合并后的需求列表，并问：“我是否针对差异逐项评估了这条需求？” 根据实际差异，为每个未评估项标记 ✅／🟡／❌。

摘要格式：


## 📋 Requirements Review
**Sources:** {e.g. "Jira: KEY-123" | "Spec: .specs/<feature>/spec.md" | "Both" | "None"}
### ✅ Implemented   — [criterion — `path:line`]
### 🟡 Partial       — [criterion — what's missing]
### ❌ Missing        — [criterion]
### 🔲 Definition of Done   — [x] covered / [ ] not covered
### 💬 Notes

子 Agent 3：测试覆盖 — ``

使用项目配置中的 TEST 运行器和目录布局，了解测试应放在哪里，以及在本项目中什么才算“正确的测试”。如果 REVIEW_SKILLS 列出了项目本地的测试技能，加载并使用该技能，将其模式作为测试位置、命名、设置／拆卸和断言风格的参考。否则应用通用标准。不要强加项目未使用的框架。

检查差异中是否存在以下问题：新增或变更的行为没有相应测试（对于公开／入口行为——新增端点、处理器、导出函数、事件／队列消费者、作业——属于 🚨 严重问题）；所需测试级别错误（纯逻辑需要单元测试；可观察的 I/O——HTTP／持久化／队列——需要集成／端到端测试；同时涉及两者的行为需要两种测试）；以及质量缺陷（测试位置不符合项目布局、缺少清理／拆卸、没有固定数据／工厂、ID 硬编码、缺少负面／错误场景、断言只执行行为却没有断言结果）。

第二轮检查（必须）： 重新阅读完整差异。列出所有你尚未评论的新增／修改入口点（端点、导出函数、处理器、消费者）。对于每一项，询问：“是否有测试在正确级别覆盖了正常路径和至少一个错误场景？” 只有在能够说明覆盖已存在或不适用时才可跳过。

评论格式：


[🚨/⚠️/💡] — [Short title]
[The coverage gap or test anti-pattern]
**Recommendation:** [Test to add, at which level, following project patterns]

子 Agent 4：架构与惯例 — ``

阶段 0 — 加载项目自身的约定来源

加载配置文件中列出的所有架构／约定文档和项目本地架构技能（CONVENTIONS + REVIEW_SKILLS），并阅读至文件末尾——不要跳过任何内容，也不要用技术栈知识替代项目文档中的规则。如果配置文件中没有列出任何内容，则执行最低限度的通用检查（遵守模块边界、不违反分层、不进行循环／跨边界导入，命名与相邻代码保持一致），并在每条评论中说明未找到项目约定文档。

阶段 1 — 提取规则矩阵（不要硬编码）

阅读每份已加载的文档，并提取其中明确写出的所有规则——检查清单项（□／- [ ]）、✅ do／❌ don't 条目、“必须”／“绝不”陈述、结构约束——整理成一个编号列表。编号从 1 开始，依次递增。不得添加文档未说明的内容；不得遗漏找到的任何内容。此编号列表根据项目自身的文档生成，是评估矩阵。

阶段 2 — 按文件逐一评估矩阵

对于每个已更改的文件，按规则判定 PASS / VIOLATION / N/A。只有当某条规则在结构上不适用于该文件类型时，才可标记为 N/A。对于每项 VIOLATION，在对应的 + 行上添加行内评论，并注明规则编号及其来源文档。

**第二轮（必须执行）：**完成矩阵评估后，重新阅读完整差异。列出每个尚未评估的文件，并再次对其运行矩阵。只有说明哪些规则为 N/A 及原因后，才能跳过文件。

评论格式：


[🚨/⚠️/💡] — [Short title]
Rule: [number + source doc, e.g. "Rule 8 — CONTRIBUTING.md Module Boundaries"]
[What in the diff violates it — quote the offending line]
**Recommendation:** [Exact fix; code snippet if < 6 lines]

子 Agent 5：回归与幻觉检测 — ``

检查差异中是否包含与 PR 声明目的无关的更改，或带有机器生成痕迹的更改：删除与更改无关的代码（🚨）、导入／引用仓库中不存在的符号（🚨）、调用时签名或参数数量错误（🚨）、在生产路径中留下 TODO／FIXME／存根、用类型断言或强制转换掩盖实际类型错误、重复实现代码库已有的逻辑、削弱错误处理或验证、静默吞掉错误、削弱或删除测试断言，以及永远不会执行的死代码。

**第二轮（必须执行）：**重新阅读完整差异。列出每个未发表评论的文件，并询问：“此处是否存在无关删除、虚假引用、重复逻辑或被削弱的断言？”只有能够说明为何这些问题都不适用时，才能跳过。

评论格式：


[🚨/⚠️/💡] — [Short title]
Type: [unrelated-deletion | phantom-reference | wrong-signature | duplicate | weakened-check | dead-code]
[Specific description with quoted evidence from the diff]
**Recommendation:** [Exact fix]

子 Agent 6：性能 — ``

如果配置文件列出了数据访问或性能约定文档，则加载这些文档作为项目预期模式的参考。只指出在差异中明确可见的问题——不要推测。检查：循环中执行查询／查找（N+1）、没有分页或限制的无界获取、延迟加载的关联关系导致逐行 I/O、可并发执行的独立操作却使用顺序 await／阻塞调用、在循环中重复计算不变的值，以及本应共用一个事务／批次的多次写入。

**第二轮（必须执行）：**重新阅读完整差异。列出每个未发表评论的函数、查询和循环，并询问：“此处是否存在明确可见的性能问题？”只有能够说明为何这些问题都不适用时，才能跳过。

评论格式：


⚡ Performance — [Short title]
[Description with estimated impact, e.g. "O(N) queries per request"]
**Recommendation:** [Fix with short code sketch if < 6 lines]

第 3 步：汇总

全部 6 个子 Agent 完成后，再启动一个 Task 子 Agent 进行汇总：

  1. gh api repos/{REPO}/pulls/{PR}/comments — 获取所有行内评论。
  2. 保留正文以 `` summary: 开头的评论。gh api repos/{REPO}/pulls/{PR}/reviews。Requirements 子 Agent 通过 gh pr review --comment 发布该评论，因此它属于 review 正文——不是行内 /pulls/{PR}/comments 条目（第 3.1 步），也不是 /issues/{PR}/comments 条目。保留正文包含该标记的 review。
  3. 按严重程度对发现项分组：🔒 安全 → 🚨 严重 → ⚡ 性能 → ⚠️ 警告 → 💡 建议。
  4. 对相同 {path, line}（±3 行）的发现项去重；在条目中注明每个提供该发现项的子 Agent。
  5. 收集每个子 Agent 的一条正面亮点。
  6. **差距检测：**运行 gh pr diff {PR} --name-only，获取完整的变更文件列表。将其与所有收到行内评论的路径交叉比对。在 ### 🔍 Files With No Inline Comments 下列出任何没有行内评论的变更逻辑文件。仅省略配置文件/锁定文件（*.json、*.yaml、*.lock）和不含逻辑的纯类型/声明文件。
  7. 将汇总写入临时文件，并发布：gh pr review {PR} --comment --body-file summary.md。

汇总格式：

## 📋 PR Review Summary

| | |
|---|---|
| **Subagents** | 6 (Security · Requirements & DoD · Test Coverage · Architecture · Regression · Performance) |
| **Detected runner** | {TEST command, from the map — or "none found"} |
| **Requirements source** | {tracker / spec path / none} |
| **Project refs loaded** | {convention docs + project-local skills used, from the profile} |
| **Findings** | {N} across {M} files |

---
### 🔒 Security ({N})
- [`path/file:L42`] Finding title
### 🚨 Critical ({N})
### ⚡ Performance ({N})
### ⚠️ Warnings ({N})
### 💡 Suggestions ({N})

---
### 🔍 Files With No Inline Comments
- `path/to/file` — no findings from any subagent (verify manually or re-run a targeted review)

_(Omit this section if every logic file received at least one comment.)_

---
### ✅ Highlights
- [One positive highlight per subagent]

---
> See inline comments for details and recommendations.

如果所有子 Agent 都没有发现问题：发布 ✅ No issues found across all review dimensions.，并仍然包含元数据表。

示例

**A — Requirements 根据仓库现状进行判断。**在分支为 feat/PLAT-482-trial 的仓库中，Track A 提取 PLAT-482，通过项目配置的 Jira CLI/MCP 获取该问题，并根据差异评估验收标准 → Sources: Jira: PLAT-482。在另一个没有跟踪系统、但 PR 正文链接了 .specs/checkout/spec.md 的仓库中，Track B 会读取该规范并评估其中的需求 ID。在第三个仓库中，两者都没有，但 PR 引用了 docs/adr/0007-rate-limits.md，Track B 会将 ADR 的 Decision/Consequences 视为判断标准。第四个仓库中这些内容都不存在 → 发布跳过提示并停止。同一个子 Agent，四种结果——完全由项目配置决定。

**B — Architecture 提取自己的矩阵。**仓库 X 在 CONTRIBUTING.md 中记录了约定；Phase 1 将其中“必须/绝不”条目转化为规则 1–12，并据此评估差异。仓库 Y 则包含项目本地的 .cursor/skills/modular-architecture/SKILL.md；子 Agent 会加载该文件，并将其中的检查清单提取为评估矩阵。仓库 Z 完全没有约定文档 → 子 Agent 会说明这一点，并仅执行最基本的通用边界检查。绝不会硬编码任何技术栈规则。

C — 使用 -F 与 -f 发布内容的修正：正确做法与错误做法。

# ✅ posts the file's contents (uppercase -F expands @)
gh api repos/acme/app/pulls/12/comments \
  -F [email protected] -f commit_id={SHA} -f path=src/x -F line=88 -f side=RIGHT
# ❌ posts the literal string "@body.md" (lowercase -f does NOT expand @)
gh api repos/acme/app/pulls/12/comments -f [email protected] -f path=src/x ...

对于 PR 级别的汇总，始终使用 gh pr review 12 --comment --body-file summary.md——绝不要将多行内容内联到 --body 中。

评论

支持 Markdown