结论先说
- 公共约定只写一份,统一放进仓库根目录的
AGENTS.md。Cursor 和 Codex 会原生自动读取它;Claude Code(v2.1.277 及以上)在没有CLAUDE.md时也会直接回退读取AGENTS.md。 - 如果仓库必须保留
CLAUDE.md,第一行写@AGENTS.md导入。因为CLAUDE.md一旦存在,Claude Code 默认只读它而忽略同目录的AGENTS.md;用@AGENTS.md把公共规则引进来,下面只写 Claude 专属补充,就能避免两边复制粘贴。 - 不要在
.cursor/rules里把AGENTS.md再抄一遍。Cursor 已经会自动加载根目录AGENTS.md,如果又建一个alwaysApply: true的.mdc写同样内容,每次对话都会塞入双份重复上下文。 - 按目录或文件后缀触发的局部规则,拆到各自专属目录。Cursor 用
.cursor/rules/.mdc里的globs字段,Claude Code 用.claude/rules/.md里的paths字段,各管各的按需加载。 - 跨平台团队慎用
ln -s符号链接,优先用@AGENTS.md导入。Windows 默认未开core.symlinks时,Git 会把符号链接检出成只有一行路径名的纯文本文件,导致 Claude Code 读不到真实规则。 - 国内免卡开通与账号服务入口:自有账号免上号自助开通可见本站 Claude Pro 充值页 与 Claude Max 充值页;缺可用账号或遇身份核验可查看 Claude 注册说明 与 Claude KYC 认证协助。

图:本站根据 Claude Code 官方文档:How Claude remembers your project 与 Cursor 官方文档:Rules 整理的示意图
本文根据 Claude Code 官方文档《How Claude remembers your project》、Cursor 官方文档《Rules》、AGENTS.md 官网与 OpenAI Codex 官方文档整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Anthropic、Cursor 或 OpenAI 官方网站。
适用于谁
- 同一代码仓库里,团队成员分别使用 Claude Code、Cursor、Codex 等不同工具的人;
- 仓库里同时放了
CLAUDE.md、AGENTS.md和.cursor/rules,每次改一条构建命令都要改三处的人; - 用符号链接共享规则文件后,发现在 Windows 同事电脑上规则失效的人。
一、为什么不能直接复制三份文件
很多团队一开始会把同一段项目说明复制进 CLAUDE.md、AGENTS.md 和 .cursor/rules/general.mdc。用上几周后通常会遇到三个问题:
- 改漏引发指令打架:比如包管理器从
npm换成了pnpm,只改了CLAUDE.md忘了改.cursor/rules,用 Cursor 的同事提交上来一堆package-lock.json。 - 双倍消耗上下文:Cursor 同时识别
AGENTS.md和.cursor/rules。两处写一样的话,每轮对话都会重复计入上下文窗口。 - 互相屏蔽不自知:Claude Code 的回退逻辑是「没有
CLAUDE.md才读AGENTS.md」。有人运行/init生成了一个简短的CLAUDE.md后,原本写在AGENTS.md里的详细规范在 Claude Code 里就静默失效了。
单个文件里具体该写哪些条目、怎么控制篇幅,可以先看 CLAUDE.md 怎么写:最佳实践与模板 与 AGENTS.md 跨工具规范指南,本文专注解决同仓单源维护。
二、推荐目录结构:一份公共源 + 两套按需增量
把项目规则按「每次必读的全局底线」和「碰到特定目录才读的局部规范」拆成两层,仓库目录结构如下:
text
your-repo/
├── AGENTS.md # 唯一公共源:技术栈、构建测试命令、目录禁区、提交规范
├── CLAUDE.md # 首行 @AGENTS.md,下方仅放 Claude Code 专属工作流
├── .claude/
│ └── rules/
│ └── api-handlers.md # 用 paths 限定只在改 src/api/** 时载入
└── .cursor/
└── rules/
└── api-handlers.mdc # 用 globs 限定只在改 src/api/** 时载入
如果团队里的 Claude Code 没有任何专属指令,最省事的做法是直接不建 CLAUDE.md,只留根目录 AGENTS.md。这样 Claude Code、Cursor、Codex 三端都会直接读同一份 AGENTS.md,连导入语句都不用写。各工具在多文件大项目里消耗额度较快,需要补充订阅用量时,Claude Code 用户可在 Claude Code 订阅充值页 查看对应方案,配合 Codex CLI 使用的成员则可参考 ChatGPT Plus 充值说明。

图:本站根据 Claude Code 官方文档 与 AGENTS.md 官网 整理的示意图
三、分步配置做法
步骤 1:把通用约定收拢进 AGENTS.md
把换任何 AI 编程工具都成立的内容留在根目录 AGENTS.md,控制在 200 行以内:
markdown
# 项目开发约定
## 常用命令
- 安装依赖:`pnpm install`
- 类型检查:`pnpm typecheck`
- 跑单个测试:`pnpm vitest run path/to/file.test.ts`
## 目录与代码规范
- 金额字段统一用「分」为单位的整数
- 禁止手动修改 `prisma/migrations/` 与 `dist/` 目录下的生成文件
Codex 对 AGENTS.md 的拼接顺序与 32 KiB 体积上限,详见 Codex 怎么读 AGENTS.md。
步骤 2:在 CLAUDE.md 里用 @AGENTS.md 单向导入
当你需要给 Claude Code 单独补充子智能体分工、计划模式要求或其他参考文档时,新建根目录 CLAUDE.md,首行直接引用 @AGENTS.md:
markdown
@AGENTS.md
## Claude Code 专属约定
- 修改超过 3 个文件前,先列出涉及的文件路径与改动摘要,确认后再执行写入
- 接口返回码对照见 @docs/error-codes.md
按 Claude Code 官方文档,@路径 相对当前文件解析,启动会话时会把被导入文件一并拼进上下文。写完后可在终端进入 claude 会话,输入 /context 查看 Memory files 列表,确认 CLAUDE.md 和 AGENTS.md 都已加载。个人习惯(如回答语言偏好)不要写进仓库,改放用户级 ~/.claude/CLAUDE.md,详见 全局 CLAUDE.md 配置教程。
步骤 3:处理 .cursor/rules 的去重与局部规则
打开 .cursor/rules/ 目录做两件事:
- 删掉与
AGENTS.md重复的全局.mdc文件,让 Cursor 直接从根目录AGENTS.md读取项目总则; - 只保留需要
globs或description按需触发的局部规则,且文件后缀必须是.mdc(写法详见 Cursor Rules 配置与四种生效方式)。
注意两家的 @文件 语义不同:Claude Code 在 CLAUDE.md 里写 @文件 会在会话启动时直接展开全文;而 Cursor 在 .mdc 规则里写 @文件 只是告诉 Agent 路径,需要时由 Agent 调工具去读,不会自动塞进初始提示词。因此,如果某份局部规范在两个工具里都要按路径触发,可以把详细正文放在 docs/api-style.md:
.claude/rules/api.md里写paths: ["src/api/**/*.ts"],正文写@../../docs/api-style.md;.cursor/rules/api.mdc里写globs: src/api/**/*.ts与alwaysApply: false,正文写「修改接口前先阅读@docs/api-style.md并遵守其中的校验要求」。
这样详细正文仍然只维护 docs/api-style.md 一份。
四、符号链接(ln -s)能不能用、有什么坑
AGENTS.md 官网在介绍旧文件迁移时给出了 ln -s 符号链接做法,不少纯 macOS 或 Linux 团队也会运行:
bash
ln -s AGENTS.md CLAUDE.md
这种做法在类 Unix 系统上完全可行,但在混用 Windows 的团队里常出故障:
- Windows 默认把无管理员或未开启「开发者模式(Developer Mode)」下的 Git 符号链接检出成普通文本文件;
- 打开检出后的
CLAUDE.md,里面只有AGENTS.md这 9 个字符(前面没有@符号); - Claude Code 会把这 9 个字母当成全部指令读进去,真正的
AGENTS.md反而被忽略。
如果团队所有人都在 macOS / Linux 下开发,符号链接可以用;只要有一位成员用 Windows(非 WSL),就用第三节的 @AGENTS.md 导入代替符号链接,彻底避开 Git 检出差异。
常见问题
问:仓库子目录里再放一份 AGENTS.md,Cursor 和 Claude Code 怎么读?
Cursor 官方文档说明子目录里的 AGENTS.md 会在处理该子目录文件时自动生效,并与上级合并,越具体的越优先。Claude Code 如果根目录没有 CLAUDE.md,同样支持按子目录层级读取;若根目录用了 CLAUDE.md,子目录建议统一用 .claude/rules/ 加 paths 或在子目录 CLAUDE.md 里导入同级 @AGENTS.md。
问:旧项目根目录还有一个 .cursorrules 文件,要一起留着吗?
Cursor 官方已将旧的根目录 .cursorrules 归为旧版格式,推荐迁移到 .cursor/rules/*.mdc 或 AGENTS.md。把里面的通用条目并入 AGENTS.md 后即可删掉 .cursorrules,免得多出一份遗留规则干扰排查。
问:在 CLAUDE.md 里写 ` @AGENTS.md `(带反引号)还能导入吗?
不能。Claude Code 官方文档明确说明,包在行内代码反引号或代码块里的 @路径 会被当作普通文本展示,不会触发文件导入。写导入语句时必须裸写 @AGENTS.md。
问:人在国内没有外币信用卡,怎么订阅或升级 Claude 付费套餐?
答:可在本站 AI 会员充值总览页 选择 Claude Pro 自助充值 或 Claude Max 充值,付款后即时发卡密、24 小时自助兑换且可开具增值税发票;实时价格与售后边界(含封号不质保)以商品页当天展示为准。
相关教程
- CLAUDE.md 怎么写:最佳实践、模板与 AGENTS.md 的区别
- AGENTS.md 怎么写:规范、模板,以及各工具怎么读
- Cursor Rules 怎么写:.cursor/rules 配置、四种生效方式与最佳实践
- 全局 CLAUDE.md 怎么配:~/.claude/CLAUDE.md 与项目指令怎么分工
- Codex 怎么读 AGENTS.md:读取顺序、32 KiB 上限与不生效排查
参考资料
- Claude Code 官方文档:How Claude remembers your project — https://code.claude.com/docs/en/memory
- Cursor 官方文档:Rules — https://cursor.com/docs/rules
- AGENTS.md 官方网站 — https://agents.md/
- OpenAI Codex 官方文档:AGENTS.md — https://learn.chatgpt.com/docs/agent-configuration/agents-md
0 条评论
还没有评论,来抢沙发~