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

Ansible 仓库的 AI Agent 协作指南AGENTS.md 驱动的 PR 审查、CI 故障诊断与许可证红线【免费下载链接】ansibleAnsible is a radically simple IT automation platform that makes your applications and systems easier to deploy and maintain. Automate everything from code deployment to network configuration to cloud management, in a language that approaches plain English, using SSH, with no agents to install on remote systems. https://docs.ansible.com.项目地址: https://gitcode.com/GitHub_Trending/ans/ansible本文基于 ansible-core 仓库根目录的 AGENTS.md 撰写。该文件是专为 Claude Code 等 AI 编程代理设计的“入口指令”规定了代理在参与该仓库开发前的必读流程、许可证红线、PR 审查清单和 CI 失败诊断工作流。读完后你可以掌握如何按照项目约定启动一次代理辅助的 PR 审查如何用ghCLI 与 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 审查或开发任务开始前必须完成五件事先读本文件—— 不凭记忆、不凭假设工作读完全部 context 文件—— 项目编码规范与策略都在这里使用 TodoWrite 建立任务清单系统化跟踪进度遵循相应流程小节中的编号步骤参考 Quick Reference 获取正确的命令与模式。所谓 context 文件就是仓库根目录下 context 目录中的 13 个 Markdown 文档例如context/licensing.md许可证要求context/running-tests.mdansible-test命令与容器选择context/writing-tests.mdPR 的测试期望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-ClauseTesting见 context/running-tests.md 获取ansible-test命令与容器选择。许可证红线不可协商的第一原则AGENTS.md 用 “CRITICAL” 级别强调了许可证要求NEVER suggest, recommend, or approve code that violates the projects 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, dont flag issues thatansible-test sanityalready catches. Focus review effort on things automated checks cant 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 Referencegh 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 失败分析工作流按以下顺序推进先看 ansibot 评论获取直接的错误详情用gh pr checks number拿到 Azure Pipelines URL 以查看详细日志聚焦标记为fail的 job检查其具体错误输出sanity 测试失败的错误信息通常直接指出要修什么对测试类失败用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/单测用--dockerdefault 容器即可但集成测试必须用发行版容器如--docker ubuntubase/default容器只适用于 sanity/单测。第四步下载 Azure Pipelines 日志深入分析当 ansibot 评论和 Web UI 不足以定位问题时使用/azp-logsSkill# 用 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?buildId12345该 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 清单 □ 步骤 1gh pr view number 获取 PR 详情 □ 步骤 2gh pr diff number 获取 PR diff □ 步骤 3检查必备组件changelog、测试 □ 步骤 4gh pr checkout number 检出 PR 分支 □ 步骤 5gh 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 规定的审查步骤必须按顺序执行获取 PR 详情gh pr view number理解 PR 范围与描述获取 PR diffgh pr diff number查看所有变更先检查必备组件changelog 与测试见上文链接检出 PR 分支gh pr checkout number带着改动整体审视代码查看已有反馈gh pr view number --comments读取全部评论与历史审查意见;确认所有问题已解决机器人失败、审查者要求、讨论点是否都已处理明确指出仍未处理的审查反馈对遗留的讨论或请求显式点名。审查任务管理与工具复杂 PR 用 TodoWrite 跟踪审查步骤正在处理的步骤标记为 in_progress每完成一步立即勾选让使用者实时可见审查进度。文件同时列出了配套工具集gh pr view number—— PR 详情与描述gh pr view number --comments—— 全部评论与审查反馈gh pr diff number—— 完整改动 diffgh pr checkout number—— 切换到 PR 分支做整体检视Read工具 —— 细读具体变更文件Grep工具 —— 搜索相关代码模式或测试覆盖底层是 ripgrep/rg。小结AGENTS.md 的工程价值把 AGENTS.md 放回仓库整体看它本质上是一份机器可读的贡献契约通过“先读 context 文件”的启动协议把散落在 context 目录的 13 份规范许可证、测试、文档、CI串成一条确定性流程通过ghCLI hacking/azp/download.py 的组合把 CI 失败诊断从“肉眼翻 Web UI”变成可 grep、可脚本化的操作通过许可证红线与Assisted-by:署名为 AI 参与贡献设定了法律与透明度的双重护栏通过“不重复 sanity 已检查的问题”这一原则把代理的审查火力集中到自动化手段覆盖不到的地方。对于维护者这类文件降低了“每次都要向 AI 解释项目约定”的沟通成本对于贡献者审查清单与 CI 诊断工作流可以直接照搬为人工检查清单——这也是该文档虽标注“仅供 AI 助手使用”却同样值得人类开发者通读的原因。【免费下载链接】ansibleAnsible is a radically simple IT automation platform that makes your applications and systems easier to deploy and maintain. Automate everything from code deployment to network configuration to cloud management, in a language that approaches plain English, using SSH, with no agents to install on remote systems. https://docs.ansible.com.项目地址: https://gitcode.com/GitHub_Trending/ans/ansible创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考