Ansible PR Review 自动化技能：/review 命令的八步审查流程、必备组件核验与合规检查

本篇技术文章解析 Ansible 官方仓库内为 AI 编程代理定义的 /review 技能（.claude/skills/review/SKILL.md）：它把 Ansible 社区标准 PR 审查流程固化为八步可执行步骤，涵盖 changelog 片段校验、测试覆盖要求与许可证合规检查。读完本文，你将掌握该技能的调用方式、每一步对应的 gh CLI 命令、审查必备组件的核验标准，以及仓库中 changelog 配置、测试规范与许可证政策的具体依据，可用于指导人工评审或复现一套自动化 PR 审查流程。

技能定位：把 CLAUDE.md 审查流程封装为可调用命令

该技能是一个 Claude Code 风格的 agent skill，其元数据（frontmatter）声明如下：

name: review
description: Review an Ansible PR following the project's standardized process from CLAUDE.md
argument-hint: <pr_number>
allowed-tools: [TodoWrite, Bash(gh pr view:*), Bash(gh pr diff:*), Bash(gh pr checkout:*), Bash(gh pr checks:*), Read, Grep, Glob, Search]
user-invocable: true

几个值得注意的设计点：

• argument-hint: <pr_number> 声明了唯一的必填参数——GitHub PR 编号；
• allowed-tools 采用最小权限原则，只放行 gh pr view/diff/checkout/checks 系列命令和文件读取/搜索工具（Read、Grep、Glob、Search），外加用于进度跟踪的 TodoWrite；
• 实现来源：技能明确说明它实现的是 AGENTS.md 中 PR Review Guidelines 一节定义的流程（根目录 CLAUDE.md 通过 @AGENTS.md 引用把该指引纳入代理工作上下文）。

调用方式非常直接：

/review <pr_number>

参数只有一个：pr_number（必填），即待审查的 GitHub PR 编号。

八步审查流程逐步解析

技能文档将审查过程拆为八个编号步骤，全部由 TodoWrite 任务清单跟踪，保证每一步显式完成、可追溯：

步骤 1：创建 TodoWrite 清单

用任务列表系统化跟踪整个审查过程。AGENTS.md 同样强调："Use TodoWrite to create a task list and track progress systematically"，并在每项完成后立即标记，让审查进度对用户可见。

步骤 2：获取 PR 详情

gh pr view <number>

目的不仅是看标题，而是理解 PR 的范围（scope）、动机（motivation）与期望结果——这三者决定了后续审查的重心。

步骤 3：获取 PR 完整 diff

gh pr diff <number>

在切换分支之前先通读全部改动，建立对变更的整体认知。

步骤 4：优先核验必备组件（核心步骤）

这是整个流程中最关键的一步，技能要求 FIRST（最先）检查三类必备组件：

（1）changelog 片段必须存在。 每个 PR 都应在 changelogs/fragments/ 下新增 YAML 片段文件。仓库内真实示例如下（changelogs/fragments/86749-winrm-stdin-error-message.yml）：

minor_changes:
  - winrm connection plugin - improved error message to include target host when stdin transfer fails (https://github.com/ansible/ansible/issues/86749)

（2）changelog 片段必须使用合法的 section。 合法 section 由 changelogs/config.yaml 的 sections 键定义，当前包括：

section 键	展示名称
major_changes	Major Changes
minor_changes	Minor Changes
breaking_changes	Breaking Changes / Porting Guide
deprecated_features	Deprecated Features
removed_features	Removed Features (previously deprecated)
security_fixes	Security Fixes
bugfixes	Bugfixes
known_issues	Known Issues

此外，context/documentation-standards.md 补充了命名与格式约束：片段文件命名为 {issue_number}-{short-description}.yml，无 issue 时可用 {component}-{description}.yml；条目格式为 - {component} - {description} ({optional URL to GH issue})；每个 PR 新建独立片段文件，不得复用已有片段以避免合并冲突。发布时 CHANGELOG-vX.Y.rst 会从 fragments 目录汇总生成（见 changelogs/README.md）。

（3）测试必须覆盖被修改的代码路径。 具体标准来自 context/writing-tests.md：

• 单元测试必须是 pytest 风格，且偏重功能性（functional）而非与 mock 深度耦合；
• 几乎所有插件（plugin）变更都要求集成测试（测试公共 API）；
• 测试必须实际执行到被修改的代码，而不是"随机增加覆盖率"。

步骤 5：检出 PR 分支

gh pr checkout <number>

切换到 PR 分支后，在改动已应用的工作区中整体性（holistically） 审读代码，而不是只看 diff 片段——这一步配合 Read/Grep 工具用于深入查看具体变更文件和相关代码模式。

步骤 6：审查已有反馈

gh pr view <number> --comments

拉取所有评论与历次评审意见，重点关注 ansibot 机器人报告的 CI 失败详情（含错误信息、文件路径与行号）。

步骤 7：确认所有问题已解决

逐项核对：机器人报告的失败、评审人提出的修改请求、讨论中的分歧点，是否都已被 PR 作者处理。

步骤 8：显式点出未解决的反馈

任何仍未被处理的讨论或请求，必须在评审意见中明确点名，不能默认"大家都看到了"。

三大关键审查要素

技能文档在流程之外单独提炼了三条硬性审查要素：

1. 许可证合规（Licensing）

任何新引入的依赖都必须满足 context/licensing.md 中的要求：

• ansible-core：所有代码必须与 GPLv3 兼容；
• lib/ansible/module_utils/：默认采用更宽松的 BSD-2-Clause；
• 外部依赖仅限使用与上述许可证兼容的库；
• 存疑时主动询问许可证兼容性，而不是默认假设。

AGENTS.md 进一步将此列为"不可协商"的红线：违反许可证的代码会带给项目严重法律风险，审查者绝不应建议或批准此类变更。

2. 测试范围（Test scope）

测试必须执行真实的改动代码路径，而非堆砌覆盖率。这一点与步骤 4 的测试核验互为呼应：审查时既要看"有没有测试"，也要看"测试是否打在了改动的代码上"。

3. Changelog 校验

片段结构必须遵循 changelogs/config.yaml 定义的 section（见上文表格），条目内容支持 Sphinx 标记（代码引用使用双反引号）。

配套的 CI 排查手段

审查中遇到 CI 失败时，AGENTS.md 提供了完整的排查链路，/review 技能所允许的 gh pr checks 正是其中一环：

# 查看 CI 检查结果（含 Azure Pipelines URL）
gh pr checks <number>

# 下载 CI 日志（仓库配套的 /azp-logs 技能）
/azp-logs <pr_number>

底层实现是 hacking/azp/download.py，按 build ID 目录存放控制台日志，并支持过滤：

# 只下载匹配特定任务名的日志
./hacking/azp/download.py <build_id> --console-logs --match-job-name "Sanity.*"

# 同时下载 artifacts 和元数据
./hacking/azp/download.py <build_id> --all

日志下载后的分析建议：用 grep -r "FAILED\|ERROR\|Traceback <build_id>/" 搜索常见失败模式，聚焦 gh pr checks 中标记为失败的任务，并将错误信息与 ansibot 评论对照。完整的 CI 日志技能文档见 .claude/skills/azp-logs/SKILL.md；本地复现测试的命令（ansible-test sanity/units/integration 及容器选择规则）见 context/running-tests.md。另外，AGENTS.md 的一条通用原则值得记住：不要标注 ansible-test sanity 已经能自动发现的问题，把审查精力集中在自动化检查无法验证的事项上。

约束与评审规模控制

• 每个步骤都在 TodoWrite 中跟踪，完成即标记，保证审查过程的可见性与系统性；
• 单轮评审的反馈项不超过 20 条——这一上限约束避免一次性倾倒海量意见，促使评审者优先聚焦最重要的问题。

小结

/review 技能的价值在于把一份"写在文档里的流程"变成了带参数、带权限边界、带任务跟踪的可执行单元：gh pr view/diff/checkout/checks 构成信息获取骨架，"changelog 片段 + 合法 section + 覆盖改动路径的测试"是放行之前的硬性门槛，GPLv3/BSD-2-Clause 合规是贯穿始终的红线。对照 context/documentation-standards.md、context/writing-tests.md 与 changelogs/config.yaml，开发者既可以按同样的八步清单做人工自查，也可以以此为模板为自己项目构建类似的标准化 PR 审查流程。