同一仓库怎么同时维护 CLAUDE.md、AGENTS.md 与 .cursor/rules:单源引用不写三份重复规则的做法

团队里有人用 Claude Code、有人用 Cursor 或 Codex,同一仓库写三份规则很容易改漏和冲突。本文按官方文档整理单源维护方案:用 AGENTS.md 存公共约定、CLAUDE.md 用 @AGENTS.md 导入、按路径拆分专属规则,以及符号链接跨平台注意事项。

NNathaniel bigo··原创首发·AI 辅助撰写
14 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 免费账号 账号

结论先说

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

  1. 改漏引发指令打架:比如包管理器从 npm 换成了 pnpm,只改了 CLAUDE.md 忘了改 .cursor/rules,用 Cursor 的同事提交上来一堆 package-lock.json。
  2. 双倍消耗上下文:Cursor 同时识别 AGENTS.md 和 .cursor/rules。两处写一样的话,每轮对话都会重复计入上下文窗口。
  3. 互相屏蔽不自知: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/ 目录做两件事:

  1. 删掉与 AGENTS.md 重复的全局 .mdc 文件,让 Cursor 直接从根目录 AGENTS.md 读取项目总则;
  2. 只保留需要 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 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

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同产品的其他教程

  1. 01

    Anthropic Contextual Retrieval(上下文增强检索)是什么、怎么实现:给文档块自动补背景摘要结合缓存降失误率

    长文档切成小块后丢了公司名、年份和主语指代导致 RAG 频频搜错?本文按 Anthropic 官方技术文章详解 Contextual Retrieval 原理、官方公开评测失误率下降 49% 至 67% 的组合架构,以及用 Claude 提示词缓存低成本批量生成切片背景的完整 Python 代码。

    Claude其他 AI 工具0
  2. 02

    RAG 知识库回答不准怎么调优:切片大小(Chunking)、BM25 + 向量混合检索与 Rerank 重排序三步排查法

    搭好的 RAG 企业知识库一问具体型号、报错码或跨行表格就答非所问?本文按 OpenAI 与 Anthropic 官方检索文档,给出先隔离检索与生成故障、再按结构化切片(Chunking)、BM25 加向量混合召回(RRF)与 Rerank 重排序逐层调优的三步法。

    Claude其他 AI 工具0
  3. 03

    Langfuse 开源本地部署(Docker Compose)与提示词版本管理(Prompt Management)从零上手教程

    企业内网严禁业务日志出境,又想免费拥有大模型调用链追踪与不发版热更新提示词的能力?本文按 Langfuse 官方文档整理 Docker Compose 本地一键启动(含 ClickHouse 架构注意事项)、密钥配置与 Prompt Management 标签化版本管理全流程。

    Claude其他 AI 工具0
  4. 04

    LangSmith 入门教程:给 LangGraph 与原生 OpenAI / Claude 接口加调用链追踪、Token 成本统计与免费层限额

    智能体多步调用总是找不到哪一轮提示词跑偏、单次请求到底烧了多少 Token?本文按 LangSmith 官方文档讲清环境变量零侵入接入 LangGraph、用 wrap_openai / wrap_anthropic 与 @traceable 追踪原生接口,以及 Developer 免费层额度与留存规则。

    Claude其他 AI 工具0
  5. 05

    Zotero 搭配 Claude / ChatGPT 高效读英文文献:PDF 翻译插件、批注导出精读与防捏造参考文献流程

    在 Zotero 里读英文顶会论文怎么无缝联动 Claude 与 ChatGPT?本文整理 Translate for Zotero 划词翻译配置、高亮批注导出精读提示词,以及杜绝 AI 捏造假 DOI 参考文献的核验闭环。

    Claude其他 AI 工具0
  6. 06

    Obsidian 接入 Claude、ChatGPT 与本地 Ollama 做个人双链笔记问答:主流插件配置与隐私脱敏边界

    想在 Obsidian 里基于自己的双链笔记库做 AI 问答又担心隐私外泄?本文对比 Copilot 与 Smart Connections 插件,整理接入 Claude、OpenAI 官方 API 与本地 Ollama 的步骤及敏感目录隔离规则。

    Claude其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~