docs: 新增 AGENTS.md（仓库定位 + 四语言日志/指标接入指引，跨 agent 通用）

[TangJia025]

新增根目录 AGENTS.md：既是 AI coding agent 在本仓库的作业指引，也是新人接手的速览。

为什么用 AGENTS.md 而不是 CLAUDE.md

指引内容与工具无关，不该绑定单一 agent。

• AGENTS.md 是跨工具约定 —— opencode / Codex / Cursor 等都读它。opencode 官方规则文档明确：同目录下 AGENTS.md 与 CLAUDE.md 并存时只读 AGENTS.md。
• Claude Code 不原生读 AGENTS.md（官方 memory 文档："Claude Code reads CLAUDE.md, not AGENTS.md"，原生支持目前仍是 open feature request）。官方给的兼容方式有两种：@AGENTS.md 导入，或符号链接。
• 这里选导入：符号链接在 Windows 需要管理员/开发者模式，本仓库贡献者可能用 Windows，导入没有这个约束。

因此 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 参与：

• 否
• 是
  1. AI Agent 平台：Claude Code
  2. AI 模型：deepseek-v4-flash
  3. Prompt 上下文：用户要求「给本仓库生成 CLAUDE.md，介绍仓库功能以及各语言项目怎么用来给各自添加日志和指标上报」，随后反馈「不要限定 claude code 使用，还有 opencode 等多种 agent」、「子需求要去掉」（经确认后要求恢复）

[opensourceways-bot]

Welcome To opensourceways Community

Hey @TangJia025 , thanks for your contribution to the community.

Bot Usage Manual

I'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 Guide

If you have any questions, please contact the SIG: infratructure ,
and any of the maintainers: @GeorgeCao-hw, @TangJia025, @pkking, @zhongjun2 ,
and any of the committers: @GeorgeCao-hw, @TangJia025, @pkking, @zkhzkhz .

[opensourceways-bot]

CLA Signature Pass

TangJia025, thanks for your pull request. All authors of the commits have signed the CLA. 👍

[opensourceways-bot]

Linking Issue Notice

@TangJia025 , the pull request must be linked to at least one issue.
If an issue has already been linked, but the needs-issue label remains, you can remove the label by commenting /check-issue .

[opensourceways-bot]

CLA Signature Pass

TangJia025, thanks for your pull request. All authors of the commits have signed the CLA. 👍

[opensourceways-bot]

CLA Signature Pass

TangJia025, thanks for your pull request. All authors of the commits have signed the CLA. 👍

[opensourceways-bot]

CLA Signature Pass

TangJia025, thanks for your pull request. All authors of the commits have signed the CLA. 👍

[opensourceways-bot]

CLA Signature Pass

TangJia025, thanks for your pull request. All authors of the commits have signed the CLA. 👍