opentelemetry-go 的 AI Agent 协作规范：从核心期望、默认工作流到五种 Agent 角色

云原生存储【免费下载链接】distributionThe toolkit to pack, ship, store, and deliver container content项目地址https://gitcode.com/gh_mirrors/dis/distribution点击查看免费下载本篇技术指南以当前仓库vendor/go.opentelemetry.io/otel/AGENTS.mdopentelemetry-go 官方为自主/半自主编码 Agent 编写的任务型协作指令为核心系统拆解其核心期望、默认工作流、验证体系、文档与 Changelog 规范、仓库习惯以及 Feature、Refactoring、Test、Performance、Review 五种 Agent 角色的分工边界。它适用于在大型 Go 开源仓库中从事 AI 辅助开发的工程师与维护者——读完你既能理解规范为什么这样定也能获得一份可直接落地到任意 Go 项目的 Agent 协作检查清单同时本文会结合当前 distribution 仓库中 vendored 的 otel 源码与真实使用方式如tracing/tracing.go、go.mod中的依赖版本进行佐证让规范从纸面落到代码。一、这份文档是什么为编码 Agent 写的任务型操作手册与面向人类贡献者的CONTRIBUTING.md不同AGENTS.md 是一份面向自主与半自主编码 Agent的活动型task-oriented指令文件同目录下还有配套的 CONTRIBUTING.md、CHANGELOG.md、RELEASING.md 与 VERSIONING.md。文档开篇就给出了明确的开工前必读要求在开始任何任务之前先阅读.github/copilot-instructions.md、CONTRIBUTING.md和本文件。将.github/copilot-instructions.md视为每个任务包括纯文档和纯评审工作的全局被动指导。这意味着 Agent 仓库中的指令是分层级的全局指导copilot-instructions 贡献规范CONTRIBUTING 任务操作指令AGENTS.md。它把如何在本仓库安全地改动代码从人类的隐性知识显式化为 Agent 可以逐条执行的约束——这正是现代 AI 辅助开源开发中仓库级 Agent 规范的标准形态。值得说明的是当前 distribution 仓库本身也践行着类似的纪律文化仓库根目录 Makefile 集中定义了test、test-race、test-full、integration、lint、validate等验证目标project/hooks/pre-commit 通过gofmt -s、golint、go vet在提交前拦截不合格代码与上游 otel 用make precommit收敛验证流程的思路一脉相承。二、核心期望Agent 改动代码前必须内化的八条底线AGENTS.md 的 Core expectations 是全文的价值观地基也是评审 Agent 判断改得对不对的判据。逐条拆解如下保持规范合规与惯用 Go始终维护 OpenTelemetry 规范符合性spec compliance、API 稳定性与地道的 Go 风格。倾向最小化、外科手术式的改动优先最小而精准的变更拒绝大规模重构或无目的的清理。这对应后续 Repository habits 中的 Prefer focused diffs. Avoid drive-by cleanup。先读懂再动手阅读你正在编辑的包匹配其既有的命名、选项类型、错误处理、注释、测试与并发模式。改动不是创造新风格而是延续既有风格。API 向后兼容除非任务明确要求破坏性变更否则保持公共 API 向后兼容。遥测要健壮且低耦合不得引入可能意外干扰宿主应用的行为。结合当前仓库可以直观理解这一点distribution 在 tracing/tracing.go 中通过autoexport.NewSpanExporter自动探测导出端、用stdouttrace输出到日志、以sdktrace.TraceIDRatioBased(1)设默认采样率整个初始化被封装为一次InitOpenTelemetry调用避免对 registry 主流程产生侵入性副作用。仔细审视边界输入校验、资源限制、取消cancellation、关闭shutdown、错误传播、并发与内存增长。这些正是遥测库最容易出问题的地方。偏向 fail-safe用显式的不变量invariants取代隐式假设。依赖最小化保持依赖最少且有充分理由。这一点在当前仓库同样有迹可循——otel 相关依赖被精确限定为go.opentelemetry.io/otel v1.45.0、otel/sdk v1.45.0、otel/trace v1.45.0及 contrib 的autoexport、otelhttp等少数几个模块见 go.mod。此外还有两条工程红线热路径上保持保守——避免不必要的分配、反射、接口变动、阻塞、全局状态与高基数遥测注释只写意图、不变量与非显然约束绝不写复述代码的废话。三、默认工作流新功能与行为变更的七步标准流程对于新功能与行为变更文档要求严格按顺序执行除非任务明确另有说明通读上下文阅读相关包、其测试以及包文档或README.md。先写失败测试添加或更新一个失败的单元测试捕获所需行为或回归场景——即 TDD 中的 red 阶段。最小实现实现让测试通过的最小改动。行为锁定后再重构只有在行为被测试锁定后才允许重构且重构必须保持 diff 聚焦。热路径性能核查若改动位于热路径或性能敏感区检查既有 benchmark缺失则补一个。趁热更新文档在上下文还新鲜时更新文档产物并遵循下文专门的文档与 changelog 约定。收尾验证每次认为工作完成前运行make precommit。对纯文档、纯测试或纯评审任务同样要遵守上述仓库指导跳过不适用的步骤但保持同样的范围纪律、验证纪律与仓库约定。这套测试先行 → 最小实现 → 行为锁定 → 性能与文档兜底 → 统一验证的顺序与 distribution 仓库内部 project/hooks/pre-commit 所体现的先让门禁挡住坏代码再谈提交的工程文化一致。四、验证体系为什么make是唯一的完成标准文档明确规定使用make作为仓库的权威验证命令默认目标是precommit。make precommit是 lint、代码生成、README 检查、模块检查与测试的最终验证步骤。迭代过程中可以使用定向命令如go test ./...做快速反馈但只要任务改了代码就不能止步于此。若触及性能敏感代码除了make之外还要跑聚焦的 benchmark并用benchstat对比结果。从上游仓库的 CONTRIBUTING.md 可以印证这套验证的定义precommit目标会修复代码格式并检查 go module 文件状态运行后git status输出nothing to commit, working tree clean即代表一切最新且格式正确。换句话说make precommit不只是一次检查它同时承担了格式化与生成文件同步的职责是仓库健康度的单点权威。需要提醒的是make precommit是opentelemetry-go 上游仓库的约定当前 distribution 仓库根目录的 Makefile 默认目标是help提供了test、test-race、test-full、integration、test-coverage、lint、validate、validate-git、validate-vendor、mod-outdated等目标。因此在将上游 AGENTS.md 的方法论迁移到别的仓库时务必先确认目标仓库实际的 Makefile 目标名而不是机械照搬。五、文档与 Changelog 规范用户可见变更必须留下的四件套文档对改完代码之后提出了明确的产出要求GoDoc非 internal、非测试的包应有 Go 文档注释通常放在doc.go中。上游仓库根目录的 doc.go 就是典型例子。README非 internal、非测试、非文档类包还应有README.md至少包含标题与pkg.go.devbadge。示例优先GoDoc 中能放示例就放示例而不是长篇代码片段。文档必须与行为同步不留下过期的注释、示例或包文档。Changelog用户可见的变更必须更新 CHANGELOG.md落到## [Unreleased]下对应的Added、Changed、Deprecated、Fixed或Removed小节。Changelog 还有三条容易被 Agent 忽略的硬性格式约束原文如下行尾始终放PR 号例如(#1234)而不是issue 号。如果 PR 号尚未可知先省略待 PR 创建后再补上并确保在合并前更新。始终使用被更新的go module 全名做引用如go.opentelemetry.io/otel/sdk/metric而不是仅写路径如sdk/metric。这些约束在当前 vendored 的 CHANGELOG.md 中可以得到逐条验证比如 v1.45.0 版本条目中的Add the experimentalWithUnsafeAttributes... (#8251)行尾是 PR 号而非 issue 号又如BatchProcessor相关条目明确写全模块名go.opentelemetry.io/otel/sdk/log。这两条实证说明规范并非纸面文章而是仓库实际执行并留下的记录。六、仓库习惯Agent 融入社区代码风格的五个动作聚焦 diff偏好聚焦的 diff避免顺手清理drive-by cleanup——这能大幅降低评审成本。沿用既有模式遵循既有的 option 模式与导出 API 约定不要发明新的抽象。生成文件入库生成的文件是检入checked in的若改动影响生成结果必须保持生成输出最新。上游仓库的 semconv 包即属此类。快速检索探索仓库时优先使用rg这类快速本地搜索工具——这也与本环境推荐的代码搜索工作流一致。不变量显式化改动行为时在测试中把不变量显式写出来让回归测试成为行为的活文档。七、五种 Agent 角色什么时候该用谁边界在哪里AGENTS.md 最大的特色是定义了五种 persona每种角色有明确的使用场景与禁止事项。这是本文档最具任务型价值的部分逐一定义如下。Feature Agent新行为与新 API 的负责人适用于新行为、新 API 面或规范驱动spec-driven的功能工作从一个失败的单元测试开始对照规范、既有包行为与公共 API 兼容性确认期望行为实现最小可行改动当变更用户可见时同步更新 GoDoc、示例、README.md与CHANGELOG.md功能触及热路径时检查 benchmark缺失则补一个。Refactoring Agent结构优化但不改行为的负责人适用于在不刻意改变行为的前提下改善结构把行为保持视为默认契约若当前行为尚未被测试钉死先补测试或收紧测试再移动代码除非被明确要求避免大规模重写、精巧的抽象或全包清理重构触及热路径时重构前后都要跑 benchmark除非任务另有说明保持 API 形态、语义、并发保证与失败模式不变。Test Agent补覆盖、复现 bug、加固回归的负责人用你能写出的最小失败测试复现 bug 或缺失行为优先测试公共行为与外部可见的不变量在改生产代码之前先加有针对性的回归测试只有当必须让被测行为正确或可测时才改动生产代码保持测试确定性、可读性并与包的既有模式一致。Performance Agent热路径、分配削减与吞吐/延迟优化的负责人先 benchmark 建立基线再动手优先减少分配、拷贝、接口切换与不必要的同步绝不为微优化牺牲正确性、规范符合性或 API 稳定性性能敏感覆盖缺失时补或更新 benchmark实质性改动热路径时记录前后结果最好用benchstat。Review Agent代码、补丁与 PR 的评审负责人评审角色的要求非常具体适合直接用作 Agent 评审的 checklist用发现findings开场而不是总结按严重程度排序尽可能给出精确的文件与行号引用聚焦正确性、规范符合性、API 兼容性、并发安全、健壮性、性能回归、缺失测试、缺失 benchmark、文档缺口与 changelog 缺口当 diff 比必要范围更宽时要明确指出如果没发现问题要明确说出来并注明残余风险或验证缺口。八、将这套规范迁移到其他 Go 仓库的落地建议综合全文可以把 AGENTS.md 提炼成一份可复用的Go 仓库 Agent 协作基线开工前固定阅读顺序全局指导 → 贡献规范 → 任务指令让 Agent 的上下文加载可预期。测试先行任何行为变更都以失败测试开头用测试把行为和不变量锁死。最小 diff把聚焦 diff、不做顺手清理写成显式约束降低人类评审负担。单一验证入口用make precommit之类的单一命令统一 lint、生成、模块与测试检查并把它定为完成的唯一标准。文档与代码同步GoDoc、README、示例、CHANGELOG 缺一不可Changelog 必须写 PR 号、写模块全名。角色分工按任务性质选择 Feature / Refactoring / Test / Performance / Review 角色并尊重各角色的禁止事项如 Refactor 不得悄悄改行为、Performance 不得牺牲正确性。迁移适配落地到目标仓库时先确认其 Makefile 目标与 hooks 机制可参考 project/hooks/README.md 中通过configure-hooks.sh安装 pre-commit 钩子的做法不要照搬上游命令名。这份文档的价值在于它把开源维护者对安全改动的隐性判断编码成了 Agent 可以逐条执行的显式规则——规范符合性、API 稳定性、热路径保守、行为锁定、验证闭环、角色边界六者缺一不可。对正在将 AI Agent 引入 Go 项目开发的团队而言它就是一份可以直接复制并本地化的最佳实践模板。赞分享云原生存储【免费下载链接】distributionThe toolkit to pack, ship, store, and deliver container content项目地址https://gitcode.com/gh_mirrors/dis/distribution点击查看免费下载相关推荐解密Windows热键冲突3步找到偷走你快捷键的神秘程序解密Windows热键冲突3步找到偷走你快捷键的神秘程序 你是否曾经遇到过这样的烦恼精心设置的CtrlShiftS保存快捷键突然失效或者F5刷新键云原生CLI镜像仓库Mastra PR 审查智能体的 TypeScript 风格规范命名约定、导入排序与错误处理标准Mastra PR 审查智能体的 TypeScript 风格规范命名约定、导入排序与错误处理标准 本文解析 Mastra 官方模板 template gith人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音BMAD-METHOD 默认 Agent 体系完全指南五位角色型 Agent 的 Skill 标识、菜单触发码与工作流解析BMAD METHOD 默认 Agent 体系完全指南五位角色型 Agent 的 Skill 标识、菜单触发码与工作流解析 BMAD METHODBreakAI 技能人工智能开发工具上一篇智慧树学习助手告别手动刷课3步实现自动化高效学习下一篇智慧树学习助手终极指南3步实现自动刷课效率提升150%创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考