用 Claude Code Skill 加载 Ansible 开发上下文：/context 技能与 AGENTS.md 指引体系全解析

在 Ansible（ansible-core）仓库中进行贡献开发时，测试命令、许可证约束、PR 评审流程等约定分散在多个文档中。本文以 .claude/skills/context/SKILL.md 为主体，讲解这个 /context 技能如何一键把 AGENTS.md 中的完整开发规范加载进 AI 助手上下文，并结合仓库内 context/ 目录的配套文档，说明该技能背后所承载的测试、CI 排障与 PR 评审知识体系，帮助你在主仓库之外的环境中也能遵循一致的 Ansible 开发规范。

技能定位：一个纯信息型的上下文加载器

.claude/skills/context/SKILL.md 是仓库内置的 Claude Code 技能（Skill）定义文件，其 frontmatter 声明如下：

---
name: context
description: Load Ansible project development guidelines, testing conventions, PR review processes, and code structure reference into context
user-invocable: true
---

其中 user-invocable: true 表示该技能可以由用户通过斜杠命令直接触发，使用方式为：

/context

该技能的核心行为只有一条：被调用时从仓库根目录读取 AGENTS.md 文件（技能内部用相对路径 @../../../AGENTS.md 指向该文件），并把其全部内容加载进上下文。随后向用户确认上下文已就绪，可用于回答问题或指导开发工作。

两点设计细节值得注意：

• 纯信息型，无副作用。技能文档明确声明 "This skill is informational only - it loads comprehensive Ansible development knowledge into context but performs no actions"，它只加载知识，不执行任何变更操作；
• 缺失兜底。如果找不到 AGENTS.md，技能会提示用户，并建议当前目录可能不是完整的 ansible-core 仓库。

技能加载的核心：AGENTS.md 的结构与关键约定

AGENTS.md 是仓库根目录下的 AI 助手指引文件，供 Claude Code 等 agentic 工具使用（人类开发者则参考官方的 Ansible Developer Guide）。/context 技能加载的正是这份文件，它的内容结构如下：

启动前的强制检查流程

AGENTS.md 开头要求：开始任何 PR 评审或开发任务之前——

1. 先完整阅读该文件，不要凭记忆或假设工作；
2. 阅读所有 context 目录下的文件，掌握项目的编码约定与政策；
3. 使用 TodoWrite 建立任务清单，系统性跟踪进度；
4. 按相关流程章节中的编号步骤执行；
5. 在 context/running-tests.md、context/ci.md 等文档中查询正确命令与模式。

许可证红线

AGENTS.md 将许可证要求标注为 CRITICAL，并指向 context/licensing.md：

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

文件明确要求：任何违反许可证要求的代码都不得被建议、推荐或批准，因为许可证违规会给项目带来严重的法律风险。

评审原则与署名要求

• 不要重复机器能做的检查：评审代码时，不要标记 ansible-test sanity 已经能自动捕获的问题，把评审精力集中在自动检查无法验证的地方；
• Agent 署名：AI 助手参与贡献时应披露自身参与，推荐使用 Assisted-by: commit trailer 标明辅助的 AI 工具。

CI 失败诊断工作流：ansibot、gh pr 与 /azp-logs

AGENTS.md 中最具实战价值的部分是"帮助开发者处理 CI 失败"的完整工作流，/context 技能加载后，AI 助手即可按此流程协助排障：

第一步，查看 ansibot 评论：

gh pr view <number> --comments

关注来自 ansibot 的评论，其中通常包含具体的测试失败详情、出错文件路径与行号、以及指向 sanity 测试文档的说明链接。

第二步，获取 CI 检查状态：

gh pr checks <number>

该命令返回整体 CI 状态（通过/失败）与耗时、Azure DevOps 构建结果链接、以及各子任务（Sanity Test 1/2、Docker 测试、Units 等）的单独结果。

第三步，按序分析：先看 ansibot 评论获取即时错误详情；再用 gh pr checks 拿到 Azure Pipelines URL 查看详细日志；聚焦标记为 fail 的 job；sanity 测试失败的信息通常直接指明需要修复的位置；其他测试失败则用 ansible-test 在本地复现调试。

深入分析：下载完整日志。当评论和 Web UI 信息不足时，可配合仓库内置的另一个技能 /azp-logs（定义见 .claude/skills/azp-logs/SKILL.md）：

/azp-logs <pr_number>              # 自动定位最新构建
/azp-logs <build_id>              # 直接使用构建 ID
/azp-logs https://dev.azure.com/.../_build/results?buildId=12345   # 完整 URL

该技能底层调用 hacking/azp/download.py，把控制台日志下载到以构建 ID 命名的目录中，并支持精细过滤：

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

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

下载后按 AGENTS.md 给出的模式检索失败信号：

grep -r "FAILED\|ERROR\|Traceback" <build_id>/

PR 评审标准流程与检查清单

AGENTS.md 定义了每一步都必须执行的 PR 评审检查清单（Checklist）：

□ 为评审步骤创建 TodoWrite 清单
□ Step 1: gh pr view <number> 获取 PR 详情
□ Step 2: gh pr diff <number> 获取完整 diff
□ Step 3: 检查必备组件（changelog、tests）
□ Step 4: gh pr checkout <number> 切换到 PR 分支
□ Step 5: gh pr view <number> --comments 查看既有反馈
□ Step 6: 验证所有问题均已解决
□ Step 7: 指出仍未处理的评审意见
□ 每完成一步即在 TodoWrite 中标记完成

其中"检查必备组件"有两项硬性标准，分别由配套文档支撑：

• Changelog fragment 必须存在，且分区结构要符合 changelogs/config.yaml 的定义（要求详见 context/documentation-standards.md）。仓库中 changelogs/fragments/ 目录存放着各 PR 对应的 fragment 文件，是这一约定的直接体现；
• 测试必须覆盖改动路径，单元测试应为 pytest 风格且偏功能化，不能与 mock 强耦合；几乎每个插件改动都需要集成测试（期望值详见 context/writing-tests.md）。

仓库内 .claude/skills/review/SKILL.md 把上述流程封装成了可直接调用的 /review <pr_number> 技能，并补充了一条评审纪律：单轮评审的反馈项不应超过 20 条。

技能加载后的知识范围与适用场景

按照 SKILL.md 的 "What This Skill Does" 部分，/context 调用后，后续所有响应都可访问以下六类知识：测试命令、PR 评审流程与检查清单、许可证要求、代码风格约定、仓库结构、CI 工作流。

适用场景包括四类：在主仓库之外开发 Ansible 相关代码、在插件市场等无法访问 AGENTS.md 的环境中运行的技能、快速查阅 Ansible 测试与 PR 约定、以及确保团队内 Ansible 开发方式的一致性。

/context 技能之所以有价值，关键在于它背后是 context/ 目录这套"对人与 Agent 同等适用"的文档体系（见 context/README.md），各文档分工如下：

文档	覆盖内容
context/contributing.md	向 ansible-core 贡献变更的规范
context/licensing.md	GPLv3 / BSD-2-Clause 许可证要求
context/dev-environment.md	开发环境搭建
context/code-structure.md	目录布局、关键组件、import 限制与插件策略
context/coding-style.md	Python 版本、依赖、格式与语法约定
context/error-handling.md	错误与异常处理模式
context/data-tagging.md	数据标签（data tags）的使用
context/public-api.md	公共 API 面与"默认内部"约定
context/documentation-standards.md	模块/插件文档与 changelog 要求
context/running-tests.md	ansible-test 各类测试的运行方式
context/writing-tests.md	PR 的测试期望
context/deprecation.md	向后兼容与弃用流程
context/ci.md	CI 常见失败模式（sanity、集成、单元）

以测试为例，context/running-tests.md 给出了技能加载后可直接使用的命令基线：

# Sanity 测试（无需 --docker）
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                          # 容器内全量覆盖

# 单元测试
ansible-test units -v --docker test/units/modules/test_command.py

# 集成测试（使用发行版容器，而非 default）
ansible-test integration -v --docker ubuntu ping

并强调容器选择规则：sanity/unit 用 --docker（默认 default 容器），集成测试必须用 --docker ubuntu、--docker fedora 等发行版容器；base/default 容器仅适用于 sanity/unit。这些命令约定与 AGENTS.md 中 "不要重复 sanity 已覆盖的检查" 的评审原则互为表里。

小结：三层结构如何让 AI 协作开发保持规范

从源码结构看，仓库把 AI 协作开发的知识组织成了清晰的三层：

1. 入口层：AGENTS.md 作为总纲，规定启动流程、许可证红线、快速命令参考与评审纪律；
2. 技能层：.claude/skills/ 下的四个技能（context、review、azp-logs、creating-backports）把高频动作封装为一键调用，其中 /context 负责加载上下文，是其余技能的"知识底座"；
3. 细则层：context/ 目录下的 13 篇文档提供各主题的完整细则，且声明"对人与 Agent 同等适用"，保证人类开发者与 AI 助手依据同一套规范工作。

这套设计的核心收益是：无论是在 ansible-core 主仓库内、还是插件市场等受限环境中，调用一次 /context 即可让 AI 助手获得与主仓库完全一致的测试命令、许可证检查清单与 PR 评审流程，从而保证贡献行为的一致性与可审计性。