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

• 云原生

本文以当前仓库中随依赖一起 vendored 的 AGENTS.md 为骨架，系统讲解 OpenTelemetry-Go（go.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 在开始任务之前，必须先读完三份文件：

1. .github/copilot-instructions.md—— 被当作「全局被动指南」，适用于包括纯文档、纯评审在内的所有任务；
2. CONTRIBUTING.md（在 vendored 副本中可直接查看 vendor/go.opentelemetry.io/otel/CONTRIBUTING.md）；
3. 本文件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-Go 的 Agent 必须是一个保守、克制、以兼容性和宿主安全为第一优先级的工程师，而不是一个喜欢「大展拳脚」的重构者。这与该项目的定位直接相关——从 vendor/go.opentelemetry.io/otel/doc.go 可以看到，otel包提供的是「全局访问 OpenTelemetry API」的接口，而默认 SDK 与各类 exporter 才负责数据的处理与传输；这类被成千上万宿主应用 import 的基础库，任何激进的改动都可能造成大范围连锁影响。

三、Default Workflow：新功能与行为变更的七步默认工作流

对于新功能和行为变更，文档规定了严格的执行顺序（除非任务明确另有要求）：

1. 先读相关包、其测试，以及包文档或README.md—— 充分理解现状是第一步；
2. 添加或更新一个失败的单元测试，用于捕获所需行为或回归场景 —— 先写红测试；
3. 实现能让测试通过的最小改动—— 只做让绿灯亮起的最小实现；
4. 仅在行为锁定之后才重构，且重构必须保持 diff 聚焦 —— 先验证后重构；
5. 如果改动位于热路径或性能敏感处，检查既有 benchmark 并运行；覆盖不足则补充 benchmark；
6. 趁上下文还热，及时更新文档产物，并按下文「文档与 CHANGELOG 规范」的要求更新相应内容；
7. 每次认定工作完成前，运行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 校验、多模块校验与默认测试——这正是「最终验证命令」能一锤定音的原因。

四、Verification：make是唯一权威验证命令，基准比较用benchstat

文档对验证环节给出了明确的等级体系：

• make是仓库的权威验证命令，默认目标就是precommit；
• make 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/otel（v1.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 各司其职。

• 云原生