review-pr

PR 审查技能

遵循工程最佳实践，生成并发布 AI 驱动的 GitHub PR 审查评论。

用法

/review-pr <pr-number>         # Generate review (step 1)
/review-pr <pr-number> --post  # Post review to GitHub (step 2)

示例：

• /review-pr 180 - 生成审查结果并保存到 YAML 文件
• /review-pr 180 --post - 将审查后的 YAML 发布到 GitHub

此技能的功能

步骤 1：生成（/review-pr <number>）

1. 使用 gh CLI 从 GitHub 获取 PR 详情
2. 执行架构审查（新增！）：质疑设计决策，检查范围蔓延情况，验证用例
3. 分析变更中的安全、测试、设计模式和代码质量问题
4. 区分不同上下文：CLI 代码与 GitHub Actions 代码（标准不同）
5. 提供可执行的反馈：基于文件名和模式给出具体的重构建议
6. 在可编辑的 YAML 文件中生成结构化审查评论
7. 预览所有生成的评论

步骤 2：发布（/review-pr <number> --post）

1. 读取你审查或编辑过的 YAML 文件
2. 发布到 GitHub：将所有已启用的评论提交到 PR
3. 自动回退：如果 GitHub API 发布失败（例如，Enterprise Managed User 限制），则自动生成包含格式化评论的 Markdown 文件，供手动复制/粘贴

工程审查原则

此技能会强制执行以下原则：

架构审查（新增！）

• 验证设计决策：审查“如何做”之前，先质疑“为什么”
• 检测范围蔓延：标记超出 Agent365 部署/管理范围的扩展
• 验证用例：新功能必须提供具体场景
• 检测重叠：识别与现有工具（Azure CLI、Portal）的重复
• 执行 YAGNI 原则：质疑没有文档说明需求的功能

架构与模式

• .NET 架构师模式：按照 .NET 最佳实践进行审查
• 与 Azure CLI 保持一致：确保符合 az cli 模式和约定
• 跨平台兼容性：验证 Windows、Linux 和 macOS 的兼容性（适用于 CLI 代码）

设计模式

• KISS（保持简单，傻瓜）：优先采用简单、直接的解决方案
• DRY（不要重复自己）：识别代码重复
• SOLID 原则：尤其是单一职责原则
• YAGNI（你不会需要它）：避免过度设计
• 每个文件一个类：确保代码组织整洁

代码质量

• 避免大文件：标记新增内容超过 500 行的文件
• 复用函数：鼓励在不同命令间复用函数
• 避免特殊字符：避免在日志/输出中使用表情符号（兼容 Windows）
• 代码应自解释：优先编写清晰代码，避免过多注释
• 简洁的注释（pr-code-reviewer #30）：标记超过 1–2 行、复述代码或叙述设计历史的新增注释——注释用一句话说明原因；较长的说明应放在提交/PR 中。
• 可直接用于发布说明的 CHANGELOG（pr-code-reviewer #31）：标记提及内部实现、解释机制或包含多个句子的 CHANGELOG.md 条目——每条都应是简洁、面向用户的一句话（会原样发布到 nuget.org 发布说明中）。
• 尽量减少变更：只做解决问题所必需的变更

测试标准

• 框架：.NET 使用 xUnit、FluentAssertions、NSubstitute；Python 使用 pytest/unittest
• 质量重于数量：重点关注关键路径和边缘情况
• CLI 可靠性：没有测试的 CLI 代码属于阻塞项
• GitHub Actions 测试：强烈建议（严重级别高），但不是阻塞项
• 模拟外部依赖：采用恰当的模拟模式

安全

• 不得硬编码机密：使用环境变量或 Azure Key Vault
• 凭据管理：CLI 代码遵循 az cli 模式；Actions 使用 GitHub Secrets

上下文感知

该技能区分：

• CLI 代码（严格要求）：跨平台、可靠，必须有测试
• GitHub Actions 代码（特定于 GitHub）：仅支持 Linux 也可以，强烈建议添加测试

审查评论输出

生成的评论保存在：

C:\Users\<username>\AppData\Local\Temp\pr-reviews\pr-<number>-review.yaml

你可以编辑此文件以：

• 设置 enabled: false 来停用评论
• 修改评论文本
• 调整严重级别（blocking、high、medium、low、info）
• 添加或移除评论

实现

该技能直接使用 Claude Code 进行语义代码分析（受 Agent365-dotnet 启发）。无需单独的 API 密钥！

生成模式（默认）：

1. Claude Code 读取 .claude/agents/pr-code-reviewer.md，了解审查流程指南。读取此文件以及 .github/copilot-instructions.md 和 CLAUDE.md 的工作树（PR）版本，而不是基础分支中的副本。当待审查的 PR 新增或更改审查规则（如 PR #461 中的规则 #30/#31）时，必须在同一次运行中将新规则应用于该 PR；读取基础分支中的副本会导致跳过这些规则。
2. Claude Code 读取 .github/copilot-instructions.md，了解编码标准
3. Claude Code 获取 PR 详情：gh pr view <number> --json ...
4. Claude Code 分析实际代码变更：gh pr diff <number>
5. Claude Code 使用自身能力进行语义分析
6. Claude Code 通过行号和代码引用指出具体问题
7. Claude Code 将 YAML 文件写入 C:\Users\<username>\AppData\Local\Temp\pr-reviews\pr-<number>-review.yaml

发布模式（使用 --post 标志）：

1. Python 脚本读取 YAML 文件
2. Python 脚本使用 gh pr comment 向 GitHub 发布评论
3. 如果发布失败（API 权限问题），则自动生成 Markdown 文件，供手动复制/粘贴

主要优势：

• ✅ 无需 ANTHROPIC_API_KEY——使用 Claude Code 现有的身份验证
• ✅ 更强的语义分析能力——Claude Code 拥有完整的上下文和对话历史
• ✅ Python 脚本更简单——仅处理发布逻辑（约 240 行，而非约 1500 行）
• ✅ 更易于维护和调试

工作流

1. 生成审查：/review-pr 180

   • 从 GitHub 获取 PR 详情
   • 分析代码并生成审查评论
   • 保存到 YAML 文件（输出中会显示路径）

2. 审查并编辑：打开 YAML 文件

   • 检查所有生成的评论
   • 根据需要编辑评论文本
   • 设置 enabled: false 来停用评论
   • 如有需要，可添加自己的评论

3. 发布到 GitHub：/review-pr 180 --post

   • 读取 YAML 文件
   • 向 PR 发布所有已启用的评论
   • 如果 API 发布失败，则自动生成 Markdown 文件，供手动复制/粘贴

要求

• 已安装并完成身份验证的 GitHub CLI (gh)
• Python 3.x（仅用于 --post 模式）
• PyYAML 库：pip install pyyaml（仅用于 --post 模式）
• 仓库必须是 GitHub 仓库
• 拥有发布审查的 GitHub API 权限（Enterprise Managed Users 可能受到限制）

另请参阅

• README.md - 详细文档
• review-pr.py - 实现脚本