pr-reviewer

PR 审查 Skill

使用行业标准准则和自动化工具，对 GitHub Pull Request 进行全面的、专业的代码审查。

目录

• 目的
• 使用场景
• 审查流程工作流
• 参考文档
• 脚本参考
• 最佳实践
• 快速参考命令
• 高效审查的技巧
• 资源

目的

此 skill 通过以下方式执行代码审查：

1. 自动化数据收集 - 获取所有 PR 相关信息（元数据、diff、评论、提交、issue）
2. 组织审查工作区 - 创建结构化的目录并存放所有产物
3. 应用系统性准则 - 依据全面的质量检查清单进行审查
4. 促进行内反馈 - 可选择直接将评论添加到 PR 代码中
5. 确保完整性 - 检查功能、安全性、测试、可维护性

使用场景

在以下情况下激活此 skill：

• 提供了 GitHub PR URL 并附带审查请求
• 收到 "review this PR" 或 "code review" 请求
• 在合并前检查 PR 质量
• 对提议的变更提供系统性反馈
• 在任何上下文中提到 GitHub PR 审查

审查流程工作流

重要：此 skill 使用两阶段审批流程。在通过 /send 或 /send-decline 明确批准之前，不会向 GitHub 发布任何内容。

概述

1. 获取 PR 数据 - 收集所有信息
2. 生成审查文件 - 创建详细、面向人类和行内评论文件
3. 审查和编辑 - 检查文件，按需修改（使用 /show）
4. 批准并发布 - 使用 /send（批准）或 /send-decline（请求更改）

步骤 1：获取 PR 数据

使用 fetch_pr_data.py 自动收集所有 PR 信息：

python scripts/fetch_pr_data.py <pr_url> [--output-dir <dir>] [--no-clone]

执行的操作：

• 解析 PR URL 以提取 owner、repo 和 PR 编号
• 创建目录结构：<output-dir>/PRs/<repo-name>/<PR-NUMBER>/
• 获取 PR 元数据（标题、作者、状态、分支、标签）
• 下载 PR diff 和提交历史
• 检索所有 PR 评论和审查
• 提取工单引用（JIRA、GitHub issue）
• 可选克隆源分支并生成 git diff

示例：

python scripts/fetch_pr_data.py https://github.com/facebook/react/pull/28476

# Custom output directory
python scripts/fetch_pr_data.py https://github.com/owner/repo/pull/123 --output-dir /tmp/reviews

# Skip cloning (faster, no git diff)
python scripts/fetch_pr_data.py https://github.com/owner/repo/pull/123 --no-clone

输出结构：

/tmp/PRs/<repo-name>/<PR-NUMBER>/
├── metadata.json           # PR metadata (title, author, branches)
├── diff.patch             # PR diff from gh CLI
├── git_diff.patch         # Git diff (if cloned)
├── comments.json          # Review comments on code
├── commits.json           # Commit history
├── related_issues.json    # Linked GitHub issues
├── ticket_numbers.json    # Extracted ticket references
├── SUMMARY.txt            # Human-readable summary
└── source/                # Cloned repository (if not --no-clone)

步骤 2：分析 PR 数据

获取后，依据审查准则分析收集到的数据：

1. 读取 SUMMARY.txt - 高层次概览
2. 查看 metadata.json - PR 上下文、标签、负责人
3. 检查 diff.patch - 代码变更
4. 查看 comments.json - 现有反馈
5. 查看 commits.json - 提交质量和提交信息
6. 查看 related_issues.json - 关联的工单/issue
7. 应用审查准则 - 依据全面的检查清单进行评估

使用 Read 工具检查文件：

Read /tmp/PRs/<repo-name>/<PR-NUMBER>/SUMMARY.txt
Read /tmp/PRs/<repo-name>/<PR-NUMBER>/metadata.json
Read /tmp/PRs/<repo-name>/<PR-NUMBER>/diff.patch

步骤 3：生成审查文件

关键：分析之后，使用 generate_review_files.py 创建结构化的审查文档：

python scripts/generate_review_files.py <pr_review_dir> --findings <findings_json> [--metadata <metadata_json>]

在 pr_review_dir/pr/ 中创建三个文件：

1. pr/review.md - 带 emoji 和行号的详细内部审查
2. pr/human.md - 用于发布的整洁审查（无 emoji、破折号、行号）
3. pr/inline.md - 附带代码片段的行内评论提议

同时在 .claude/commands/ 中创建斜杠命令：

• /send - 发布 human.md 并批准 PR
• /send-decline - 发布 human.md 并请求更改
• /show - 在 VS Code 中打开审查目录

Findings JSON 结构：

{
  "summary": "Overall assessment of the PR...",
  "metadata": {
    "repository": "owner/repo",
    "number": 123,
    "title": "PR title",
    "author": "username",
    "head_branch": "feature",
    "base_branch": "main"
  },
  "blockers": [
    {
      "category": "Security",
      "issue": "SQL injection vulnerability",
      "file": "src/db/queries.py",
      "line": 45,
      "details": "Using string concatenation for SQL query",
      "fix": "Use parameterized queries",
      "code_snippet": "result = db.execute('SELECT * FROM users WHERE id = ' + user_id)"
    }
  ],
  "important": [...],
  "nits": [...],
  "suggestions": ["Consider adding...", "Future enhancement..."],
  "questions": ["Is this intended to...", "Should we..."],
  "praise": ["Excellent test coverage", "Clear documentation"],
  "inline_comments": [
    {
      "file": "src/app.py",
      "line": 42,
      "comment": "Consider edge case handling for empty input",
      "code_snippet": "def process(data):\n    return data.strip()",
      "start_line": 41,
      "end_line": 43,
      "owner": "owner",
      "repo": "repo",
      "pr_number": 123
    }
  ]
}

步骤 4：审查和编辑文件

使用 /show 在 VS Code 中打开审查目录。

可执行的操作：

• 读取 pr/review.md - 详细分析
• 编辑 pr/human.md - 在发布前修改
• 查看 pr/inline.md - 检查提议的评论
• 按需调整任何内容

在步骤 5 中明确批准之前，不会发布任何内容。

步骤 5：批准并发布

准备好后发布评审：

方案 A：批准 PR

/send

• 将 pr/human.md 作为评论发布
• 批准 PR
• 确认操作

方案 B：请求更改

/send-decline

• 将 pr/human.md 作为评论发布
• 在 PR 上请求更改
• 确认操作

发布行内评论（可选，在 /send 或 /send-decline 之后）： 查看 pr/inline.md，并运行提供的命令来添加具体的代码评论。

步骤 6：应用评审标准

参考 references/review_criteria.md 获取完整检查清单。按以下类别进行评审：

类别	关键问题
功能	代码是否解决了问题？是否有 bug？是否处理了边界情况？
可读性	代码是否清晰？命名是否有意义？是否遵循 DRY？
风格	是否遵循 linter 规则？是否与代码库保持一致？
性能	算法是否高效？是否可扩展？
安全	是否解决了漏洞？是否保护了密钥？
测试	是否存在测试？是否覆盖了正常路径和边界情况？
PR 质量	范围是否聚焦？提交是否清晰？描述是否清楚？

发现问题的优先级标记：

• Blocker：合并前必须修复
• Important：应当解决
• Nit：锦上添花，可选
• Suggestion：可考虑在未来改进
• Question：需要澄清
• Praise：做得好

获取详细标准： 阅读 references/review_criteria.md

参考文档

此技能包含全面的参考指南：

参考	用途
references/review_criteria.md	涵盖功能、安全、测试等的完整检查清单
references/gh_cli_guide.md	GitHub CLI 命令快速参考
references/scenarios.md	常见评审场景的详细工作流
references/troubleshooting.md	常见问题与解决方案

脚本参考

scripts/fetch_pr_data.py

自动获取并整理 PR 数据。

python scripts/fetch_pr_data.py <pr_url> [options]

Options:
  --output-dir DIR    Base output directory (default: /tmp)
  --no-clone         Skip cloning repository

scripts/generate_review_files.py

根据分析发现生成结构化的评审文件。

python scripts/generate_review_files.py <pr_review_dir> --findings <findings_json> [--metadata <metadata_json>]

创建：

• pr/review.md - 详细的内部评审
• pr/human.md - 用于发布的简洁评审
• pr/inline.md - 附命令的行内评论建议
• .claude/commands/send.md - 用于批准并发布的斜杠命令
• .claude/commands/send-decline.md - 用于请求更改的斜杠命令
• .claude/commands/show.md - 用于在 VS Code 中打开的斜杠命令
• REVIEW_READY.txt - 后续步骤摘要

scripts/add_inline_comment.py

向 PR 中的特定行添加行内代码评审评论。

python scripts/add_inline_comment.py <owner> <repo> <pr_number> <commit_id> <file_path> <line> "<comment>" [options]

Options:
  --side RIGHT|LEFT       Side of diff (default: RIGHT)
  --start-line N         Starting line for multi-line comment
  --start-side RIGHT|LEFT Starting side for multi-line comment

最佳实践

沟通

• 将反馈表述为建议，而非批评
• 解释问题为何重要，而不只是指出哪里错了
• 肯定优秀的做法
• 优先处理 blocker，将风格问题放在最后

评审效率

• 使用脚本自动化数据获取和评论发布
• 将 review_criteria.md 作为检查清单参考
• 聚焦：关键问题 > 重要问题 > 锦上添花
• 及时评审（尽可能在 24 小时内）

行内评论

• 引用确切的行和文件
• 提供更好的替代方案
• 先在测试 PR 上测试行内评论
• 谨慎使用，避免信息过载

PR 规模处理

• 大型 PR（>400 行）：建议拆分
• 按逻辑分块评审
• 对于大型变更，重点关注架构

获取详细场景： 阅读 references/scenarios.md

快速参考命令

# Fetch PR data
python scripts/fetch_pr_data.py https://github.com/owner/repo/pull/123

# Add inline comment
python scripts/add_inline_comment.py owner repo 123 latest "src/app.py" 42 "Comment"

# View PR in browser
gh pr view 123 --repo owner/repo --web

# Check PR status
gh pr checks 123 --repo owner/repo

# View existing comments
gh api /repos/owner/repo/pulls/123/comments --jq '.[] | {path, line, body}'

高效评审的技巧

1. 从上下文开始：阅读 PR 描述、关联 issue、提交信息
2. 理解意图：识别正在解决的问题
3. 先检查测试：验证测试是否展示了修复/功能
4. 寻找模式：重复出现的问题暗示架构问题
5. 考虑替代方案：评估更简单的方法
6. 思考可维护性：评估未来修改的难易程度
7. 记住对方是人：保持友善、尊重和建设性的语气

获取故障排查帮助： 阅读 references/troubleshooting.md

资源

• 审查标准：references/review_criteria.md
• gh CLI 指南：references/gh_cli_guide.md
• 场景：references/scenarios.md
• 疑难解答：references/troubleshooting.md
• GitHub PR 审查文档：https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests
• Google 工程实践：https://google.github.io/eng-practices/review/
• OWASP Top 10：https://owasp.org/www-project-top-ten/