Ansible 仓库的 AI Agent 协作指南：AGENTS.md 驱动的 PR 审查、CI 故障诊断与许可证红线

本文基于 ansible-core 仓库根目录的 AGENTS.md 撰写。该文件是专为 Claude Code 等 AI 编程代理设计的“入口指令”，规定了代理在参与该仓库开发前的必读流程、许可证红线、PR 审查清单和 CI 失败诊断工作流。读完后你可以掌握：如何按照项目约定启动一次代理辅助的 PR 审查，如何用 gh CLI 与 hacking/azp/download.py 定位 Azure Pipelines 上的 CI 失败，以及哪些内容绝不可以绕过（GPLv3/BSD-2-Clause 许可证约束）。

文件定位：先给 AI 看什么，再给人看什么

AGENTS.md 开头即声明了它的受众边界：

This file provides guidance to Claude Code (claude.ai/code) and other compatible agentic tools when working with code in this repository.

也就是说，它是给“AI 助手”看的操作手册，而不是面向人类开发者的入门文档——文件里明确指出，人类开发者应去查阅 Ansible 官方开发者指南（external 文档站），而本文件只服务于代理工具。这种“人机双轨”的文档分工是当前大型开源仓库的一个典型实践：把机器可执行的流程约束（读哪些文件、跑哪些命令、按什么顺序审查）单独抽出来，让 Agent 每次任务都从确定性的起点出发，而不是依赖“记忆”或假设。

文件给出的“启动协议”（Always Start Here）要求任何 PR 审查或开发任务开始前必须完成五件事：

1. 先读本文件 —— 不凭记忆、不凭假设工作；
2. 读完全部 context 文件 —— 项目编码规范与策略都在这里；
3. 使用 TodoWrite 建立任务清单，系统化跟踪进度；
4. 遵循相应流程小节中的编号步骤；
5. 参考 Quick Reference 获取正确的命令与模式。

所谓 context 文件，就是仓库根目录下 context 目录中的 13 个 Markdown 文档，例如：

• context/licensing.md：许可证要求；
• context/running-tests.md：ansible-test 命令与容器选择；
• context/writing-tests.md：PR 的测试期望；
• context/ci.md：常见 CI 失败模式；
• context/documentation-standards.md：文档与 changelog 规范；
• 以及 context/code-structure.md、context/coding-style.md、context/deprecation.md 等。

这正是 AGENTS.md 中“Quick Reference”最后两条 Critical Reminders 的落点：

• Licensing：见 context/licensing.md —— 仅允许 GPLv3/BSD-2-Clause；
• Testing：见 context/running-tests.md 获取 ansible-test 命令与容器选择。

许可证红线：不可协商的第一原则

AGENTS.md 用 “CRITICAL” 级别强调了许可证要求：

NEVER suggest, recommend, or approve code that violates the project's licensing requirements. Always verify any new dependencies or suggested libraries are license-compatible. This is non-negotiable -- licensing violations can create serious legal issues for the project.

这条红线的具体边界在 context/licensing.md 中给出，共四条：

• ansible-core：全部代码必须 GPLv3 兼容；
• lib/ansible/module_utils/：默认为 BSD-2-Clause（更宽松）；
• 外部依赖：只能使用与上述许可证兼容的库；
• 拿不准时：先询问兼容性，而不是想当然。

这个区分在仓库结构上是有据可查的：lib/ansible/module_utils/ 存放的是需要被任意许可证的模块/集合复用的底层工具代码，因此采用宽松的 BSD-2-Clause；而 lib/ansible/ 主体（controller、executor、plugins 等）受 GPLv3 约束。仓库根目录的 licenses/ 目录中也分别放置了 Apache-License.txt、BSD-3-Clause.txt、MIT-license.txt、PSF-license.txt 等第三方许可文本，供比对参考。对 Agent 而言，这意味着：推荐一个新第三方库之前，必须先核对其许可证是否 GPLv3/BSD-2-Clause 兼容，否则应直接拒绝该建议。

一般原则与署名规范

除许可证外，AGENTS.md 还给出两条影响审查行为的通用原则：

1. 不要重复自动化检查能发现的问题。

When reviewing code, don't flag issues that ansible-test sanity already catches. Focus review effort on things automated checks can't verify.

仓库的 sanity 测试体系（ansible-test sanity）覆盖面极广——从 test/sanity/ 目录可以看到除 code-smell 规则集外还有大量 ignore 配置与自定义检查。因此人工（或代理）审查的价值在于自动化检查“看不见”的东西：设计合理性、跨模块一致性、测试与变更的对应关系等。

2. Agent 必须披露参与贡献（Attribution）。

文件推荐在提交信息中使用 Assisted-by: trailer 来标识协助的 AI 工具，例如：

commit ...
Assisted-by: Claude Code

这是一种“贡献可追溯”机制，让维护者能区分纯人工提交与 AI 辅助提交，也符合大型社区对 AI 参与透明度日益提高的要求。

Quick Reference：gh CLI 快速命令表

AGENTS.md 的 Quick Reference 小节集中列出了 PR 审查与 CI 诊断的核心命令：

# PR Review and CI
gh pr view <number>                                       # 获取 PR 详情
gh pr view <number> --comments                             # 查看 ansibot CI 失败报告
gh pr checks <number>                                      # 获取 Azure Pipelines 构建 URL
gh pr checkout <number>                                   # 切换到 PR 分支
gh pr diff <number>                                       # 查看全部改动
/azp-logs <number>                                        # 下载该 PR 的 CI 日志

其中 /azp-logs 不是标准 CLI 命令，而是本仓库为 Claude Code 定义的 Skill，其完整文档在 .claude/skills/azp-logs/SKILL.md（该文件确实存在于仓库中）。.claude/skills/ 目录下还有 creating-backports、context、review 等 Skill，与 AGENTS.md 所述的“流程步骤”相互呼应。

帮助开发者排查 CI 失败：完整的诊断工作流

这是 AGENTS.md 篇幅最大的实操部分，描述了 PR 提交后遇到 CI 失败时的标准处置流程，共分四步。

第一步：检查 ansibot 的评论

# 获取全部 PR 评论以找到 ansibot 的 CI 失败报告
gh pr view <number> --comments

要找 ansibot 发出的评论，其中通常包含：

• 带具体错误信息的测试失败详情；
• 失败位置的文件路径与行号；
• 指向 sanity 测试文档的 [explain] 链接。

第二步：获取 CI 检查状态与构建 URL

# 查看所有 CI 检查结果及 Azure Pipelines URL
gh pr checks <number>

输出包括：整体 CI 状态（通过/失败）及耗时、指向 Azure DevOps 构建结果页的直接链接，以及各个 job 的单独结果（Sanity Test 1/2、Docker 测试、Units 等）。

第三步：CI 失败分析工作流

按以下顺序推进：

1. 先看 ansibot 评论，获取直接的错误详情；
2. 用 gh pr checks <number> 拿到 Azure Pipelines URL 以查看详细日志；
3. 聚焦标记为 fail 的 job，检查其具体错误输出；
4. sanity 测试失败的错误信息通常直接指出要修什么；
5. 对测试类失败，用 ansible-test 在本地复现并调试。

context/ci.md 对三类失败模式做了归纳，可与本工作流对照：

• Sanity 失败：通常有明确修法（尾随空白、import 错误等）；
• 集成测试失败：可能需要平台专属容器或测试调整；
• 单元测试失败：往往指向真实代码缺陷，需要调试。

而“本地复现”具体跑什么，由 context/running-tests.md 给出权威命令，例如：

# 全部 sanity 测试
ansible-test sanity -v
# 指定测试类型
ansible-test sanity -v --test pep8 --test pylint
# 仅针对改动文件（路径相对仓库根）
ansible-test sanity -v lib/ansible/modules/command.py
# 容器内全量覆盖
ansible-test sanity -v --docker

需要注意的两个坑：--docker 不带参数时默认使用 default 容器，不要在 --docker 后紧跟非容器参数，否则会被解释为镜像名；sanity/单测用 --docker（default 容器）即可，但集成测试必须用发行版容器（如 --docker ubuntu），base/default 容器只适用于 sanity/单测。

第四步：下载 Azure Pipelines 日志深入分析

当 ansibot 评论和 Web UI 不足以定位问题时，使用 /azp-logs Skill：

# 用 PR 号下载（自动定位最新构建）
/azp-logs <pr_number>

# 或直接用 gh pr checks 输出中的 build ID
/azp-logs <build_id>

# 或直接用完整 Azure Pipelines URL
/azp-logs https://dev.azure.com/ansible/ansible/_build/results?buildId=12345

该 Skill 底层调用的是 hacking/azp/download.py，会把控制台日志下载到以构建 ID 命名的目录中。阅读该脚本源码可以看到，它实际支持的参数比 AGENTS.md 展示得更多：

• RUN：接受构建 ID 或完整构建 URL（脚本中用正则同时匹配两种输入）；
• -v/--verbose：显示下载内容；-t/--test：只打印将下载什么而不实际下载；
• -p/--pipeline-id：指定 pipeline（默认 20）；
• --console-logs / --artifacts / --run-metadata / --all：分别控制下载控制台日志、构建产物、运行元数据或全部；
• --match-job-name / --match-artifact-name：用正则过滤 job 名或产物名。

AGENTS.md 中展示的“高级用法”对应其中两个参数：

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

# 连产物和元数据一起下载
./hacking/azp/download.py <build_id> --all

下载完日志后的分析方法（AGENTS.md 原文）：

• 用 grep -r "FAILED\|ERROR\|Traceback" <build_id>/ 搜常见失败模式；
• 聚焦 gh pr checks 中识别出的失败 job 的日志；
• 把错误信息与 ansibot 评论交叉比对以获得完整上下文；
• sanity 失败一般有带 文件:行号 的明确错误信息；
• 集成/单元测试失败则可能需要通读完整测试输出与 traceback。

PR 审查指南：清单、七步流程与工具

PR 审查清单（每个 PR 都要过一遍）

AGENTS.md 要求对每一次 PR 审查使用如下清单（原文为 TodoWrite 任务项）：

□ 已为审查步骤创建 TodoWrite 清单
□ 步骤 1：gh pr view <number> 获取 PR 详情
□ 步骤 2：gh pr diff <number> 获取 PR diff
□ 步骤 3：检查必备组件（changelog、测试）
□ 步骤 4：gh pr checkout <number> 检出 PR 分支
□ 步骤 5：gh pr view <number> --comments 查看已有反馈
□ 步骤 6：确认所有问题已解决
□ 步骤 7：指出仍未处理的反馈
□ 每完成一步立即在 TodoWrite 中勾选

其中“步骤 3：检查必备组件”对应两项硬性要求，分别由 context/documentation-standards.md 与 context/writing-tests.md 定义：

Changelog 要求（见 context/documentation-standards.md 的 Changelog requirements 小节）：

• 每个变更都需要在 changelogs/fragments/ 下新增 YAML 片段；
• 每个 PR 新建一个片段文件，绝不复用已有片段（避免合并冲突）——仓库当前该目录中已有上百个形如 82792-sort-entries-in-FILES_json.yml、ansible-test-ubuntu-2604.yml 的片段实例，均遵循此约定；
• 片段结构须使用 changelogs/config.yaml 中 sections 键定义的合法小节；
• 命名规范：{issue_number}-{short-description}.yml，无 issue 时用 {component}-{description}.yml；
• 内容格式：- {component} - {description} ({可选的 issue 链接})，支持 Sphinx 标记（代码引用用双反引号）。

测试期望（见 context/writing-tests.md）：

• 变更必须有覆盖到改动代码的测试；
• 单元测试应为 pytest 风格，偏功能验证而非紧贴 mock；
• 几乎所有插件变更都需要集成测试（测试公共 API）；
• 测试必须真正执行被改动的代码，而不是随机补覆盖率。

七步审查流程

AGENTS.md 规定的审查步骤必须按顺序执行：

1. 获取 PR 详情：gh pr view <number>，理解 PR 范围与描述；
2. 获取 PR diff：gh pr diff <number>，查看所有变更；
3. 先检查必备组件：changelog 与测试（见上文链接）；
4. 检出 PR 分支：gh pr checkout <number>，带着改动整体审视代码；
5. 查看已有反馈：gh pr view <number> --comments，读取全部评论与历史审查意见;
6. 确认所有问题已解决：机器人失败、审查者要求、讨论点是否都已处理；
7. 明确指出仍未处理的审查反馈：对遗留的讨论或请求显式点名。

审查任务管理与工具

• 复杂 PR 用 TodoWrite 跟踪审查步骤；正在处理的步骤标记为 in_progress；
• 每完成一步立即勾选，让使用者实时可见审查进度。

文件同时列出了配套工具集：

• gh pr view <number> —— PR 详情与描述；
• gh pr view <number> --comments —— 全部评论与审查反馈；
• gh pr diff <number> —— 完整改动 diff；
• gh pr checkout <number> —— 切换到 PR 分支做整体检视；
• Read 工具 —— 细读具体变更文件；
• Grep 工具 —— 搜索相关代码模式或测试覆盖（底层是 ripgrep/rg）。

小结：AGENTS.md 的工程价值

把 AGENTS.md 放回仓库整体看，它本质上是一份机器可读的贡献契约：

• 通过“先读 context 文件”的启动协议，把散落在 context 目录的 13 份规范（许可证、测试、文档、CI）串成一条确定性流程；
• 通过 gh CLI + hacking/azp/download.py 的组合，把 CI 失败诊断从“肉眼翻 Web UI”变成可 grep、可脚本化的操作；
• 通过许可证红线与 Assisted-by: 署名，为 AI 参与贡献设定了法律与透明度的双重护栏；
• 通过“不重复 sanity 已检查的问题”这一原则，把代理的审查火力集中到自动化手段覆盖不到的地方。

对于维护者，这类文件降低了“每次都要向 AI 解释项目约定”的沟通成本；对于贡献者，审查清单与 CI 诊断工作流可以直接照搬为人工检查清单——这也是该文档虽标注“仅供 AI 助手使用”，却同样值得人类开发者通读的原因。