企业官网建设流程全解析

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 混合 monorepo（Go 服务、CLI、Dashboard 等），其 Go 工作区通过go.mod以间接依赖形式引入了 OpenTelemetry-Go：

go.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 条祈使句给出了不可退让的工程底线，可以归纳为五组约束：

1. 规范与 API 优先：保持 OpenTelemetry 规范合规、API 稳定、Go 代码地道；公共 API 向后兼容，除非任务明确要求破坏性变更。
2. 最小化外科式变更：优先小而准的改动，反对大范围重构和投机性清理；编辑某个包之前，先读该包，使其命名、Option 类型、错误处理、注释、测试和并发模式与现状一致。
3. 遥测的宿主安全性（Telemetry Resilience）：这是本指南最有行业特色的一组约束——
   • 保持遥测“有弹性、松耦合”，不得引入会意外干扰宿主应用的行为；
   • 仔细检查边界：输入校验、资源限制、取消、关停、错误传播、并发、内存增长；
   • 优先 fail-safe 行为和显式不变量，而不是隐式假设；
   • 遥测代码不得 panic、不得无限阻塞、不得放大攻击者可控输入；
   • 在热路径上保持保守：避免不必要的分配、反射、接口转换（interface churn）、阻塞、全局状态和高基数（high-cardinality）遥测。
4. 依赖最小化：保持依赖最小且有正当理由（keep dependencies minimal and justified）。
5. 注释纪律：只为“意图、不变量、非显而易见的约束”写注释，禁止复述代码本身的注释。

对“库作者”而言，第 3 组约束本质上是在回答一个根本问题：被依赖方出错的成本由谁承担？一个埋进宿主应用的 tracing/metrics SDK，一旦 panic 或阻塞，炸的是宿主应用而不是自己。把这些“宿主应用安全”条款显式写进 Agent 指南，等于把库作者最容易忽视的责任边界固化成了 Agent 每次改代码前必须核对的检查项。

默认七步工作流：先测试后实现

“Default workflow” 一节规定，除非任务另有说明，新功能和行为变更必须按以下顺序执行：

1. 阅读相关包、它的测试，以及包文档或README.md；
2. 先添加或更新一个能捕捉目标行为/回归的失败单元测试（failing unit test）；
3. 实现让测试通过的最小改动；
4. 只有在行为被测试“钉死”之后才允许重构，且重构必须保持 diff 聚焦；
5. 若改动位于热路径或性能敏感代码，先检查现有 benchmark，缺失则补一个，并实际运行；
6. 趁上下文还热的时候更新文档产物（遵循下文文档与 changelog 约定）；
7. 在认为工作完成之前，运行make precommit。

这是一条标准的“失败测试驱动 + 最小实现 + 事后重构”的 TDD 流水线，且每一步都对 Agent 的可执行性做了收紧：第 2 步要求测试“失败”而不是“通过”，第 4 步给重构设置了行为锁定的前置条件，第 7 步把工作完成的判定权交给一条确定性命令。

指南同时覆盖了非代码任务：对于 docs-only、test-only 或 review-only 任务，仍然要先读仓库指导文件，只是跳过不适用步骤，但范围控制、验证方式和仓库约定的纪律保持不变。这避免了 Agent 在“小任务”上放松验证纪律的常见漏洞。

验证：make precommit 是唯一权威

“Verification” 一节只有一条命令级的硬规则：

• make是该仓库的权威验证命令，默认目标是precommit；
• make 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” 一节给出四条可核查的硬约定：

1. 非 internal、非测试包必须有 Go doc 注释，通常放在doc.go中。vendor 副本中的 vendor/go.opentelemetry.io/otel/doc.go 就是一个实例：它用包注释声明otel包“提供对 OpenTelemetry API 的全局访问”，并说明默认情况下采集到的数据不会被处理或传输，需配合 SDK 与 exporter 使用，再分别指向trace、metric、log、propagation、baggage子包——整段注释本身就是“文档与真实行为对齐”的样板。
2. 非 internal、非测试、非纯文档包还必须有README.md，至少包含标题和pkg.go.dev徽章。vendor/go.opentelemetry.io/otel/README.md 顶部就带有 PkgGoDev 徽章，并给出项目状态表（Traces / Metrics 为 Stable，Logs 为 Beta）与 Go 版本兼容策略——这些内容正是verify-readmes一类检查所守护的文档面。
3. GoDoc 中优先使用可运行的 example 而非长代码片段。
4. 文档必须与实际行为对齐，不允许留下过期的注释、示例或包文档。

对用户可见的变更，还要更新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 与 Test 角色都从“失败测试”起步，Performance 角色强制“基线在前”，Refactoring 角色把“行为保持”设为默认契约，Review 角色则要求用文件/行号级别的证据说话而非泛泛总结。这套角色划分实际上回答了一个工程问题：同一份通用守则对不同任务类型会产生不同优先级，与其让 Agent 自行取舍，不如在指南里预先特化。

对 Nhost 这类 monorepo 的启示

把这份 vendor 目录里“借来的”指南放回 Nhost 仓库自身来看，可以看到同一个问题的两种表达：Nhost 根目录与各子项目使用CLAUDE.md系列文件（如根 CLAUDE.md 声明“各子项目可能有自己的CLAUDE.md，处理某个项目时务必先加载它”）为编码 Agent 提供项目级上下文，而 opentelemetry-go 则用AGENTS.md+copilot-instructions.md的组合提供任务级纪律。二者指向同一结论，也正好构成一份可操作的“如何写好 Agent 指南”清单：

1. 写“任务导向的祈使句”，不写愿景——每条规则都应能被 Agent 在一次任务中执行或核查（先写失败测试、跑make precommit、更新Unreleased分节）；
2. 验证收敛为一条权威命令——把 lint/generate/test 展开在 Makefile 中，指南里只暴露make precommit与.DEFAULT_GOAL的默认行为，Agent 无需理解展开细节；
3. 把“完成”的定义写死——包含 benchmark 对比（benchstat）、文档同步、CHANGELOG 分节、干净工作树，而不只是“测试通过”；
4. 对库/SDK 类代码显式声明宿主安全责任——不 panic、不阻塞、不放大攻击者输入、热路径零多余分配；
5. 按任务类型预置角色，把行为保持、基线优先、结论先行等约束分发给对应角色，降低 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