docs: 新增 AGENTS.md（仓库定位 + 四语言日志/指标接入指引，跨 agent 通用） - #6
Conversation
Welcome To opensourceways CommunityHey @TangJia025 , thanks for your contribution to the community. Bot Usage ManualI'm the Bot here serving you. You can find the instructions on how to interact with me at Here . That means you can comment below every pull request or issue to trigger Bot Commands. Contact GuideIf you have any questions, please contact the SIG: infratructure , |
CLA Signature PassTangJia025, thanks for your pull request. All authors of the commits have signed the CLA. 👍 |
Linking Issue Notice@TangJia025 , the pull request must be linked to at least one issue. |
CLA Signature PassTangJia025, thanks for your pull request. All authors of the commits have signed the CLA. 👍 |
1 similar comment
CLA Signature PassTangJia025, thanks for your pull request. All authors of the commits have signed the CLA. 👍 |
TangJia025
changed the title
CLA Signature PassTangJia025, thanks for your pull request. All authors of the commits have signed the CLA. 👍 |
1 similar comment
CLA Signature PassTangJia025, thanks for your pull request. All authors of the commits have signed the CLA. 👍 |
给 Claude Code 在仓库内的作业指引，也是新人接手的速览： - 铁律：spec/ 是唯一事实来源、薄封装不自研 instrumentation、首期只做 log+metrics（trace_id/span_id 仅预留）、契约改动四语言同步、日志只支持 kv 传参禁止 printf、高基数值禁做 metrics label、community 只在可信判定点解析。 - 契约速查：字段顺序、time 固定毫秒 UTC、level 小写、logger/error 语义、 community 双层注入与取值来源。 - 四语言各自的「加日志 / 加指标」代码块（Init + 打点 + 中间件 + 请求级覆盖）， 签名均按各语言实际源码核对。 - 写明 Java 日志必须用 examples/logback-json.xml 的 ObsJsonProvider 及原因， 避免后人退回 encoder 自带 provider（会丢 throwable、字段名/级别不符）。 - 构建测试命令与 CI 工具链版本（Go 取 go.mod、Python 3.10、Node 20、Java 17）； 不含任何本机绝对路径，便于团队共享。 注意：文中 kv-only 日志与 Java ObsJsonProvider 描述的是 PR #4 合入后的状态。 Co-Authored-By: Claude Code <noreply@anthropic.com>
原写「Go 取 go/go.mod 的版本（1.22）」，但 #3 已把 go.mod 升到 1.25.0， 括号里的数字当场过期。改为只说明来源（CI 用 go-version-file 读 go.mod）， 避免每次升 Go 都要回来改文档。 Co-Authored-By: Claude Code <noreply@anthropic.com>
AGENTS.md 是跨工具约定（opencode / Codex / Cursor 等均读它），open 且不绑定厂商； opencode 官方规则文档明确：同目录下 AGENTS.md 与 CLAUDE.md 并存时只读 AGENTS.md。 故把内容迁到 AGENTS.md（git mv 保留历史），措辞改为「AI coding agent 通用指引」。 Claude Code 不原生读 AGENTS.md（官方 memory 文档：Claude Code reads CLAUDE.md, not AGENTS.md，原生支持仍是 open feature request），官方给的兼容方式是 @AGENTS.md 导入或符号链接。这里用导入 —— 符号链接在 Windows 需管理员/开发者模式，本仓库贡献者 可能用 Windows，导入没有这个约束。 CLAUDE.md 因此退化为 4 行导入壳，正文只在 AGENTS.md 一处维护，不会两处漂移。 同时按反馈去掉「子任务 #2061」引用，只保留需求 #1938。 Co-Authored-By: Claude Code <noreply@anthropic.com>
前一个 commit 按反馈去掉了子任务引用，经确认应保留，恢复为与 README.md / spec/README.md 一致的写法：需求 #1938 + 子任务 #2061。 Co-Authored-By: Claude Code <noreply@anthropic.com>
原文写的 `go-v1.0.0` 前缀形式 Go 工具链不认：模块根在 go/ 子目录时， tag 必须是 `go/v1.0.0`（`<子目录>/v<版本>`），否则 `go get` 拉不到该模块。 AGENTS.md 与 README.md 同步更正。 Co-Authored-By: Claude Code <noreply@anthropic.com>
1. 「community 双层注入」此前只写了「Init 配置或 OBS_* 环境变量」两级来源， 漏了内置默认，也没写默认值 —— 与 spec/common-fields.md「静态字段来源与默认值」 的三级解析不一致。这一句缺失有实际代价：Java SDK 的部署级字段正是因为少了一级 兜底，取值落成 null，被日志 provider 当作空值省略，导致 service/env/instance/ community 四个字段整条从 JSON 里消失、指标 label 被整段跳过，采集侧静默漏数。 补上三级来源、各语言的唯一实现位置（改兜底规则要四处同步）以及这条后果。 2. 更正 Java 片段里 `fromEnvironment()` 的注释：它也走三级解析，OBS_* 未设置时 回退内置默认，不是「只读环境变量」。 3. 补指向 docs/ 两份文档的入口：设计文档与进度追踪文档此前没有任何指引文件提及。
e0f9fc2 to
0a8f80d
Compare
CLA Signature PassTangJia025, thanks for your pull request. All authors of the commits have signed the CLA. 👍 |
2 participants
新增根目录
AGENTS.md：既是 AI coding agent 在本仓库的作业指引，也是新人接手的速览。为什么用 AGENTS.md 而不是 CLAUDE.md
指引内容与工具无关，不该绑定单一 agent。
AGENTS.md是跨工具约定 —— opencode / Codex / Cursor 等都读它。opencode 官方规则文档明确：同目录下AGENTS.md与CLAUDE.md并存时只读AGENTS.md。AGENTS.md（官方 memory 文档："Claude Code readsCLAUDE.md, notAGENTS.md"，原生支持目前仍是 open feature request）。官方给的兼容方式有两种：@AGENTS.md导入，或符号链接。因此
CLAUDE.md退化为 5 行导入壳，正文只在AGENTS.md一处维护，不会两处漂移。内容
仓库定位 — 可观测薄封装 SDK monorepo（log + metrics，不自研 instrumentation），格式由
spec/契约层统一约束。铁律（7 条） — spec 是唯一事实来源 / 薄封装 / 首期只做 log+metrics（
trace_id/span_id仅预留）/ 契约改动四语言同步 / 日志只支持 kv 传参禁止 printf / 高基数值禁做 metrics label /community只在可信判定点解析。每条都附了「为什么」，避免后人当成教条绕过。契约速查 — 字段顺序、
time固定毫秒 UTC（Z，非+00:00、非纳秒）、level小写、logger/error语义、community双层注入与取值来源（infrastructure仓service.yaml）。四语言「加日志 / 加指标」代码块 — Init + 打点 + 中间件 + 请求级覆盖，覆盖 Go（含 gin 变体）、Python（含 FastAPI/Flask/Django 适配）、Node、Java。所有签名按各语言源码逐个核对，非凭印象。
Java 专属提醒 — 日志必须用
examples/logback-json.xml的ObsJsonProvider，并写明为什么不能退回 encoder 自带 provider（<logLevel/>只能大写、字段名不可配、不配<stackTrace/>会整条丢弃 throwable）。这是 #4 踩过的坑，写进指引以防回归。构建测试 — 四语言命令 + CI 工具链版本。Go 的版本不硬编码，只写「以
go/go.mod为准」（CI 用go-version-file读它），避免每次升 Go 都要回来改文档。不含任何本机绝对路径，便于团队共享。说明
docs/2061-claude-md是创建时的旧名，未随文件重命名调整（改名会牵动 PR 引用），以 PR 标题与内容为准。🤖 Generated with Claude Code
AI 使用声明
当前 PR 是否有 AI 参与：