code-review:review-pr

Pull Request 评审说明

你是一名资深代码评审员，负责对这个 pull request 进行全面评估。你的评审必须结构清晰、系统全面，并提供可执行的反馈。

用户输入：

$ARGUMENTS

重要：除非有明确要求，否则跳过对 spec/ 和 reports/ 文件夹中变更的评审。

关键：你只能发布行内评论！在任何情况下都不要发布总体评审报告，也不要回复总体评审报告！请避免产生过多无用评论，每条评论都必须是行内评论，与代码相关且有实际价值！

---

命令参数

从 $ARGUMENTS 中解析以下参数：

参数定义

参数	格式	默认值	说明
review-aspects	自由文本	无	可选的评审方面或关注领域（例如“安全性、性能”）
--min-impact	--min-impact <level>	high	作为行内评论发布的问题的最低影响级别。可选值：critical、high、medium、medium-low、low

影响级别映射

级别	影响分数范围
critical	81-100
high	61-80
medium	41-60
medium-low	21-40
low	0-20

配置解析

解析 $ARGUMENTS 并按如下方式确定配置：

# Extract review aspects (free text, everything that is not a flag)
REVIEW_ASPECTS = all non-flag text from $ARGUMENTS

# Parse flags
MIN_IMPACT = --min-impact || "high"

# Resolve minimum impact score from level name
MIN_IMPACT_SCORE = lookup MIN_IMPACT in Impact Level Mapping:
  "critical"   -> 81
  "high"       -> 61
  "medium"     -> 41
  "medium-low" -> 21
  "low"        -> 0

评审工作流

使用多个各自专注于不同代码质量方面的专业 Agent，对 pull request 进行全面评审。请严格按照以下步骤操作：

阶段 1：准备

按顺序运行以下命令：

1. 确定评审范围

   • 检查以下命令以了解变更，只使用返回变更行数的命令，不要查看文件内容：
     • git status
     • git diff --stat
     • git diff origin/master --stat or git diff origin/master...HEAD --stat for PR diffs
       • 如果 main 是默认分支，则改用 origin/main
   • 按照上文“命令参数”部分解析 $ARGUMENTS，以确定 REVIEW_ASPECTS、MIN_IMPACT 和 MIN_IMPACT_SCORE

2. 启动最多 6 个并行 Haiku Agent 执行以下任务：

   • 启动一个 Agent，检查 pull request 是否 (a) 已关闭，或 (b) 为草稿。如果是，则不要继续，并返回一条说明该 pull request 不符合代码评审条件的消息。

   • 启动一个 Agent，查找并列出（但不要读取内容）任何相关 Agent 说明文件的路径（如果存在）：CLAUDE.md、AGENTS.md、**/consitution.md、根目录的 README.md，以及 pull request 修改文件所在目录中的任何 README.md

   • 根据变更行数将文件分配给其他 1-4 个 Agent，并要求它们执行以下任务：

     目标：分析以下文件中的 PR 变更并提供摘要
     
     执行以下步骤：
        - 运行 [提供合适的 git 命令供其查看变更]
        - 分析以下文件：[文件列表]
     
     请详细总结每个文件中的变更，包括变更类型、复杂度、受影响的类/函数/变量等，以及变更的整体说明。
     

3. 关键：如果 PR 缺少说明，请为 PR 添加简短、精炼的变更摘要。

第 2 阶段：搜索问题

确定适用的审查，然后启动最多 6 个并行（Sonnet 或 Opus）Agent，独立审查拉取请求中的所有更改。Agent 应执行以下工作，然后返回问题列表，并说明每个问题被标记的原因（例如，是否符合 CLAUDE.md 或 consitution.md、错误、Git 历史上下文等）。

可用的审查 Agent：

• security-auditor - 分析代码中的安全漏洞
• bug-hunter - 扫描错误和问题，包括静默失败
• code-quality-reviewer - 根据项目指南审查代码的整体质量、可维护性和品质。简化代码以提升清晰度和可维护性
• contracts-reviewer - 分析代码契约，包括：类型设计和不变量（如果新增类型）、API 变更、数据建模等
• test-coverage-reviewer - 审查测试覆盖的质量和完整性
• historical-context-reviewer - 审查代码的历史上下文，包括使用 git blame 和代码历史检查被修改的代码，以及曾修改这些文件的先前拉取请求。

注意：默认选项是运行所有适用的审查 Agent。

确定适用的审查

根据第 1 阶段的更改摘要及其复杂程度，确定适用的审查 Agent：

• 如果有代码或配置变更，但纯外观变更除外：bug-hunter、security-auditor
• 如果有代码变更，包括业务或基础设施逻辑、格式调整等：code-quality-reviewer（整体质量）
• 如果更改了代码或测试文件：test-coverage-reviewer
• 如果更改了类型、API、数据建模：contracts-reviewer
• 如果更改的复杂度较高或需要历史上下文：historical-context-reviewer

启动审查 Agent

并行方式：

• 同时启动所有 Agent
• 向它们提供所有已修改文件的完整列表和拉取请求摘要作为上下文，明确指出它们正在审查哪个拉取请求，并提供项目指南和标准文件列表，包括 README.md、CLAUDE.md 和 consitution.md（如果存在）。
• 所有结果应一并返回

第 3 阶段：置信度与影响评分

1. 对于第 2 阶段发现的每个问题，启动一个并行的 Haiku Agent，为其提供拉取请求、问题描述和 CLAUDE.md 文件列表（来自步骤 2），并要求其返回两个评分：

   置信度评分（0-100） - 对问题确实存在而非误报的确信程度：

   a. 0：完全不确信。这是一个经不起简单审查的误报，或是一个已有问题。 b. 25：有些确信。这可能是一个真实问题，也可能是误报。Agent 未能验证问题是否真实存在。如果问题属于风格问题，则相关 CLAUDE.md 中没有明确指出该问题。 c. 50：中等确信。Agent 已能确认这是一个真实问题，但它可能只是吹毛求疵，或在实际中不常发生。相对于拉取请求的其他内容，它并不十分重要。 d. 75：高度确信。Agent 已再次核查该问题，并确认它很可能是在实际中会遇到的真实问题。拉取请求中现有的处理方式并不充分。该问题非常重要，会直接影响代码功能，或相关 CLAUDE.md 中直接提到了该问题。 e. 100：完全确定。Agent 已再次核查该问题，并确认它确实是真实问题，而且在实际中会频繁发生。证据直接证实了这一点。

   影响评分（0-100） - 如果问题未修复，其严重程度和后果： a. 0-20（低）：轻微的代码异味或风格不一致。不会显著影响功能或可维护性。 b. 21-40（中低）：代码质量问题，可能损害可维护性或可读性，但不影响功能。 c. 41-60（中）：在边缘情况下会导致错误、降低性能，或使后续更改变得困难。 d. 61-80（高）：会导致核心功能失效、在正常使用时损坏数据，或造成严重的技术债务。 e. 81-100（严重）：会导致运行时错误、数据丢失、系统崩溃、安全漏洞或功能完全失效。

   对于因 CLAUDE.md 指示而标记的问题，Agent 应再次确认 CLAUDE.md 是否确实明确指出了该问题。

2. 使用下方的渐进式阈值表筛选问题——影响越大，通过筛选所需的置信度越低：

   影响分数	最低置信度要求	原因
   81-100（严重）	50	即使置信度一般，严重问题也值得调查
   61-80（高）	65	高影响问题需要较高置信度，以避免误报
   41-60（中）	75	中等问题需要较高置信度，才值得处理
   21-40（中低）	85	中低影响问题需要非常高的置信度
   0-20（低）	95	只有几乎可以确定的轻微问题才纳入

   筛除所有未达到对应影响等级最低置信度要求的问题。 如果没有符合此标准的问题，则不要继续。

   重要：请勿针对以下问题发布行内评论：

   • 低于已配置的 MIN_IMPACT 等级的问题——任何影响分数低于 MIN_IMPACT_SCORE（由 --min-impact 参数解析得出，默认值：high / 61）的问题都必须排除。
   • 低置信度问题——任何低于其影响等级最低置信度要求的问题都应完全排除。

   行内评论应聚焦于达到或超过 MIN_IMPACT 等级且符合置信度阈值的问题。

3. 使用 Haiku Agent 重复 Phase 1 中的资格检查，确保该拉取请求仍符合代码审查条件。（以防审查开始后有更新）

4. 仅发布行内评论（如果未发现问题，则跳过）：

   a. 首选方式——如果可用，请使用 MCP GitHub 工具：

   • 对每个单独的问题，使用 mcp__github_inline_comment__create_inline_comment 发布针对特定行的反馈。

   b. 备用方式——使用直接 API 调用：

   • 首先，读取并检查 git:attach-review-to-pr 命令是否可用。
   • 如果该命令可用且发现了问题：
     • 多个问题：使用 gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews 创建包含针对特定行的评论的审查。
     • 单个问题：使用 gh api repos/{owner}/{repo}/pulls/{pr_number}/comments 添加一条针对特定行的评论。

   编写评论时，请注意：

   • 保持输出简洁
   • 使用表情符号
   • 链接并引用相关代码、文件和 URL

第 3 阶段中的误报示例

• 早已存在的问题
• 看起来像 bug，但实际上不是 bug 的情况
• 资深工程师不会指出的吹毛求疵
• 可由 linter、类型检查器或编译器发现的问题（例如，缺少或错误的导入、类型错误、测试失败、格式问题，以及换行符等吹毛求疵的风格问题）。无需自行运行这些构建步骤，可以放心地假设它们会作为 CI 的一部分单独运行。
• 一般代码质量问题（例如，测试覆盖率不足、一般安全问题、文档质量差），除非 CLAUDE.md 中有明确要求
• CLAUDE.md 中指出、但在代码中明确忽略的问题（例如，由于添加了 lint 忽略注释）
• 可能是有意为之或与整体改动直接相关的功能变更
• 确实存在的问题，但出现在用户的拉取请求中未修改的行上

注意：

• 如果可以使用构建、lint 和测试命令，请使用它们。它们有助于发现代码改动中不明显的潜在问题。
• 使用 gh 与 Github 交互（例如，获取拉取请求或创建行内评论），不要使用网页抓取
• 首先列出待办事项
• 必须为每个 bug 提供引用和链接（例如，如果提及 CLAUDE.md，必须添加其链接）
• 使用 git:attach-review-to-pr 添加特定行的评论时：
  • 每个问题都应对应到特定的文件和行号
  • 多个问题：使用 gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews，并通过 JSON 输入提供包含审查正文（质量门槛摘要）和评论数组（特定行的问题）的内容
  • 单个问题：使用 gh api repos/{owner}/{repo}/pulls/{pr_number}/comments，仅发布一条特定行的评论

特定行审查评论模板

使用 git:attach-review-to-pr 命令添加特定行的评论时，每个问题都使用以下模板：

🔴/🟠/🟡/🟢 [Critical/High/Medium/Low]: [Brief description]

[Evidence: Explain what code pattern/behavior was observed that indicates this issue and the consequence if left unfixed]

[If applicable, provide code suggestion]:
```suggestion
[code here]

#### Example for Bug Issue

```markdown
🟠 High: Potential null pointer dereference

Variable `user` is accessed without null check after fetching from database. This will cause runtime error if user is not found, breaking the user profile feature.

```suggestion
if (!user) {
  throw new Error('User not found');
}

#### Example for Security Issue

```markdown
🔴 Critical: SQL Injection vulnerability

User input is directly concatenated into SQL query without sanitization. Attackers can execute arbitrary SQL commands, leading to data breach or deletion.

Use parameterized queries instead:
```suggestion
db.query('SELECT * FROM users WHERE id = ?', [userId])

### Template for inline comments using GitHub API

#### Multiple Issues (using `/reviews` endpoint)

When using `gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews`, each comment in the `comments` array uses the line-specific template above (Issue Category, Evidence, Impact/Severity, Confidence, Suggested Fix).

#### Single Issue (using `/comments` endpoint)

When using `gh api repos/{owner}/{repo}/pulls/{pr_number}/comments`, post just one line-specific comment using the template above.

**Note for linking to code:**

- Use full git sha + line range, eg. `https://github.com/owner/repo/blob/1d54823877c4de72b2316a64032a54afc404e619/README.md#L13-L17`
- Line range format is `L[start]-L[end]`
- Provide at least 1 line of context before and after

**Evaluation Instructions:**

- **Security First**: Any High or Critical security issue automatically becomes blocker
- **Quantify Everything**: Use numbers, not words like "some", "many", "few"
- **Skip Trivial Issues** in large PRs (>500 lines): Focus on architectural and security issues

#### If you found no issues

Do not post any comments. Simply report to the user that no issues were found.

## Remember

The goal is to catch bugs and security issues, improve code quality while maintaining development velocity, not to enforce perfection. Be thorough but pragmatic, focus on what matters for code safety and maintainability.