尧图网络 高端网站定制 · 原创设计
免费咨询热线
400-888-6620
免费获取方案
CLAUDE.md 与 AGENTS.md 实战指南:一套模板同时喂饱 Claude Code 与 Codex,TaoToken 统一 Key 接入
1. Monorepo 里两套 AI 规则文件的真实困境如果你正在一个 Monorepo 里同时用 Claude Code 和 Codex 写代码大概率遇到过这种场面在apps/web目录里让 Claude Code 改一个 React 组件它老老实实按命名导出写切到 Codex 让它改同一个文件它给你加了个export default。你回头翻规则文件发现CLAUDE.md里写了「禁止 default export」但AGENTS.md里压根没提这回事——因为当初只维护了一份另一份是复制粘贴后忘了同步。CLAUDE.md 是 Claude Code 的原生记忆文件AGENTS.md 是 Codex、Cursor、Copilot 等工具共同遵守的开放标准。两者要传达的信息 95% 相同都是命令、约定、边界但加载机制和封装方式完全不同。Monorepo 场景把这个矛盾放大了根目录一份全局规则子目录各自有增量规则两个工具各读各的维护成本直接翻倍。这篇要解决的就是这件事用一套模板同时喂饱 Claude Code 与 Codex再通过 TaoToken 统一 Key 接入两端做到一次维护、两端生效。适合正在把 AI 编码助手引入团队工程流程、且仓库结构不止一个包的开发者。下面从目录分层和内容骨架开始给出可复制的配置片段和逐条验证动作。2. 前置TaoToken 统一 Key 与两端接入准备在写规则文件之前先把两端的 API 通道统一掉。Claude Code 和 Codex 默认走各自的官方端点团队里每个人配一遍 Key 既麻烦又容易泄露。TaoToken 提供统一的 API 通道一个 Key 同时给 Claude Code 和 Codex 用规则文件里也不用再写两套环境变量说明。你需要先拿到一个 API Key。打开 https://taotoken.net/api-keys 创建复制出来存好后面两端配置都要用。注意这个 Key 只显示一次丢了就重新生成。TaoToken 的 API 端点是https://taotoken.net/api兼容 Anthropic 和 OpenAI 两种协议格式。Claude Code 走 Anthropic 协议Codex 走 OpenAI 协议同一个 Key 两边都能认证。模型对话可以在 https://taotoken.net/models 里先试一下确认 Key 有效再往下配。这里有个容易踩的坑不要把 Key 直接写进CLAUDE.md或AGENTS.md。规则文件是提交进 Git 的Key 写进去等于公开。正确做法是写进本地环境变量或.env.local规则文件里只写「Key 从环境变量读取」这一条约定。3. 可复制配置目录分层与内容骨架3.1 Monorepo 三层目录结构先定目录。Monorepo 最怕一个 2000 行的根文件把所有上下文灌给 Agent正确姿势是三层repo-root/ ├── AGENTS.md # 第一层全局规则仓库结构、通用命令、提交规范 ├── CLAUDE.md # 桥接文件AGENTS.md Claude 专属补充 ├── apps/ │ └── web/ │ └── AGENTS.md # 第二层前端专属规则 └── services/ └── order/ └── AGENTS.md # 第二层订单服务专属规则为什么这样可行两个工具的机制刚好都支持。Codex 从 Git 根目录向当前工作目录逐层合并AGENTS.md离代码最近的文件优先每个目录至多取一个文件AGENTS.override.md优先于AGENTS.md。Claude Code 根目录CLAUDE.md全量加载子目录的CLAUDE.md只在 Agent 读取该目录文件时才按需进入上下文子项目规则不会污染无关任务。子目录文件里只写「与根规则不同或新增」的内容。全局规则比如提交格式、安全底线留在根文件不要重复。3.2 根 AGENTS.md 骨架这是任何项目的起点六个小节是社区事实标准# AGENTS.md ## 项目概述 Node.js 20 TypeScript 5 的计费平台 Monorepo包管理器 pnpm 9。 服务在 /services共享库在 /packages。 ## 常用命令 - 安装依赖pnpm install - 启动开发服务pnpm dev - 全量测试pnpm test - 单个测试pnpm vitest run -t test name - Lintpnpm lint构建pnpm build ## 代码规范 - TypeScript strict 模式禁止 any - 仅命名导出不使用 default export - 新增功能优先函数式写法不新增 class ## 测试约定 - 不 mock 数据库使用测试库测试数据用工厂函数构造 - 提交前 pnpm lint pnpm test 必须全部通过 ## 安全红线 - 禁止提交 .env 及 /secrets 目录 - 支付相关代码/services/billing的改动必须在 PR 中标记人工评审 ## 提交与 PR - 分支命名feat/模块-描述、fix/模块-描述 - Commit 遵循 Conventional Commitsfeat: / fix: / chore: / docs: / refactor: - PR 标题格式[服务名] 描述填写的唯一标准是删掉某一条Agent 会不会因此犯错不会就删。3.3 桥接文件 CLAUDE.mdClaude Code 不会自动读取AGENTS.mdCodex 默认也不读CLAUDE.md。双工具团队必须做桥接。推荐方案是AGENTS.md为唯一权威内容源CLAUDE.md做一行导入加 Claude 专属补充# CLAUDE.md AGENTS.md ## Claude 专属补充 - 本仓库使用 .claude/rules/*.md 做按路径触发的规则详见各文件头部 frontmatter - 子目录 CLAUDE.md 按需加载不要把所有规则堆在根文件AGENTS.md是 Claude Code 的导入语法递归导入最多 4 层。这样跨平台零成本Git 友好团队无需任何配置。3.4 子目录增量规则示例apps/web/AGENTS.md只写前端增量# AGENTS.mdapps/web ## 前端专属规范 - 组件一律命名导出仅路由懒加载的页面组件允许 default export - 样式只用 Tailwind 工具类禁止新增 .css 文件 - 数据请求必须经过 src/lib/api.ts 的封装禁止在组件内直接调用 fetch / axios - 环境变量必须以 VITE_ 前缀定义和读取 ## 测试约定 - 测试文件就近放在模块内 __tests__/ 目录命名 *.test.tsx - 网络请求用 MSW 拦截禁止 mock 业务模块services/order/AGENTS.md只写后端增量# AGENTS.mdservices/order ## 分层约定 - controller → service → repository 严格单向依赖 - Transactional 只允许出现在 service 层只读查询标注 Transactional(readOnly true) - 业务异常统一抛 BusinessException(code, message)禁止在业务代码里 try/catch 后吞掉异常 ## 数据库变更纪律 - 只能新增 Flyway 迁移文件V{n}__{desc}.sql禁止修改已合并的迁移 - 迁移必须与实体变更在同一个 PR 中提交4. 验证请求两端接入与成功结果规则文件写好后先验证两端都能读到、都能按规则干活。4.1 Claude Code 接入 TaoTokenClaude Code 通过环境变量读取 API 端点和 Key。在 shell 配置里加export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的 TaoToken Key然后进入仓库根目录启动 Claude Codeclaude在对话里输入/memoryClaude Code 会列出当前加载的所有记忆文件。你应该能看到根目录CLAUDE.md和它导入的AGENTS.md。如果只看到CLAUDE.md没看到AGENTS.md的内容检查AGENTS.md那行有没有写错路径。接着让它读一个子目录文件比如「看一下 apps/web/src/lib/api.ts」再输入/memory应该能看到apps/web/AGENTS.md被按需加载进来了。4.2 Codex 接入 TaoTokenCodex 走 OpenAI 协议配置在~/.codex/config.tomlmodel_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api/v1 env_key TAOTOKEN_API_KEY [model_providers.taotoken] wire_api chat环境变量里设置export TAOTOKEN_API_KEY你的 TaoToken Key进入仓库根目录启动 Codex让它读根目录文件codex 读一下 AGENTS.md告诉我这个仓库用什么包管理器如果它回答 pnpm 9说明根AGENTS.md加载成功。再让它读子目录codex 看一下 apps/web 下的组件导出规范它应该能引用apps/web/AGENTS.md里的「命名导出」规则。4.3 成功结果对照两端都配好后做一次交叉验证在apps/web目录里让 Claude Code 和 Codex 各生成一个组件检查是否都用了命名导出、都走了src/lib/api.ts封装。如果两边行为一致说明规则文件生效了。长期编码和 Agent 任务建议用 Coding Plan额度更稳适合团队日常跑https://taotoken.net/coding-plan5. 本篇常见错排查5.1 Claude Code 读不到 AGENTS.md最常见的原因是CLAUDE.md里AGENTS.md路径写错。导入路径是相对于CLAUDE.md所在目录的如果CLAUDE.md在根目录AGENTS.md就指向根目录的AGENTS.md。如果放在.claude/CLAUDE.md要写成../AGENTS.md。另一个原因是文件名大小写。必须是全大写AGENTS.md不是agents.md。Linux 和 macOS 默认文件系统大小写敏感写错了不报错但读不到。5.2 Codex 只读了根文件没读子目录Codex 从 Git 根目录向当前工作目录逐层合并如果你启动 Codex 时不在子目录里它不会主动加载子目录的AGENTS.md。要么cd到子目录再启动要么在对话里明确让它读某个子目录的文件触发按需加载。还有一种情况子目录里同时有AGENTS.override.md和AGENTS.mdCodex 只取 override 那个。检查一下是不是有遗留的 override 文件把正常规则盖掉了。5.3 两端行为不一致如果 Claude Code 遵守了某条规则但 Codex 没遵守先确认这条规则写在哪个文件里。写在CLAUDE.md里的 Claude 专属补充Codex 读不到写在AGENTS.md里的共享规则两端都应该读到。共享规则一律放AGENTS.mdClaude 专属的才放CLAUDE.md。5.4 Key 认证失败TaoToken 的 Anthropic 协议端点是https://taotoken.net/apiOpenAI 协议端点是https://taotoken.net/api/v1两个不一样。Claude Code 用前者Codex 用后者。写反了会报 404 或认证失败。Key 本身在 https://taotoken.net/api-keys 管理确认没有过期或删掉。5.5 规则文件太长导致 Agent 不遵守CLAUDE.md建议控制在 200 行以内AGENTS.md根文件保持精简。文件越长单条指令被遵循的概率越低。详细文档用导入或拆分子目录文件解决不要把架构设计文档整段贴进规则文件。6. 持续维护与接入入口规则文件写完不是终点。每次纠正 Agent 之后把教训写回文件这是投资回报率最高的习惯。纠正一次是消耗写回文件就变成了团队资产。CI 里可以加一个新鲜度检查校验文件里引用的路径和脚本仍然存在防止路径重命名后规则失效。接入文档和完整参数说明在 https://taotoken.net/doc模型对话调试在 https://taotoken.net/modelsAPI Key 管理在 https://taotoken.net/api-keys。Claude Code 的 Anthropic 协议接入细节可以参考 https://taotoken.net/claude-code-anthropic。从根AGENTS.md骨架开始挑一个子目录模板填进去在下一个真实任务里跑一遍然后把 Agent 犯的每个错变成文件里的一条新规则。几周之后你会得到一份比任何新人文档都值钱的东西。
RELATED

相关推荐

OpenClaw 实战:一个人如何搭建并指挥一个 AI 虚拟开发团队(保姆级教程)

OpenClaw 实战:一个人如何搭建并指挥一个 AI 虚拟开发团队(保姆级教程)

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

📅 2026/9/27 15:59:52
掌握 AI Agent Harness:用 TaoToken 统一 Key 让大模型可控可信赖,小白程序员必备收藏!

掌握 AI Agent Harness:用 TaoToken 统一 Key 让大模型可控可信赖,小白程序员必备收藏!

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

📅 2026/9/27 15:59:52
Sverklo 代码记忆的证据链验收:TaoToken 统一 Key 下 grep 与向量搜索的配置骨架

Sverklo 代码记忆的证据链验收:TaoToken 统一 Key 下 grep 与向量搜索的配置骨架

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

📅 2026/9/27 15:59:52
MORE NEWS

更多资讯

📰

手把手教你用 Docker Compose 部署 Hermes Agent:TaoToken 统一 Key 接入 Telegram 完整指南

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

📰

5 分钟完成 OpenClaw 2.7.9 部署:Windows 11/macOS 自动化工具落地教程(TaoToken 配置版)

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

📰

3步搞定wordpress金属主题选型与定制,一文搞懂避坑指南

3步搞定wordpress金属主题选型与定制,一文搞懂避坑指南 网站被黑挂马不知道怎么办?别慌,这往往不是服务器问题,而是你的wordpress金属主题本身存在安全漏洞或代码臃肿。很多老板花大价钱买的“金属工业风”主题,看着炫酷,实则内藏无…

📰

搞定wordpress底部模板:3步走完整流程告别廉价感

搞定wordpress底部模板:3步走完整流程告别廉价感 还在为模板网站太丑、不够用而头疼?尤其是那个死气沉沉的底部,简直拉低了整个站点的逼格。别急着换主题,其实只要掌握一套 完整流程…

📰

接单子做网站别乱搞 图解步骤搞定备案不踩坑

接单子做网站别乱搞 图解步骤搞定备案不踩坑 很多刚入行的前端或设计朋友,第一次接单子做网站时,代码写得飞起,页面调得漂亮,结果客户一句“怎么打不开”,才发现卡在备案上。备案流程一头雾水,填表填到怀疑人生,域名解析配不对,SSL证书申请卡住,…

📰

福州网站建设哪家公司好?3个维度教你避开性能优化大坑

福州网站建设哪家公司好?3个维度教你避开性能优化大坑 自己不会代码,想做个像样的企业官网,这是很多老板的痛点。别被那些花哨的术语唬住,核心就两点:好不好看,快不快。很多甲方问我, 福州网站建设哪家公司好 ,其实答案不在广告里,而在对…

TODAY

今日更新

THIS WEEK

本周精选

THIS MONTH

本月热门

读完文章,想聊聊您的网站?

告诉我们您的行业与需求,资深顾问一对一梳理方案与报价,全程免费。

📞 💬