同一倉庫怎麼同時維護 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 條評論

登入 後參與評論

還沒有評論,來搶沙發~