用 AI Agent 为 OpenTelemetry-Go 仓库贡献代码：AGENTS.md 协作规范、默认工作流与五种 Personas 全解读

云原生【免费下载链接】buildahA tool that facilitates building OCI images.项目地址https://gitcode.com/gh_mirrors/bu/buildah点击查看免费下载本文以当前仓库中随依赖一起 vendored 的 AGENTS.md 为骨架系统讲解 OpenTelemetry-Gogo.opentelemetry.io/otel为自主与半自主编码 Agent 制定的任务导向型协作指南包括贯穿所有任务的「核心期望」、七步「默认工作流」、以make precommit为核心的验证机制、文档与 CHANGELOG 更新规范以及 Feature / Refactoring / Test / Performance / Review 五种 Agent 角色Personas的分工与纪律。读完本文你将能理解一个高规格开源 Go 项目如何约束 Agent 行为并可直接把其中的 TDD、基准测试、变更日志、聚焦 diff 等工程纪律复用到自己的 Agent 化开发流程中。一、文档定位这不是一份 README而是一份任务导向的 Agent 指令集AGENTS.md的第一段就明确了自身定位This file contains active, task-oriented instructions for autonomous and semi-autonomous coding agents working in this repository.它是一份「活跃的、面向任务的操作指令」而不是面向人类读者的入门文档或架构说明。它要求任何 Agent 在开始任务之前必须先读完三份文件.github/copilot-instructions.md—— 被当作「全局被动指南」适用于包括纯文档、纯评审在内的所有任务CONTRIBUTING.md在 vendored 副本中可直接查看 vendor/go.opentelemetry.io/otel/CONTRIBUTING.md本文件AGENTS.md本身。这条「先读指南再动手」的规则意味着该仓库把 Agent 当成正式的协作者来管理知识前置、纪律前置而不是让 Agent 边做边摸索。当前这份文档位于 buildah 仓库的 vendor 目录vendor/go.opentelemetry.io/otel/AGENTS.md是 buildah 在 go.mod 中以 v1.46.0 间接依赖// indirect引入 OpenTelemetry 时随源码一起冻结的副本——因此它真实反映了上游 OpenTelemetry-Go 的工程约定。二、Core Expectations贯穿所有任务的十三条核心期望文档用一组「核心期望」定义了 Agent 在任何任务中都必须遵守的价值观。逐条拆解如下期望含义与实践保持 OpenTelemetry 规范兼容性、API 稳定性与惯用 Go改动不得偏离 OTel 规范语义公开 API 要稳定代码风格要符合 Go 惯例偏好最小、外科手术式的改动而非大规模重构或投机式清理拒绝「顺手清理」diff 必须聚焦先读你正在修改的包匹配其既有命名、选项类型、错误处理、注释、测试与并发模式新代码要「融入」既有包而不是另起一套风格保持公开 API 向后兼容除非任务明确要求破坏性变更兼容性是不可动摇的默认契约保持遥测的弹性与低耦合不得引入意外干扰宿主应用的行为埋点库是被嵌入别人进程的代码稳定性优先仔细检查边界输入校验、资源限制、取消、关闭、错误传播、并发、内存增长边界是 bug 高发区Agent 必须逐一审视偏好故障安全行为与显式不变量而非隐式假设宁可明确失败也不要默默吞掉异常保持依赖最小化且有据可依每新增一个依赖都要能说明理由保护宿主应用安全遥测不得 panic、不得无限阻塞、不得放大攻击者可控的输入安全底线直接约束了遥测代码的行为上限在热路径上保持保守避免不必要的分配、反射、接口抖动、阻塞、全局状态与高基数遥测性能敏感处宁可少做不可多做注释只写意图、不变量与非显而易见约束不得复述代码注释的价值在于「为什么」而不是「做了什么」这些期望组合起来勾勒出了一个鲜明的画像OpenTelemetry-Go 的 Agent 必须是一个保守、克制、以兼容性和宿主安全为第一优先级的工程师而不是一个喜欢「大展拳脚」的重构者。这与该项目的定位直接相关——从 vendor/go.opentelemetry.io/otel/doc.go 可以看到otel包提供的是「全局访问 OpenTelemetry API」的接口而默认 SDK 与各类 exporter 才负责数据的处理与传输这类被成千上万宿主应用 import 的基础库任何激进的改动都可能造成大范围连锁影响。三、Default Workflow新功能与行为变更的七步默认工作流对于新功能和行为变更文档规定了严格的执行顺序除非任务明确另有要求先读相关包、其测试以及包文档或README.md—— 充分理解现状是第一步添加或更新一个失败的单元测试用于捕获所需行为或回归场景 —— 先写红测试实现能让测试通过的最小改动—— 只做让绿灯亮起的最小实现仅在行为锁定之后才重构且重构必须保持 diff 聚焦 —— 先验证后重构如果改动位于热路径或性能敏感处检查既有 benchmark 并运行覆盖不足则补充 benchmark趁上下文还热及时更新文档产物并按下文「文档与 CHANGELOG 规范」的要求更新相应内容每次认定工作完成前运行make precommit。对纯文档、纯测试或纯评审类任务规则允许跳过不适用的步骤但必须保持同样的「范围、验证、仓库约定」纪律。这套工作流本质上是一条测试先行TDD 最小改动 文档同步 统一验证的流水线。其中两个细节值得注意第 5 步把 benchmark 写进了功能开发的必经环节而不是事后补充项第 7 步把make precommit定位为「完成」的判据——未通过 precommit 的工作一律不算完成。在 vendored 副本的 Makefile 中可以看到该约定的落地.DEFAULT_GOAL : precommit而precommit目标依次执行generate toolchain-check license-check misspell go-mod-tidy golangci-lint-fix verify-readmes verify-mods test-default。也就是说一次make precommit同时覆盖了代码生成、工具链检查、license 检查、拼写检查、依赖整理、lint 自动修复、README 校验、多模块校验与默认测试——这正是「最终验证命令」能一锤定音的原因。四、Verificationmake是唯一权威验证命令基准比较用benchstat文档对验证环节给出了明确的等级体系make是仓库的权威验证命令默认目标就是precommitmake precommit是预期的最终验证步骤覆盖 lint、代码生成、README 检查、模块检查和测试迭代过程中针对性的快速命令如单包测试可以用于快速反馈但如果任务改了代码绝不能止步于此若触及性能敏感代码除了make之外还要运行聚焦的 benchmark并用benchstat比较结果。Makefile 中与此对应的是benchmark系列目标benchmark: $(OTEL_GO_MOD_DIRS:%benchmark/%)按每个 Go module 分片执行基准还有print-affected-benchmarks/print-sharded-benchmarks用于筛选出代码变更涉及的 benchmark 分片——这说明该仓库不仅要求「跑了基准」还要求「跑对基准」只跑受影响的模块并且期望用benchstat给出量化的前后对比而不是凭感觉判断快慢。五、Documentation and Changelog文档与变更日志的硬性规范文档产物不是可选项而是工作流第 6 步的强制输出。规范要点如下GoDoc 与 README非 internal、非测试的包应有 Go doc 注释通常放在doc.go中如 vendor/go.opentelemetry.io/otel/doc.go 所示用包级注释交代了 API 定位、子包划分与阅读指引非 internal、非测试、非文档类包还应有README.md至少要包含标题和pkg.go.dev徽章文档必须与实际行为保持一致不得留下过期的注释、示例或包说明能使用示例Example时优先于长代码片段。CHANGELOG.md面向用户的变更必须更新 CHANGELOG.md落在## [Unreleased]下对应的Added/Changed/Deprecated/Fixed/Removed小节中行尾必须写 PR 号如(#1234)而不是 issue 号如果 PR 号尚不可知先省略等 PR 创建后再补上并在合并前完成更新引用必须使用被更新的 go module如go.opentelemetry.io/otel/sdk/metric而不是路径简写如sdk/metric。从仓库的 CHANGELOG.md 头部可以看到这套格式的实际执行它基于 Keep a Changelog 风格、遵循语义化版本每个版本条目都按Added/Changed/Fixed分组且每条末尾都带 PR 号——例如Support testing of [Go 1.27]. (#8811)、Add Hasher struct and methods ... (#8598)。这些条目正是由遵守 AGENTS.md 的贡献者人类或 Agent按上述规范写入的。六、Repository Habits仓库工作习惯文档用一组「习惯」约束 Agent 的日常行为偏好聚焦的 diff避免顺手清理drive-by cleanup沿用既有 option 模式和导出 API 约定不要发明新的抽象生成文件是要入库的如果改动影响代码生成必须同步更新生成产物探索仓库时优先用快速本地搜索工具如rg改动行为时把不变量显式写进测试。前两条与「核心期望」中最小改动、匹配既有模式的要求一脉相承「生成文件入库」则意味着 Agent 修改生成器或语义约定后必须重新生成并提交产物否则 precommit 中的生成与校验步骤会失败最后一条则把「行为契约」落到了测试断言上让不变量可以被机器验证。七、Personas五种 Agent 角色与各自的执行纪律AGENTS.md最具特色的是定义了五种任务型 Persona。它们共享上述全部规范但各有侧重7.1 Feature Agent —— 新行为、新 API 面、规范驱动的功能开发以失败的单元测试起步对照规范、既有包行为与公开 API 兼容性确认预期行为实现最小可行改动变更对用户可见时同步更新 GoDoc、示例、README.md与CHANGELOG.md若触及热路径检查 benchmark覆盖缺失则补一个。7.2 Refactoring Agent —— 改善结构而不改变行为以「行为不变」为默认契约若现状行为未被测试钉死搬代码前先加或收紧测试除非明确要求避免大范围重写、花哨抽象或全包清理重构触及热路径时重构前后都要跑 benchmark除非任务另有说明API 形态、语义、并发保证与失败模式一律保持不变。7.3 Test Agent —— 补覆盖、复现 bug、加固回归用最小可复现的失败测试复现 bug 或缺失行为优先测试公开行为与外部可见的不变量改生产代码之前先加针对性的回归测试只在使被测行为正确或可测所必需的范围内改动生产代码保持测试确定、可读并与包内既有模式一致。7.4 Performance Agent —— 热路径、分配削减、吞吐与延迟优化先基准、后动手建立基线优先减少分配、拷贝、接口抖动和不必要的同步绝不为微优化牺牲正确性、规范兼容性或 API 稳定性性能敏感覆盖缺失时补充或更新 benchmark实质性改动热路径时用benchstat给出前后对比结果。7.5 Review Agent —— 评审代码、补丁与 Pull Request先讲结论不先写总结按严重程度排序尽量给出精确的文件与行号引用审查面覆盖正确性、规范兼容性、API 兼容性、并发安全、弹性、性能回归、缺失测试、缺失 benchmark、文档缺口与 changelog 缺口明确指出 diff 是否超出必要范围如果没发现问题明确说出来并指出残余风险与验证缺口。五种 Persona 的分工清晰且互补Feature Agent 负责「造」Refactoring Agent 负责「改而不变」Test Agent 负责「守」Performance Agent 负责「快」Review Agent 负责「审」。一个典型场景是Feature Agent 按七步工作流提交功能后由 Review Agent 依据同样的规范清单进行评审——评审标准和开发标准出自同一份文档保证了评审意见的确定性。八、对 buildah 仓库的实际意义一份随依赖冻结的工程规范对 buildah 项目而言这份AGENTS.md并非空谈——它是随go.opentelemetry.io/otelv1.46.0在 go.mod 中以// indirect标记一起 vendored 进来的真实工程规范。buildah 通过go.opentelemetry.io/otel/metric、go.opentelemetry.io/otel/trace与go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp等模块获得遥测能力而 AGENTS.md 中「遥测不得 panic、不得阻塞、不得干扰宿主应用」「热路径保持保守」等约束正是保证 buildah 这类被嵌入 CI/CD 流水线的镜像构建工具在引入遥测后依然稳定、低开销的底层逻辑。如果你打算以 Agent 身份为 OpenTelemetry-Go 或其下游如 buildah的 vendored 依赖提交改动可以直接把本文第二节到第七节的内容当作操作手册即使你只是普通使用者这份文档也值得作为「高质量 Go 开源项目的工程纪律样本」来阅读——测试先行、最小 diff、文档同步、统一验证、角色分工这五条纪律对任何规模的 Go 工程都有普适价值。一句话总结AGENTS.md把「如何做一个靠谱的编码 Agent」从口号变成了可执行的清单——先读规范、红测试起步、最小实现、基准佐证、文档随改、make precommit收尾再按五种 Persona 各司其职。赞分享云原生【免费下载链接】buildahA tool that facilitates building OCI images.项目地址https://gitcode.com/gh_mirrors/bu/buildah点击查看免费下载相关推荐opentelemetry-go 的 AI Agent 协作规范从核心期望、默认工作流到五种 Agent 角色opentelemetry go 的 AI Agent 协作规范从核心期望、默认工作流到五种 Agent 角色 本篇技术指南以当前仓库 vendor/go.o云原生存储OpenTelemetry-Go 仓库 AI Agent 协作开发指南AGENTS.md 任务规范全解读OpenTelemetry Go 仓库 AI Agent 协作开发指南AGENTS.md 任务规范全解读 导读 opentelemetry go 是 Ope机器学习深度学习数据可视化可观测性Podman 仓库中的 OpenTelemetry-Go AGENTS.md 解读面向 AI 编码 Agent 的仓库协作与工程规范指南Podman 仓库中的 OpenTelemetry Go AGENTS.md 解读面向 AI 编码 Agent 的仓库协作与工程规范指南 本文是一篇围绕 ve容器运行时云原生CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考