1. Monorepo 里 AGENTS.md 到底该写什么
AGENTS.md 是一份放在仓库里、给 AI 编码工具读的规则文件。它不是什么项目说明书，也不是给人看的 README，而是每次对话都会被塞进上下文的一段“系统提示”。在 Monorepo 多包仓库里，这件事会变得格外敏感：一个仓库里可能同时有apps/web、apps/api、packages/ui、packages/shared，如果根目录的 AGENTS.md 把前端、后端、组件库的规则全写在一起，AI 在改一个 React 组件时，会顺带把 NestJS 的 DTO 规范、Prisma 的迁移命令一起读进去，白白烧掉几千 token。
我试过在一个 12 个包的仓库里只放一份根 AGENTS.md，结果 ClaudeCode 每次生成前端代码都要先“消化”后端的分层规则，响应明显变慢，还偶尔把packages/ui的组件写成带@Injectable()的类。后来拆成根 + 子目录多级配置，问题才消失。
所以这篇要解决的核心问题是：在 Monorepo 场景下，AGENTS.md 应该遵循哪些原则、放在哪些目录、写多长、写什么，以及如何用 TaoToken 的统一 Key 和 API 通道，让 ClaudeCode、Cline、Codex 这些工具在多个包之间共享同一套调用配置，不用每个项目单独配一遍 Key。
适合谁看：正在维护 Monorepo、同时用两三种 AI 编码工具的团队；被“AI 读错上下文”“Key 到处散落”“换工具就要重配”折腾过的开发者。读完你能拿到一份可直接复制的 AGENTS.md 模板、目录级配置示例，以及验证 AI 是否真的读到了规则的排查步骤。
先说结论性的三条原则，后面展开：
最小化——AGENTS.md 里每个 token 每次请求都会加载，只放“AI 猜不到”的信息，比如非默认包管理器、非标准构建命令、一句话项目定位。
稳定性优先——别写死易变的文件路径，写相对稳定的“能力”和“领域概念”，文档过期对 AI 是毒药，它会自信地往错路径找。
渐进式披露——根目录只放导航和共享约定，具体包的规则下沉到子目录，AI 走到哪读到哪。
这三条不是我拍脑袋想的，是踩过坑之后总结的。下面按“问题场景 → TaoToken 前置 → 可复制配置 → 验证 → 排错 → 收尾”的顺序讲，你可以跳着看，但配置部分建议完整跟一遍。
2. TaoToken 统一 Key 的前置准备
在讲 AGENTS.md 之前，得先把“AI 工具怎么调用模型”这条链路理清楚，否则规则写得再好，工具连不上也是白搭。Monorepo 的痛点在于：一个仓库里可能同时跑 ClaudeCode 做重构、Cline 做补全、Codex 做单测生成，每个工具都要配 Base URL、API Key、Model ID。如果每个包、每个人、每台机器都各配一份，Key 管理会彻底失控。
TaoToken 在这里扮演的角色是统一入口：一个 API 通道，一个 Key，多个工具共用。官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数，配置时直接用这个。
你需要先拿到一个 Key。登录后进控制台，在 API Keys 页面创建一个，建议按“用途 + 环境”命名，比如monorepo-dev-claude、monorepo-ci-codex，方便后面按工具区分和轮换。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API Keys 页面是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
为什么强调“统一 Key”而不是每个工具一个 Key？两个原因。第一，Monorepo 里工具切换频繁，同一个开发者可能上午用 ClaudeCode 写业务、下午用 Cline 补测试，统一 Key 意味着换工具不用换凭证，配置只改 Base URL 和 Model ID。第二，排查问题时链路单一，如果请求失败，你只需要确认“Key 是否有效、Base URL 是否写对、Model ID 是否存在”这三件事，而不是在多个 Key 之间来回试。
这里要提醒一句：TaoToken 是合规的 API 聚合通道，不是让你去搞什么网络绕行。所有配置都在正常网络环境下完成，不要在任何文档或脚本里写与网络代理相关的内容，AGENTS.md 里也不要出现这类指令，否则会污染整个仓库的规则。
拿到 Key 之后，先别急着写 AGENTS.md，先用最简方式验证通道是通的。打开终端，用 curl 发一个最小请求：
curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "reply with ok"}], "max_tokens": 16 }'把$TAOTOKEN_API_KEY换成你刚创建的 Key。如果返回里有choices字段和内容，说明通道正常。这一步很重要，因为后面所有工具配置都依赖这个 Base URL 和 Key 的组合，先确认底层通，再往上叠工具，排错会简单很多。
如果你更想先在网页里试模型，可以打开模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，选一个模型发一句话，确认账号和额度没问题。这一步和 curl 二选一即可。
前置准备做完，你应该手上有三样东西：一个可用的 Key、确认过的 Base URLhttps://taotoken.net/api、以及至少一个可用的 Model ID。接下来进入 AGENTS.md 的配置环节。
3. 可复制的 AGENTS.md 与目录级配置
这一节是全文的核心，给你可以直接抄的模板。先说目录结构，假设你的 Monorepo 长这样：
repo/ ├── AGENTS.md ├── apps/ │ ├── web/ │ │ └── AGENTS.md │ └── api/ │ └── AGENTS.md ├── packages/ │ ├── ui/ │ │ └── AGENTS.md │ └── shared/ │ └── AGENTS.md ├── pnpm-workspace.yaml └── package.json根目录的 AGENTS.md 只做三件事：一句话项目定位、包管理器与构建命令、子包导航。不要写具体业务规则。模板如下：
# AGENTS.md This is a pnpm monorepo for a data dashboard product. - Package manager: pnpm (do not use npm or yarn). - Install: `pnpm install` - Build all: `pnpm -r build` - Type check: `pnpm -r typecheck` ## Workspaces - `apps/web` — Next.js frontend. See apps/web/AGENTS.md - `apps/api` — NestJS backend. See apps/api/AGENTS.md - `packages/ui` — shared React components. See packages/ui/AGENTS.md - `packages/shared` — shared types and utils. See packages/shared/AGENTS.md For TypeScript conventions, see docs/TYPESCRIPT.md For commit style, see docs/COMMITS.md注意几个细节。第一，包管理器必须写，因为 pnpm 不是默认，AI 默认会用 npm，写清楚能省掉一堆 lockfile 冲突。第二，构建命令写非标准的，pnpm -r build这种递归命令 AI 猜不到。第三，子包用“See xxx/AGENTS.md”引用，而不是把内容展开，这就是渐进式披露。第四，TypeScript 规范、提交规范这类长内容放独立文件，主文件只留一行引用。
再看子包的 AGENTS.md，以apps/api为例：
# apps/api — NestJS backend ## Structure - Controllers live in `src/modules/*/**.controller.ts` - DTOs must live in `src/modules/*/dto/`, never inside controllers. - Business logic goes in services, not controllers. ## Commands - Dev: `pnpm --filter api dev` - Test: `pnpm --filter api test` - Migration: `pnpm --filter api prisma migrate dev` ## Conventions - Use class-validator for DTO validation. - Never expose Prisma models directly from controllers.packages/ui的 AGENTS.md 则完全不同：
# packages/ui — shared React components ## Structure - One component per folder: `src/<Component>/index.tsx` - Stories live next to components: `src/<Component>/<Component>.stories.tsx` ## Commands - Build: `pnpm --filter ui build` - Storybook: `pnpm --filter ui storybook` ## Conventions - No data fetching inside components. - All props must be typed, no `any`.这样拆的好处是：当 ClaudeCode 在apps/web里工作时，它读到的是根 AGENTS.md +apps/web/AGENTS.md，不会加载apps/api的 DTO 规则。上下文干净，token 省下来给真正的任务。
接下来是工具侧的配置。ClaudeCode 默认读CLAUDE.md而不是AGENTS.md，解决办法是用软链接把两者关联，避免维护两份：
ln -s AGENTS.md CLAUDE.md cd apps/web && ln -s AGENTS.md CLAUDE.md cd ../api && ln -s AGENTS.md CLAUDE.md这样你只维护 AGENTS.md，ClaudeCode 通过 CLAUDE.md 软链接读到同一份内容。注意软链接在 Windows 上需要开发者模式或管理员权限，团队里如果有 Windows 用户，可以在文档里说明用mklink或直接复制。
然后是 ClaudeCode 的接入配置。ClaudeCode 通过环境变量或 settings 文件读取 Base URL 和 Key。推荐用项目级.claude/settings.json，路径和字段如下：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-your-taotoken-key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }三件套齐全：Base URL 是https://taotoken.net/api，Key 填你创建的，Model ID 填通道支持的模型。这个文件放在仓库根目录的.claude/下，记得加进.gitignore，不要把 Key 提交上去。团队协作时，每个人本地创建自己的 settings.json，或者用环境变量注入。
如果你用 Cline，它的配置在 VS Code 设置里，同样是三件套：API Provider 选 OpenAI Compatible，Base URL 填https://taotoken.net/api/v1，API Key 填 TaoToken Key，Model ID 填对应模型。Cline 的 MCP 配置如果需要，也走同一个 Base URL。
Codex 的配置在~/.codex/auth.json或项目级配置里，字段是：
{ "base_url": "https://taotoken.net/api", "api_key": "sk-your-taotoken-key", "model": "claude-sonnet-4-20250514" }三个工具都指向同一个 Base URL 和同一个 Key，这就是“统一 Key”的落地方式。换工具时只改工具侧的配置文件，Key 和通道不变。
最后提醒：AGENTS.md 里不要写任何与 Key、Base URL 相关的内容，那是工具配置的事，写进 AGENTS.md 只会浪费 token 且可能泄露。规则文件和凭证配置要严格分开。
4. 验证 AI 是否真的读到了规则
配置写完不代表生效，必须验证。很多人配完就直接用，结果 AI 行为不对，还以为是模型问题，其实是规则没被读到。下面给你一套可操作的验证步骤。
第一步，确认文件被工具识别。在 ClaudeCode 里输入/memory或查看启动日志，它会列出当前加载的上下文文件。你应该能看到根 AGENTS.md（通过 CLAUDE.md 软链接）和当前工作目录的子 AGENTS.md。如果只看到根文件，说明子目录的软链接没建对，或者你不在子包目录下启动。
第二步，用“探针问题”测试规则是否生效。在apps/api目录下启动 ClaudeCode，问它：“这个项目里 DTO 应该放在哪里？”如果它回答“src/modules/*/dto/，不能写在 controller 里”，说明apps/api/AGENTS.md被读到了。如果它回答“通常放在 src 下”这种泛泛的答案，说明规则没加载。
第三步，测试渐进式披露是否真的省了上下文。在apps/web目录下问：“这个仓库用什么包管理器？”它应该回答 pnpm。再问：“DTO 放哪里？”它不应该知道，因为apps/web的上下文里没有后端规则。如果它答出了 DTO 规则，说明根 AGENTS.md 里混入了后端内容，需要清理。
第四步，验证 API 通道。在 ClaudeCode 里发一个真实任务，比如“给packages/ui加一个 Button 组件的 story”，观察它是否能正常调用模型并返回结果。如果卡住或报错，进入下一节的排错。
第五步，跨工具一致性验证。用同一个 Key 在 Cline 里发一个请求，确认 Base URL 和 Model ID 配置正确。三个工具都能通，说明统一 Key 方案成立。
这里有个小技巧：在 AGENTS.md 里放一条“可验证的独特规则”，比如“所有组件文件名用 PascalCase”，然后让 AI 生成一个组件，看它是否遵守。这比问它“你读到了什么”更可靠，因为 AI 可能会“假装”读到了。
验证通过后，建议把验证步骤写进团队的 onboarding 文档，新成员配完环境后跑一遍，能省掉大量“为什么我的 AI 不听话”的沟通成本。
5. 常见报错与排查对照
配置过程中最容易撞到几类报错，这里按真实错误信息对照排查。
401 Unauthorized。返回体通常是{"error":{"message":"invalid api key"}}。原因有三种：Key 复制时带了空格或换行；Key 已被删除或过期；Authorization 头格式不对。排查：重新从 API Keys 页面复制，确认格式是Bearer sk-xxx，注意 Bearer 和 Key 之间一个空格。如果用的是 settings.json，检查 JSON 里有没有多余逗号导致解析失败。
local proxy failed / connection refused。这个报错说明工具尝试连接的地址不对。检查 Base URL 是否写成了https://taotoken.net/api，注意不要多加/v1或漏掉协议。ClaudeCode 的ANTHROPIC_BASE_URL填https://taotoken.net/api，Cline 的 OpenAI Compatible Base URL 填https://taotoken.net/api/v1，两者路径不同，别混用。
reading choices: unexpected end of JSON input。这通常是响应被截断或返回了非 JSON 内容。排查：先用 curl 直接请求确认通道返回正常 JSON；检查max_tokens是否设得太小导致响应为空；确认 Model ID 拼写正确，不存在的模型可能返回错误页而非 JSON。
OAuth / authentication failed。ClaudeCode 有时会走 OAuth 流程而不是 API Key。解决办法是在 settings.json 里显式设置ANTHROPIC_AUTH_TOKEN，并确保没有同时配置冲突的登录态。如果之前登录过官方账号，先清理~/.claude下的缓存再试。
模型不存在 / model not found。检查 Model ID 是否在 TaoToken 支持的列表里。不同通道支持的模型名可能不同，去文档页 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 确认可用模型名，不要凭记忆写。
AGENTS.md 不生效。先确认文件名大小写正确（AGENTS.md 全大写），再确认软链接是否指向正确路径。ClaudeCode 读 CLAUDE.md，如果软链接建在根目录但你在子目录启动，它可能只读子目录的 CLAUDE.md，需要在每个子包都建软链接。
子包规则互相污染。如果 AI 在apps/web里答出了后端规则，检查根 AGENTS.md 是否把子包内容展开了。根文件只应保留导航引用，具体规则下沉。
Key 泄露风险。如果.claude/settings.json被提交到 git，立刻在控制台轮换 Key，并把该文件加入.gitignore。建议用环境变量TAOTOKEN_API_KEY注入，配置文件里只写变量引用。
排查顺序建议：先 curl 确认通道，再确认工具配置三件套，再确认 AGENTS.md 加载，最后确认规则内容。从底层往上查，比一上来就改 AGENTS.md 高效得多。
6. 长期编码场景的通道选择
如果你只是偶尔用 AI 补个函数，按上面的配置就够了。但 Monorepo 团队往往是长期、高频地使用 AI 编码，这时候通道的稳定性和额度管理就变得重要。TaoToken 的 Coding Plan 适合这种场景：多个包、多个工具、多个开发者共享一套调用通道，按计划管理额度，不用每次请求都担心计费波动。入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
回到 AGENTS.md 本身，最后给你几条实战建议，都是踩过坑换来的。
规则不要无限累积。AI 每次做错就加一条禁止规则，几个月后文件会臃肿到没人敢动。建议每月 review 一次，删掉已经内化成默认行为的规则，合并重复项。
不要用脚本自动生成 AGENTS.md。自动生成的文件追求“全面”，会把大量无用信息塞进去，直接吃掉指令预算。手写、精简、只留 AI 猜不到的内容。
根目录的 AGENTS.md 控制在 30 行以内，子包的控制在 50 行以内。超过这个量级，先问自己：这条规则是不是应该放到独立文档里用引用代替？
跨工具兼容用软链接，不要维护两份。AGENTS.md 是开放格式，CLAUDE.md 是 ClaudeCode 的习惯，软链接让两者共存，改一处生效两处。
最后，把 AGENTS.md 当成代码来管理：进 git、走 review、有变更记录。它是团队和 AI 协作的接口契约，值得和源码同等对待。配置好之后，你会发现 AI 在 Monorepo 里的表现稳定很多，不再到处乱翻文件，也不再烧掉大量 token 去读无关上下文。
