Nhost 仓库中的 opentelemetry-go AGENTS.md 解读面向自主编码 Agent 的工程纪律与协作规则【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost本文以 Nhost 仓库 vendor 目录中随 Go 依赖一并检入的vendor/go.opentelemetry.io/otel/AGENTS.md为主体完整解读这份“编码 Agent 指南”的核心预期、七步默认工作流、make precommit验证规范、文档与 CHANGELOG 约定以及 Feature / Refactoring / Test / Performance / Review 五类 Agent 角色分工并结合 vendor 目录下真实的Makefile、doc.go、README.md等文件交叉印证这些规则在 opentelemetry-go 中的落地方式帮助读者把同样的纪律写入自己仓库的 Agent 指南。AGENTS.md 在 Nhost 仓库中的位置Nhost 是一个 Go TypeScript 混合 monorepoGo 服务、CLI、Dashboard 等其 Go 工作区通过go.mod以间接依赖形式引入了 OpenTelemetry-Gogo.opentelemetry.io/otel v1.44.0 // indirect go.opentelemetry.io/otel/metric v1.44.0 // indirect go.opentelemetry.io/otel/trace v1.44.0 // indirect见 go.mod。执行go mod vendor后依赖的完整源码连同上游仓库的 Markdown 文档被冻结到vendor/目录因此上游的这份 Agent 指南也原样存在于 vendor/go.opentelemetry.io/otel/AGENTS.md。从 vendor/modules.txt 可以看到本仓库实际使用了该库的otel、attribute、baggage、codes、metric、trace、propagation、semconv等多个子包——这正是 Nhost 服务做分布式追踪与指标采集时的 API 面。这份文件的定位在开头写得很明确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和本文件其中copilot-instructions.md作为“全局被动指导”适用于每一个任务包括纯文档任务和纯评审任务。这种“主动任务指令 全局被动约束”的双层结构是编写仓库级 Agent 指南时值得直接借鉴的分层思路。核心预期十二条工程底线AGENTS.md 的 “Core expectations” 一节用 12 条祈使句给出了不可退让的工程底线可以归纳为五组约束规范与 API 优先保持 OpenTelemetry 规范合规、API 稳定、Go 代码地道公共 API 向后兼容除非任务明确要求破坏性变更。最小化外科式变更优先小而准的改动反对大范围重构和投机性清理编辑某个包之前先读该包使其命名、Option 类型、错误处理、注释、测试和并发模式与现状一致。遥测的宿主安全性Telemetry Resilience这是本指南最有行业特色的一组约束——保持遥测“有弹性、松耦合”不得引入会意外干扰宿主应用的行为仔细检查边界输入校验、资源限制、取消、关停、错误传播、并发、内存增长优先 fail-safe 行为和显式不变量而不是隐式假设遥测代码不得 panic、不得无限阻塞、不得放大攻击者可控输入在热路径上保持保守避免不必要的分配、反射、接口转换interface churn、阻塞、全局状态和高基数high-cardinality遥测。依赖最小化保持依赖最小且有正当理由keep dependencies minimal and justified。注释纪律只为“意图、不变量、非显而易见的约束”写注释禁止复述代码本身的注释。对“库作者”而言第 3 组约束本质上是在回答一个根本问题被依赖方出错的成本由谁承担一个埋进宿主应用的 tracing/metrics SDK一旦 panic 或阻塞炸的是宿主应用而不是自己。把这些“宿主应用安全”条款显式写进 Agent 指南等于把库作者最容易忽视的责任边界固化成了 Agent 每次改代码前必须核对的检查项。默认七步工作流先测试后实现“Default workflow” 一节规定除非任务另有说明新功能和行为变更必须按以下顺序执行阅读相关包、它的测试以及包文档或README.md先添加或更新一个能捕捉目标行为/回归的失败单元测试failing unit test实现让测试通过的最小改动只有在行为被测试“钉死”之后才允许重构且重构必须保持 diff 聚焦若改动位于热路径或性能敏感代码先检查现有 benchmark缺失则补一个并实际运行趁上下文还热的时候更新文档产物遵循下文文档与 changelog 约定在认为工作完成之前运行make precommit。这是一条标准的“失败测试驱动 最小实现 事后重构”的 TDD 流水线且每一步都对 Agent 的可执行性做了收紧第 2 步要求测试“失败”而不是“通过”第 4 步给重构设置了行为锁定的前置条件第 7 步把工作完成的判定权交给一条确定性命令。指南同时覆盖了非代码任务对于 docs-only、test-only 或 review-only 任务仍然要先读仓库指导文件只是跳过不适用步骤但范围控制、验证方式和仓库约定的纪律保持不变。这避免了 Agent 在“小任务”上放松验证纪律的常见漏洞。验证make precommit 是唯一权威“Verification” 一节只有一条命令级的硬规则make是该仓库的权威验证命令默认目标是precommitmake precommit是 lint、代码生成、README 检查、module 检查和测试的期望最终验证步骤迭代过程中可以用定向命令如单个包go test快速反馈但只要任务改了代码就不能止步于此触碰性能敏感代码时除了make还要运行聚焦 benchmark 并用benchstat对比结果。这条规则在 vendor 副本中可以直接交叉印证。vendor/go.opentelemetry.io/otel/Makefile 中确实声明了.DEFAULT_GOAL : precommit且precommit目标由一串确定性步骤组成precommit: generate toolchain-check license-check misspell go-mod-tidy golangci-lint-fix verify-readmes verify-mods test-default ci: generate toolchain-check license-check lint vanity-import-check verify-readmes verify-mods build test-default check-clean-work-tree test-coverage也就是说“跑make precommit” 在 opentelemetry-go 里意味着依次完成代码生成、Go 工具链版本检查、License 头检查、拼写检查、go mod tidy校验、golangci-lint 自动修复、README 徽章/链接校验verify-readmes、多 module 一致性校验verify-mods和默认测试集。ci目标则在其之上追加了 build、干净工作树检查与覆盖率统计。AGENTS.md 把“Agent 必须记住的验证命令”压缩成了一条把展开细节留在 Makefile 里——指南只写不变量实现细节交给工具链这正是它易于被 Agent 稳定执行的原因。文档与 CHANGELOG 约定文档即代码的一部分“Documentation and changelog” 一节给出四条可核查的硬约定非 internal、非测试包必须有 Go doc 注释通常放在doc.go中。vendor 副本中的 vendor/go.opentelemetry.io/otel/doc.go 就是一个实例它用包注释声明otel包“提供对 OpenTelemetry API 的全局访问”并说明默认情况下采集到的数据不会被处理或传输需配合 SDK 与 exporter 使用再分别指向trace、metric、log、propagation、baggage子包——整段注释本身就是“文档与真实行为对齐”的样板。非 internal、非测试、非纯文档包还必须有README.md至少包含标题和pkg.go.dev徽章。vendor/go.opentelemetry.io/otel/README.md 顶部就带有 PkgGoDev 徽章并给出项目状态表Traces / Metrics 为 StableLogs 为 Beta与 Go 版本兼容策略——这些内容正是verify-readmes一类检查所守护的文档面。GoDoc 中优先使用可运行的 example 而非长代码片段。文档必须与实际行为对齐不允许留下过期的注释、示例或包文档。对用户可见的变更还要更新CHANGELOG.md条目必须落在## [Unreleased]下恰当的Added/Changed/Deprecated/Fixed/Removed小节中。这份文件同样随 vendor 目录存在vendor/go.opentelemetry.io/otel/CHANGELOG.md其Unreleased 分节结构就是该约定的实物形态。对 Agent 而言这条约定的意义在于“改完代码”不等于“完成”CHANGELOG 分节归类是完成判据的一部分而分节命名又保证了 changelog 本身可被脚本解析例如 Nhost 仓库自己的changelog_summary.sh、cliff.toml这类工具链通常依赖此类结构化约定。五类 Agent 角色把纪律按任务类型特化“Personas” 一节是这份指南最有辨识度的部分它不要求 Agent 记住一份大而全的守则而是按任务类型激活五个性格化角色每个角色只携带与当前任务相关的约束。角色适用场景关键纪律Feature Agent新行为、新 API 面、规范驱动的功能开发从失败单元测试出发对照规范、既有包行为、公共 API 兼容性确认预期实现最小可行改动用户可见变更要同步 GoDoc、example、README.md与CHANGELOG.md触及热路径则检查/补充 benchmarkRefactoring Agent改结构但不改行为行为保持是默认契约若当前行为尚未被测试钉死先补测试再动代码避免大面积重写、炫技抽象、整包清理触及热路径则前后各跑一次 benchmarkAPI 形状、语义、并发保证、失败模式默认不变Test Agent补覆盖、复现 bug、加固回归用能写出的最小失败测试复现问题优先测公共行为与对外可见的不变量先加回归测试再改生产代码只在让被测行为正确或可测时才动生产代码测试保持确定性、可读、贴合包内既有模式Performance Agent热路径、降分配、吞吐与延迟优化先 benchmark 建立基线优先减少分配、拷贝、接口转换和多余同步不为微优化牺牲正确性、规范合规或 API 稳定覆盖缺失时补 benchmark实质性改动热路径要留下前后对比优先用benchstatReview Agent评审代码、补丁或 PR结论先行不做摘要开场按严重度排序发现项并给出精确的文件与行号引用关注正确性、规范合规、API 兼容、并发安全、弹性、性能回归、缺失测试/benchmark、文档缺口、changelog 缺口diff 超出必要范围要直接指出没有问题就明确说没有问题并说明残余风险与验证缺口五个角色之间共享同一条主线——行为先于结构、证据先于结论Feature 与 Test 角色都从“失败测试”起步Performance 角色强制“基线在前”Refactoring 角色把“行为保持”设为默认契约Review 角色则要求用文件/行号级别的证据说话而非泛泛总结。这套角色划分实际上回答了一个工程问题同一份通用守则对不同任务类型会产生不同优先级与其让 Agent 自行取舍不如在指南里预先特化。对 Nhost 这类 monorepo 的启示把这份 vendor 目录里“借来的”指南放回 Nhost 仓库自身来看可以看到同一个问题的两种表达Nhost 根目录与各子项目使用CLAUDE.md系列文件如根 CLAUDE.md 声明“各子项目可能有自己的CLAUDE.md处理某个项目时务必先加载它”为编码 Agent 提供项目级上下文而 opentelemetry-go 则用AGENTS.mdcopilot-instructions.md的组合提供任务级纪律。二者指向同一结论也正好构成一份可操作的“如何写好 Agent 指南”清单写“任务导向的祈使句”不写愿景——每条规则都应能被 Agent 在一次任务中执行或核查先写失败测试、跑make precommit、更新Unreleased分节验证收敛为一条权威命令——把 lint/generate/test 展开在 Makefile 中指南里只暴露make precommit与.DEFAULT_GOAL的默认行为Agent 无需理解展开细节把“完成”的定义写死——包含 benchmark 对比benchstat、文档同步、CHANGELOG 分节、干净工作树而不只是“测试通过”对库/SDK 类代码显式声明宿主安全责任——不 panic、不阻塞、不放大攻击者输入、热路径零多余分配按任务类型预置角色把行为保持、基线优先、结论先行等约束分发给对应角色降低 Agent 在任务切换时的自由度。从源码结构看Nhost 自身的服务如services/下的 Go 服务与cli/同样依赖go.opentelemetry.io/otel提供的trace/metricAPI 面见 vendor/modules.txt 中的包清单因此这类“遥测宿主安全”条款并非空泛口号对任何把 OpenTelemetry 埋点织入业务服务的仓库AGENTS.md 中“遥测不得干扰宿主应用”的一组约束都可以直接移植为自家 Agent 指南中的一条检查项。小结vendor/go.opentelemetry.io/otel/AGENTS.md用不到一百行给出了一个完整的“Agent 协作工程”范式以 12 条核心预期划定规范合规、API 稳定与遥测弹性的底线以七步失败测试驱动工作流锁定行为以make precommit单命令收敛全部验证以doc.go/README/CHANGELOG 三类产物保证文档与实现同步最后用 Feature、Refactoring、Test、Performance、Review 五个角色把通用纪律特化成任务级行为。对于正在为自己的 Go 仓库尤其是被广泛依赖的库引入编码 Agent 的团队这份随 Nhost vendor 目录可完整获取的指南及其背后 vendor/go.opentelemetry.io/otel/Makefile、vendor/go.opentelemetry.io/otel/doc.go、vendor/go.opentelemetry.io/otel/README.md 等可交叉印证的文件构成了一份可直接对标的写作样本。【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考