尧图网页设计 
Grafana Tempo 的 Agent 协作开发规范AGENTS.md 全解析与贡献实战指南【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempoGrafana Tempo 是一个面向高吞吐、低依赖场景的分布式链路追踪后端其代码仓库根目录下的 AGENTS.md 是一份面向 AI AgentCursor、Claude Code、Copilot 等与人类开发者的统一协作指南。它定义了 Changelog 管理、编码规范、代码审查、文档写作和提交前检查五大约束。本文以该文件为核心骨架结合.agents/guidance/下的详细规范、Makefile 中的命令体系以及 .chloggen/ 的变更条目机制逐层拆解 Tempo 仓库对代码贡献的硬性要求帮助你或你的 Agent在提交 PR 前一次通过评审。一、AGENTS.md 在仓库中的定位AGENTS.md 位于仓库根目录是 Tempo 面向 AI 编程工具与人工贡献者的第一入口。它本身只有五个小节、二十余行但每一条都是一份更详细规范的入口指针小节职责指向的详细规范Changelog Entries管理用户可见变更的 changelog 条目.chloggen/README.mdCoding Standards编写/修改 Go 代码前的编码标准.agents/guidance/coding.mdCode Review Standards进行代码审查时的多领域审查框架.agents/guidance/code-review.mdWriting Standards撰写 Markdown 文案时的写作标准.agents/guidance/writing.mdPre-Commit Checklist推送或开 PR 前的自检清单.agents/guidance/precommit.md从设计意图看Tempo 将规则与入口分离AGENTS.md 保持极简保证任何 Agent 在打开仓库时能快速定位应遵守的规范详细内容下沉到.agents/guidance/避免根文档臃肿。这种模式本身即是值得借鉴的仓库治理实践。二、Changelog Entries用 chloggen 替代直接编辑 CHANGELOG.mdAGENTS.md 的第一条硬性规则是永远不要直接编辑CHANGELOG.md。每个用户可见的变更都必须在 .chloggen/ 下新增一个 YAML 条目。2.1 为什么禁止直接编辑Tempo 使用仓库内置的 chloggen 工具管理变更日志。直接在共享的CHANGELOG.md上并发编辑必然产生合并冲突改为每个 PR 携带独立的小 YAML 文件后冲突被彻底消除发布时再由工具统一汇总collate进 changelog。这正是 .chloggen/README.md 中说明的机制。2.2 创建与校验命令从 Makefile 可以看到 chloggen 从 tools 子模块构建并以仓库根目录为工作目录运行make chlog-new # 生成 .chloggen/当前分支名.yaml基于 TEMPLATE.yaml make chlog-new FILENAMEmy-change # 显式指定条目文件名main/master 或 detached HEAD 下必须指定 make chlog-validate # 校验所有待发布条目 make chlog-preview # 将待发布条目渲染到标准输出预览发布仅维护者时执行make chlog-update VERSIONv2.11.0 # 汇总条目写入 CHANGELOG.md 并删除条目文件2.3 条目文件的结构生成的条目基于 TEMPLATE.yaml模板文件本身在.chloggen/目录中填写示例change_type: enhancement # breaking | change | feature | enhancement | bug_fix | security component: metrics-generator # 必须在 config.yaml 的 components 允许清单内 note: A brief description of the change. issues: [] # 可选留空则发布时自动从提交信息解析 PR 号 subtext: # 可选补充细节 user: your-github-handle # 渲染为 (your-github-handle)各change_type关键字在 changelog 中对应不同分区breaking→、change→、feature→、enhancement→、bug_fix→、security→。component必须落在 .chloggen/config.yaml 的允许清单内否则chlog-validate直接拒绝新增组件需在同一次 PR 中同步修改该清单。2.4 写 note 的核心原则保持简短最多一两句话聚焦用户影响描述用户得到了什么而非技术上做了什么例如✅Improve read performance by pushing down predicates to the parquet iterators.❌Add support for pushdown predicates in the parquet iterators.确需补充的实现细节放在subtext不放 note。这一条规则直接呼应了 docs 侧对 changelog 质量的长期要求变更日志是面向运维与终端用户的不是内部实现的流水账。三、Coding StandardsGo 编码规范的五个层次.agents/guidance/coding.md 从核心哲学、测试、错误处理、并发、资源管理、惯用模式、性能到 Tempo 特有约定系统定义了 Go 代码的书写底线。3.1 核心哲学与测试写干净、朴素、惯用的 Go标准库优先显式优于隐式测试先行是默认路径先写测试 → 验证其失败证明测试确实有效→ 写最小实现使其通过 → 重构测试结构采用 table-driven subtests 模式规范中给出了TestSomething的完整骨架示例覆盖率目标作为指导而非硬性规则关键路径 80%、业务逻辑 75%、整体 70%任何新/变更行为都必须覆盖 happy path、错误路径与边界nil、空、零值。3.2 错误处理一律用fmt.Errorf(...: %w, err)包装错误以保留上下文禁止直接返回裸错误绝不静默吞错_ someFunc()属于反面示例比较错误用errors.Is/errors.As禁止err ErrNotFound包装后会失效生产服务与库代码中禁止 panic初始化失败应向上返回错误并交给main退出。3.3 并发与资源管理goroutine 必须有明确生命周期优先响应ctx.Done()取消信号用 channel 做编排/信号用 mutex 保护共享状态共享计数器等给出SafeCounter式的显式加锁示例必须跑go test -race发现竞态即修复而非抑制context 必须是函数第一个参数并贯穿所有 goroutine资源获取后立即defer清理文件、HTTP body、数据库行、锁、连接。3.4 性能先测量再优化性能优化必须 profile 先行go test -cpuprofilecpu.out -memprofilemem.out -bench. ./...与go test -bench. -benchmem ./...是标准工具热路径上 3 倍慢的实现若能换来清晰度可以接受——上下文比基准数字更重要分配模式已知大小预分配make([]T, 0, n)、紧循环中复用 buffer、短生命周期高频对象用sync.Pool、循环拼接字符串用strings.Builder算法上优先 O(n log n)对 Parquet 迭代器使用SeekTo()跳过已扫描的 row group。规范中还给出了 Tempo 的已知热路径清单这些位置改动必须有基准数据支撑路径文件基准佐证Span 摄取instance.push()modules/ingester/instance.goBenchmarkInstancePush、BenchmarkInstanceContentionLive trace 追加liveTrace.Push()modules/ingester/trace.go每 span 在 mutex 下调用TraceQL 二元运算pkg/traceql/ast_execute.goBenchmarkBinOpParquet 行号比较pkg/parquetquery/iters.goBenchmarkEqualRowNumberParquet TraceQL 块执行tempodb/encoding/vparquet5/block_traceql.go4 个以上关系运算符基准字符串驻留interningpkg/parquetquery/intern/intern.go对重复值使用 unsafe3.5 Tempo 特有约定从代码库中沉淀的惯例配置校验返回(warnings []error, err error)warnings 非致命降级运行err 致命——参考 modules/overrides 及 config 校验相关实现让运维在部分配置缺失时仍能启动复杂构造函数用类型化 option 接口而非裸func(*T)option 自描述且可携带状态租户行为必须透传通过 handler 链传递overrides.Interface始终从 context 提取 tenant ID绝不硬编码租户级行为泛型用于类型安全队列/容器如PriorityQueue[T Op]消除运行时类型断言队列组件内嵌 Prometheus gauge并为测试场景做 nil 保护mock 用_占位未用参数、//nolint:all抑制 stub 的 lint、线程安全计数器做断言同一初始化逻辑重复 3 次以上提取为局部闭包新增查询路径保持向后兼容旧路径保留新路径由 hint/flag 门控引擎选择走哪条路调用方不变配置默认值与破坏性变更在CHANGELOG.md与变更点代码注释中同步说明移除配置字段时留下替代说明如QueryIngestersUntil在 v2.7 移除改用QueryBackendAfter。四、Code Review Standards十遍通过的审查框架.agents/guidance/code-review.md 定义了多领域审查框架要求按 pass 系统推进并为每个发现记录what、why、wherefile:line、severity 和具体修复方案。4.1 严重级别与路由CRITICAL可利用漏洞、数据丢失、崩溃注入、认证绕过、热路径 nil 解引用、硬编码凭据HIGH严重 bug、破坏性行为、安全弱点关键路径缺错误处理、竞态、资源/goroutine 泄漏、弱加密、破坏性 API 变更MEDIUM质量问题、潜在 bug、非惯用代码缺校验、N1 查询、缺缓存LOW风格、小改进、文档注释错别字、命名建议。路由规则任何 CRITICAL/HIGH 必须修复后才能合并并考虑重审设计仅 MEDIUM/LOW 则定点修复、不阻塞。4.2 十个审查 PassSecurityOWASP Top 10、硬编码凭据、注入特别强调——配置结构中任何命名含password/token/key/secret/credential/auth的字段必须使用flagext.Secret或config.Secret来自github.com/prometheus/common/config确保日志与序列化输出中被脱敏并给出 grep 排查命令集os/exec、弱密码学crypto/md5/crypto/sha1、math/rand用于安全目的等Bug Diagnosisnil 解引用、数据竞态、off-by-one、资源未关闭、未检查的类型断言Error Handling忽略错误、静默吞错、缺少%w包装上下文、panic 代替错误返回Code Quality Logic逻辑错误、边界缺失、跨文件一致性、死代码、测试覆盖缺口PerformanceO(n²) 算法、紧循环内分配、热路径回归必须有基准佐证已知热路径同 coding.md 清单Go Idiomsstuttering 命名、接口过大、无生命周期 goroutine、比较错误、循环内 defer、init()滥用Architecture Design紧耦合、缺抽象、违反单一职责、循环依赖、阻碍可测试性的全局状态Documentation示例无法编译或与 API 不符、导出符号缺注释、README 命令失效Comment Accuracy过期/误导性注释、错误的参数/返回值描述、未解决的 TODO/FIXME给出git diff HEAD --name-only | xargs grep -n TODO\|FIXME\|HACK\|XXX排查命令Reference Integrity注释中引用的 spec/设计文档必须真实存在、且代码与所引章节描述一致。输出格式要求按Critical Issues (Must Fix)→High Priority Issues→Medium Priority Issues→Low Priority Issues→Summary含各级数量与 MUST FIX / TARGETED FIXES / READY 结论组织。4.3 Tempo 维护者的实战审查标准测试特异性锁定完整行为契约而非松散断言如用assert.Equal(t, GET /api/users/_, result)而非assert.Contains(t, result, _)并发假设必须显式跨 goroutine 共享的切片/指针要注明是否安全必要时解释拷贝原因性能声明需要生产证据仅微基准不足以定论须用真实/仿真集群 profile 佐证引述维护者原话SortTrace is not present in CPU profiles at all... 0.02% of CPU异步行为必须文档化Tempo 在 live-store、block-builders 等多处异步执行限额代码注释与文档都必须明确说明最小化导出默认不导出仅在测试中使用的保持在测试文件内且不导出进程内调用不过度设计monolith 场景直接函数调用即可避免 gRPC/channel/worker pool命名必须精确一个canonical命名的争议最终被解析为NormalizeQuery——名字应传达无歧义的意图。五、Writing StandardsMarkdown 语义化换行SemBr.agents/guidance/writing.md 要求所有文档、README、设计文档与 Agent 指南采用Semantic Line BreaksSemBr写作在语义边界换行而不是固定列宽硬折或整段一行。Tempo 仓库的 docs/ 与各模块 AGENTS.md 普遍遵循这一约定。原因diff 只显示真正变更的句子/子句审查者可针对单句评论LLM 辅助写作倾向产出长而密的段落SemBr 让这类编辑保持可审工具官方 SemBr 技能位于 .agents/doc-agents/ 工作流体系内skill 定义在.claude/skills/sembr-reformat/SKILL.md源自 MIT 许可的 sembr/skills 项目范围只对新增文案与正在编辑的段落应用不批量重排未触及文件避免 diff 噪音代码块、表格、YAML frontmatter 及换行有语法意义的标记一律保留原样。六、Pre-Commit Checklist推送前的五道关卡.agents/guidance/precommit.md 定义了开 PR 前的最低门槛对应命令均可从 Makefile 找到实现。6.1 格式化与 Lintmake fmt # gofumpt goimportsCI 跑 make check-fmt工作树不干净即失败 make lint # golangci-lint make lint baseorigin/main # 仅检查相对 base 分支的 diff与 CI 行为一致大仓库推荐6.2 单元测试与 E2emake test # 全包测试 make test-with-cover # 带 race detector 与覆盖率匹配 CI 拆分 make test-with-cover-pkg # CI 将测试拆为 pkg / tempodb / tempodb-wal / others 四组 make test-with-cover-tempodb make test-with-cover-tempodb-wal make test-with-cover-others make test-e2e # 全套 E2e需 Docker先构建本地 Tempo 镜像 make test-e2e-api # 也可单独跑各套件 make test-e2e-operations make test-e2e-limits make test-e2e-metrics-generator make test-e2e-storage make test-e2e-clean # 跑完后清理 Docker 拥有的测试目录6.3 开 PR 前的最低门槛make fmt——工作树无 dirtymake lint baseorigin/main——无新增 lint 错误make test——全部单元测试通过go test -race ./...或make test-with-cover——变更包无竞态make chlog-validate——用户可见变更存在.chloggen/条目绝不直接编辑CHANGELOG.md。6.4 PR 描述与推送纪律开 PR 前阅读.github/pull_request_template.md并按模板结构填写注意非交互工具用gh pr create --body显式传 body 会绕过 GitHub 模板自动填充需手动应用模板已进入评审的 PR 禁止改写历史用新提交回应评审意见不 amend/squash/rebase 已评审提交不 force push含--force-with-lease它虽防覆盖他人工作但仍会重写历史并破坏 GitHub 的 changes since your last review 视图唯一例外基于main的 rebase如解决冲突且必须单独推送、不夹带其他改动并在 PR 评论中说明。七、Agent 工作流的延伸文档写作管线AGENTS.md 指向的规范之外.agents/README.md 还描述了完整的 AI 辅助文档工作流由 Tempo 维护团队专门为文档写作编排的 agent 体系PR 驱动/docs-workflow依次执行 triage/docs-pr-check分类文档状态→ write/docs-pr-write补写缺失文档→ review/docs-review检查风格/准确性/完整性每步之间暂停等人工确认从零写作运行 .agents/doc-agents/writers/writer-agent.md以五阶段交互推进Teacher理解功能→ Information Architect规划结构→ Author起草→ Reviewer审查→ Committer准备 PR共享资源.agents/doc-agents/ 下的 docs-context-guide代码-文档映射、style-guideGrafana 风格规则、best-practices常见陷阱、verification-checklist提交前质量清单等供 agent 与人类作者共用领域知识编写 metrics-generator 文档时须加载 modules/generator/AGENTS.md 作为额外上下文覆盖功能范围、配置结构、常见困惑点与 v3 架构变化。八、结语把规范变成可自动执行的流程AGENTS.md 的价值不在于规则数量而在于它将 Tempo 仓库的工程纪律编码成了 Agent 可直接读取、直接执行的指令链changelog 用 chloggen 避免合并冲突编码与审查规范用可 grep 的命令与代码骨架消除歧义提交门槛用make目标实现可复现校验。对贡献者而言遵循这份指南意味着先跑make chlog-new与make fmt再写测试与代码最后按make lint baseorigin/mainmake testmake chlog-validate的顺序自检——这套流程既能通过 CI也能大幅缩短维护者评审往返。如果你正在用 AI 工具为 Tempo 或其他大型 Go 仓库做贡献将 AGENTS.md 及.agents/guidance/中的规范作为首轮上下文加载是让 Agent 产出符合上游标准的最高效路径。【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Grafana Tempo 的 Agent 协作开发规范：AGENTS.md 全解析与贡献实战指南
Grafana Tempo 的 Agent 协作开发规范AGENTS.md 全解析与贡献实战指南【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempoGrafana Tempo 是一个面向高吞吐、低依赖场景的分布式链路追踪后端其代码仓库根目录下的 AGENTS.md 是一份面向 AI AgentCursor、Claude Code、Copilot 等与人类开发者的统一协作指南。它定义了 Changelog 管理、编码规范、代码审查、文档写作和提交前检查五大约束。本文以该文件为核心骨架结合.agents/guidance/下的详细规范、Makefile 中的命令体系以及 .chloggen/ 的变更条目机制逐层拆解 Tempo 仓库对代码贡献的硬性要求帮助你或你的 Agent在提交 PR 前一次通过评审。一、AGENTS.md 在仓库中的定位AGENTS.md 位于仓库根目录是 Tempo 面向 AI 编程工具与人工贡献者的第一入口。它本身只有五个小节、二十余行但每一条都是一份更详细规范的入口指针小节职责指向的详细规范Changelog Entries管理用户可见变更的 changelog 条目.chloggen/README.mdCoding Standards编写/修改 Go 代码前的编码标准.agents/guidance/coding.mdCode Review Standards进行代码审查时的多领域审查框架.agents/guidance/code-review.mdWriting Standards撰写 Markdown 文案时的写作标准.agents/guidance/writing.mdPre-Commit Checklist推送或开 PR 前的自检清单.agents/guidance/precommit.md从设计意图看Tempo 将规则与入口分离AGENTS.md 保持极简保证任何 Agent 在打开仓库时能快速定位应遵守的规范详细内容下沉到.agents/guidance/避免根文档臃肿。这种模式本身即是值得借鉴的仓库治理实践。二、Changelog Entries用 chloggen 替代直接编辑 CHANGELOG.mdAGENTS.md 的第一条硬性规则是永远不要直接编辑CHANGELOG.md。每个用户可见的变更都必须在 .chloggen/ 下新增一个 YAML 条目。2.1 为什么禁止直接编辑Tempo 使用仓库内置的 chloggen 工具管理变更日志。直接在共享的CHANGELOG.md上并发编辑必然产生合并冲突改为每个 PR 携带独立的小 YAML 文件后冲突被彻底消除发布时再由工具统一汇总collate进 changelog。这正是 .chloggen/README.md 中说明的机制。2.2 创建与校验命令从 Makefile 可以看到 chloggen 从 tools 子模块构建并以仓库根目录为工作目录运行make chlog-new # 生成 .chloggen/当前分支名.yaml基于 TEMPLATE.yaml make chlog-new FILENAMEmy-change # 显式指定条目文件名main/master 或 detached HEAD 下必须指定 make chlog-validate # 校验所有待发布条目 make chlog-preview # 将待发布条目渲染到标准输出预览发布仅维护者时执行make chlog-update VERSIONv2.11.0 # 汇总条目写入 CHANGELOG.md 并删除条目文件2.3 条目文件的结构生成的条目基于 TEMPLATE.yaml模板文件本身在.chloggen/目录中填写示例change_type: enhancement # breaking | change | feature | enhancement | bug_fix | security component: metrics-generator # 必须在 config.yaml 的 components 允许清单内 note: A brief description of the change. issues: [] # 可选留空则发布时自动从提交信息解析 PR 号 subtext: # 可选补充细节 user: your-github-handle # 渲染为 (your-github-handle)各change_type关键字在 changelog 中对应不同分区breaking→、change→、feature→、enhancement→、bug_fix→、security→。component必须落在 .chloggen/config.yaml 的允许清单内否则chlog-validate直接拒绝新增组件需在同一次 PR 中同步修改该清单。2.4 写 note 的核心原则保持简短最多一两句话聚焦用户影响描述用户得到了什么而非技术上做了什么例如✅Improve read performance by pushing down predicates to the parquet iterators.❌Add support for pushdown predicates in the parquet iterators.确需补充的实现细节放在subtext不放 note。这一条规则直接呼应了 docs 侧对 changelog 质量的长期要求变更日志是面向运维与终端用户的不是内部实现的流水账。三、Coding StandardsGo 编码规范的五个层次.agents/guidance/coding.md 从核心哲学、测试、错误处理、并发、资源管理、惯用模式、性能到 Tempo 特有约定系统定义了 Go 代码的书写底线。3.1 核心哲学与测试写干净、朴素、惯用的 Go标准库优先显式优于隐式测试先行是默认路径先写测试 → 验证其失败证明测试确实有效→ 写最小实现使其通过 → 重构测试结构采用 table-driven subtests 模式规范中给出了TestSomething的完整骨架示例覆盖率目标作为指导而非硬性规则关键路径 80%、业务逻辑 75%、整体 70%任何新/变更行为都必须覆盖 happy path、错误路径与边界nil、空、零值。3.2 错误处理一律用fmt.Errorf(...: %w, err)包装错误以保留上下文禁止直接返回裸错误绝不静默吞错_ someFunc()属于反面示例比较错误用errors.Is/errors.As禁止err ErrNotFound包装后会失效生产服务与库代码中禁止 panic初始化失败应向上返回错误并交给main退出。3.3 并发与资源管理goroutine 必须有明确生命周期优先响应ctx.Done()取消信号用 channel 做编排/信号用 mutex 保护共享状态共享计数器等给出SafeCounter式的显式加锁示例必须跑go test -race发现竞态即修复而非抑制context 必须是函数第一个参数并贯穿所有 goroutine资源获取后立即defer清理文件、HTTP body、数据库行、锁、连接。3.4 性能先测量再优化性能优化必须 profile 先行go test -cpuprofilecpu.out -memprofilemem.out -bench. ./...与go test -bench. -benchmem ./...是标准工具热路径上 3 倍慢的实现若能换来清晰度可以接受——上下文比基准数字更重要分配模式已知大小预分配make([]T, 0, n)、紧循环中复用 buffer、短生命周期高频对象用sync.Pool、循环拼接字符串用strings.Builder算法上优先 O(n log n)对 Parquet 迭代器使用SeekTo()跳过已扫描的 row group。规范中还给出了 Tempo 的已知热路径清单这些位置改动必须有基准数据支撑路径文件基准佐证Span 摄取instance.push()modules/ingester/instance.goBenchmarkInstancePush、BenchmarkInstanceContentionLive trace 追加liveTrace.Push()modules/ingester/trace.go每 span 在 mutex 下调用TraceQL 二元运算pkg/traceql/ast_execute.goBenchmarkBinOpParquet 行号比较pkg/parquetquery/iters.goBenchmarkEqualRowNumberParquet TraceQL 块执行tempodb/encoding/vparquet5/block_traceql.go4 个以上关系运算符基准字符串驻留interningpkg/parquetquery/intern/intern.go对重复值使用 unsafe3.5 Tempo 特有约定从代码库中沉淀的惯例配置校验返回(warnings []error, err error)warnings 非致命降级运行err 致命——参考 modules/overrides 及 config 校验相关实现让运维在部分配置缺失时仍能启动复杂构造函数用类型化 option 接口而非裸func(*T)option 自描述且可携带状态租户行为必须透传通过 handler 链传递overrides.Interface始终从 context 提取 tenant ID绝不硬编码租户级行为泛型用于类型安全队列/容器如PriorityQueue[T Op]消除运行时类型断言队列组件内嵌 Prometheus gauge并为测试场景做 nil 保护mock 用_占位未用参数、//nolint:all抑制 stub 的 lint、线程安全计数器做断言同一初始化逻辑重复 3 次以上提取为局部闭包新增查询路径保持向后兼容旧路径保留新路径由 hint/flag 门控引擎选择走哪条路调用方不变配置默认值与破坏性变更在CHANGELOG.md与变更点代码注释中同步说明移除配置字段时留下替代说明如QueryIngestersUntil在 v2.7 移除改用QueryBackendAfter。四、Code Review Standards十遍通过的审查框架.agents/guidance/code-review.md 定义了多领域审查框架要求按 pass 系统推进并为每个发现记录what、why、wherefile:line、severity 和具体修复方案。4.1 严重级别与路由CRITICAL可利用漏洞、数据丢失、崩溃注入、认证绕过、热路径 nil 解引用、硬编码凭据HIGH严重 bug、破坏性行为、安全弱点关键路径缺错误处理、竞态、资源/goroutine 泄漏、弱加密、破坏性 API 变更MEDIUM质量问题、潜在 bug、非惯用代码缺校验、N1 查询、缺缓存LOW风格、小改进、文档注释错别字、命名建议。路由规则任何 CRITICAL/HIGH 必须修复后才能合并并考虑重审设计仅 MEDIUM/LOW 则定点修复、不阻塞。4.2 十个审查 PassSecurityOWASP Top 10、硬编码凭据、注入特别强调——配置结构中任何命名含password/token/key/secret/credential/auth的字段必须使用flagext.Secret或config.Secret来自github.com/prometheus/common/config确保日志与序列化输出中被脱敏并给出 grep 排查命令集os/exec、弱密码学crypto/md5/crypto/sha1、math/rand用于安全目的等Bug Diagnosisnil 解引用、数据竞态、off-by-one、资源未关闭、未检查的类型断言Error Handling忽略错误、静默吞错、缺少%w包装上下文、panic 代替错误返回Code Quality Logic逻辑错误、边界缺失、跨文件一致性、死代码、测试覆盖缺口PerformanceO(n²) 算法、紧循环内分配、热路径回归必须有基准佐证已知热路径同 coding.md 清单Go Idiomsstuttering 命名、接口过大、无生命周期 goroutine、比较错误、循环内 defer、init()滥用Architecture Design紧耦合、缺抽象、违反单一职责、循环依赖、阻碍可测试性的全局状态Documentation示例无法编译或与 API 不符、导出符号缺注释、README 命令失效Comment Accuracy过期/误导性注释、错误的参数/返回值描述、未解决的 TODO/FIXME给出git diff HEAD --name-only | xargs grep -n TODO\|FIXME\|HACK\|XXX排查命令Reference Integrity注释中引用的 spec/设计文档必须真实存在、且代码与所引章节描述一致。输出格式要求按Critical Issues (Must Fix)→High Priority Issues→Medium Priority Issues→Low Priority Issues→Summary含各级数量与 MUST FIX / TARGETED FIXES / READY 结论组织。4.3 Tempo 维护者的实战审查标准测试特异性锁定完整行为契约而非松散断言如用assert.Equal(t, GET /api/users/_, result)而非assert.Contains(t, result, _)并发假设必须显式跨 goroutine 共享的切片/指针要注明是否安全必要时解释拷贝原因性能声明需要生产证据仅微基准不足以定论须用真实/仿真集群 profile 佐证引述维护者原话SortTrace is not present in CPU profiles at all... 0.02% of CPU异步行为必须文档化Tempo 在 live-store、block-builders 等多处异步执行限额代码注释与文档都必须明确说明最小化导出默认不导出仅在测试中使用的保持在测试文件内且不导出进程内调用不过度设计monolith 场景直接函数调用即可避免 gRPC/channel/worker pool命名必须精确一个canonical命名的争议最终被解析为NormalizeQuery——名字应传达无歧义的意图。五、Writing StandardsMarkdown 语义化换行SemBr.agents/guidance/writing.md 要求所有文档、README、设计文档与 Agent 指南采用Semantic Line BreaksSemBr写作在语义边界换行而不是固定列宽硬折或整段一行。Tempo 仓库的 docs/ 与各模块 AGENTS.md 普遍遵循这一约定。原因diff 只显示真正变更的句子/子句审查者可针对单句评论LLM 辅助写作倾向产出长而密的段落SemBr 让这类编辑保持可审工具官方 SemBr 技能位于 .agents/doc-agents/ 工作流体系内skill 定义在.claude/skills/sembr-reformat/SKILL.md源自 MIT 许可的 sembr/skills 项目范围只对新增文案与正在编辑的段落应用不批量重排未触及文件避免 diff 噪音代码块、表格、YAML frontmatter 及换行有语法意义的标记一律保留原样。六、Pre-Commit Checklist推送前的五道关卡.agents/guidance/precommit.md 定义了开 PR 前的最低门槛对应命令均可从 Makefile 找到实现。6.1 格式化与 Lintmake fmt # gofumpt goimportsCI 跑 make check-fmt工作树不干净即失败 make lint # golangci-lint make lint baseorigin/main # 仅检查相对 base 分支的 diff与 CI 行为一致大仓库推荐6.2 单元测试与 E2emake test # 全包测试 make test-with-cover # 带 race detector 与覆盖率匹配 CI 拆分 make test-with-cover-pkg # CI 将测试拆为 pkg / tempodb / tempodb-wal / others 四组 make test-with-cover-tempodb make test-with-cover-tempodb-wal make test-with-cover-others make test-e2e # 全套 E2e需 Docker先构建本地 Tempo 镜像 make test-e2e-api # 也可单独跑各套件 make test-e2e-operations make test-e2e-limits make test-e2e-metrics-generator make test-e2e-storage make test-e2e-clean # 跑完后清理 Docker 拥有的测试目录6.3 开 PR 前的最低门槛make fmt——工作树无 dirtymake lint baseorigin/main——无新增 lint 错误make test——全部单元测试通过go test -race ./...或make test-with-cover——变更包无竞态make chlog-validate——用户可见变更存在.chloggen/条目绝不直接编辑CHANGELOG.md。6.4 PR 描述与推送纪律开 PR 前阅读.github/pull_request_template.md并按模板结构填写注意非交互工具用gh pr create --body显式传 body 会绕过 GitHub 模板自动填充需手动应用模板已进入评审的 PR 禁止改写历史用新提交回应评审意见不 amend/squash/rebase 已评审提交不 force push含--force-with-lease它虽防覆盖他人工作但仍会重写历史并破坏 GitHub 的 changes since your last review 视图唯一例外基于main的 rebase如解决冲突且必须单独推送、不夹带其他改动并在 PR 评论中说明。七、Agent 工作流的延伸文档写作管线AGENTS.md 指向的规范之外.agents/README.md 还描述了完整的 AI 辅助文档工作流由 Tempo 维护团队专门为文档写作编排的 agent 体系PR 驱动/docs-workflow依次执行 triage/docs-pr-check分类文档状态→ write/docs-pr-write补写缺失文档→ review/docs-review检查风格/准确性/完整性每步之间暂停等人工确认从零写作运行 .agents/doc-agents/writers/writer-agent.md以五阶段交互推进Teacher理解功能→ Information Architect规划结构→ Author起草→ Reviewer审查→ Committer准备 PR共享资源.agents/doc-agents/ 下的 docs-context-guide代码-文档映射、style-guideGrafana 风格规则、best-practices常见陷阱、verification-checklist提交前质量清单等供 agent 与人类作者共用领域知识编写 metrics-generator 文档时须加载 modules/generator/AGENTS.md 作为额外上下文覆盖功能范围、配置结构、常见困惑点与 v3 架构变化。八、结语把规范变成可自动执行的流程AGENTS.md 的价值不在于规则数量而在于它将 Tempo 仓库的工程纪律编码成了 Agent 可直接读取、直接执行的指令链changelog 用 chloggen 避免合并冲突编码与审查规范用可 grep 的命令与代码骨架消除歧义提交门槛用make目标实现可复现校验。对贡献者而言遵循这份指南意味着先跑make chlog-new与make fmt再写测试与代码最后按make lint baseorigin/mainmake testmake chlog-validate的顺序自检——这套流程既能通过 CI也能大幅缩短维护者评审往返。如果你正在用 AI 工具为 Tempo 或其他大型 Go 仓库做贡献将 AGENTS.md 及.agents/guidance/中的规范作为首轮上下文加载是让 Agent 产出符合上游标准的最高效路径。【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考