結論先說
- 公共約定只寫一份,統一放進倉庫根目錄的
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 條評論
還沒有評論,來搶沙發~