高效 AI 駕馭術
AGENTS.md、CLAUDE.md 怎麼寫?範例+一份規則管所有 AI 寫程式工具(2026)
CLAUDE.md 是 Claude Code 每次啟動讀的規則檔,AGENTS.md 是 Codex 讀的那一份。兩個工具各自從哪裡讀、`@` 匯入怎麼用、該寫什麼不該寫什麼,以及怎麼讓一份規則同時給兩個工具用,附可以直接複製的範本。
Kelvin Wang · · 10 分鐘閱讀
重點整理
- Codex 讀 AGENTS.md;Claude Code 讀 CLAUDE.md,repo 裡沒有 CLAUDE.md 時也會直接讀 AGENTS.md。
- 要兩個工具共用,規則寫在 AGENTS.md,CLAUDE.md 只放一行 @AGENTS.md,再加 Claude 專用的幾行。
- 只寫程式碼裡看不出來的事:測試指令、容易誤導的地方、已經做過的決定、糾正過兩次的錯。
- 一定不能違反的規則不要只寫在這裡,改用 hook、權限規則或測試。
每次開新對話,AI 寫程式工具都從空白開始。你上次說過的「測試要跑這個指令」「這個資料夾看起來沒用但不能刪」,它全都不記得,除非寫進它每次啟動都會讀的那個檔案。我同時用 Codex 和 Claude Code,這篇整理兩邊的官方文件(2026-11-16 查詢),再加上我讓兩個工具讀同一份規則的做法。
CLAUDE.md 和 AGENTS.md 差在哪?
兩個都是一般的 Markdown 檔,用途一樣:寫給 AI 看的專案說明和規則。差別在誰讀、從哪裡讀。
| 項目 | Codex | Claude Code |
|---|---|---|
| 讀哪個檔 | AGENTS.md(同一層有 AGENTS.override.md 時改讀它) | CLAUDE.md;沒有 CLAUDE.md 時直接讀 AGENTS.md |
| 個人全域 | ~/.codex/AGENTS.md(可用 CODEX_HOME 改位置) | ~/.claude/CLAUDE.md |
| 專案 | 從專案根目錄(通常是 Git 根目錄)一路往下到目前資料夾,每層最多讀一個 | 目前資料夾和上面每一層的 CLAUDE.md;子資料夾的在用到那裡的檔案時才載入 |
| 只給自己的專案設定 | 文件沒有提到 | CLAUDE.local.md,加進 .gitignore |
| 衝突時 | 離目前資料夾越近的檔案排越後面,以它為準 | 全部接在一起,離目前資料夾越近的越後面讀到 |
| 匯入其他檔案 | 文件沒有提到匯入語法 | @path/to/file,最多四層 |
| 大小 | 所有檔案合計預設 32 KiB,超過就不再加入 | 建議每個檔案 200 行以內 |
| 產生第一版 | /init | /init |
來源:Codex AGENTS.md 文件 [3]、Codex slash commands [5]、Claude Code memory 文件 [1]。
兩邊都有 /init。Claude Code 的會分析專案,產生第一版 CLAUDE.md,已經有的話改成提修改建議,不會覆蓋1;Codex 的會在目前資料夾產生一份 AGENTS.md 骨架5,文件建議產生後照團隊實際的做法再改4。
Claude Code 還有一個公司層級的位置(managed policy),由 IT 統一派送給組織裡每個人,個人用不到1。
Claude Code 會讀 AGENTS.md 嗎?
會,從 v2.1.277 開始。規則是看你的工作資料夾和上面幾層有沒有 CLAUDE.md1:
| 你的 repo 有 | Claude Code 讀 |
|---|---|
只有 AGENTS.md | AGENTS.md |
AGENTS.md 和 CLAUDE.md(或 CLAUDE.local.md) | 只讀 CLAUDE.md |
CLAUDE.md 裡寫了 @AGENTS.md | CLAUDE.md,AGENTS.md 經由匯入一起讀 |
要注意 CLAUDE.local.md 也算數。一個靠 AGENTS.md 運作的專案,就算你只是想加一份自己的筆記,放了 CLAUDE.local.md 之後,Claude Code 就不再讀 AGENTS.md。全域的 ~/.claude/CLAUDE.md 則不算,它會跟 AGENTS.md 一起載入1。
預設行為可以在 /config 的 Project instructions 改,例如兩種檔案都讀。不過最不用擔心版本和設定的,是官方文件寫的做法:規則寫在 AGENTS.md,旁邊的 CLAUDE.md 第一行匯入它,下面再加 Claude 專用的規則1。
@AGENTS.md
## Claude Code
- 改 src/billing/ 底下的東西先用 plan mode。
不需要 Claude 專用規則的話,也可以 ln -s AGENTS.md CLAUDE.md 做 symlink。官方文件提醒兩件事:Claude 的 Edit 工具不會透過 symlink 寫檔,而是直接編輯 AGENTS.md;團隊裡有人用 Windows 時改用匯入,因為 Windows 建 symlink 要系統管理員權限或開發人員模式,Git 也可能把它 checkout 成一個只有一行字的普通檔案1。
檔案要放在哪裡?
我的分法是三層:
- 全域:所有專案都適用的規則。溝通方式、改檔案前先讀最新版本、commit 只提交自己的修改。Codex 放
~/.codex/AGENTS.md,Claude Code 放~/.claude/CLAUDE.md。 - 專案根目錄:這個 repo 的建置和測試指令、資料夾的約定、做過的決定。放進版本控制,團隊共用。
- 子資料夾:只有某一塊才需要的規則,例如支付模組要用另一個測試指令。放在那個資料夾裡,AI 在那裡工作時才讀到。
子資料夾這層兩個工具都支援,做法不同。Codex 從根目錄往下讀到目前資料夾,越近的越後面、以它為準;某一層要完全換掉上層的規則,就在那裡放 AGENTS.override.md3。Claude Code 的子資料夾 CLAUDE.md 在 AI 讀寫那個資料夾的檔案時才載入;它另外有 .claude/rules/,每個規則檔可以用 paths 指定只在碰到符合的檔案時載入,例如只管 src/api/**/*.ts1。
@ 匯入怎麼用?
Claude Code 的 CLAUDE.md 裡寫 @ 加路徑,就會把那個檔案的內容一起載入1:
- 相對路徑以寫匯入的那個檔案為準,不是以你目前的資料夾為準。絕對路徑和
~開頭的路徑也可以。 - 被匯入的檔案可以再匯入,最多四層。
- 寫在反引號裡不會匯入。想在規則裡提到某個路徑但不要載入它,寫成
`@README`。 - 專案的 CLAUDE.md 匯入專案外的檔案時,第一次會跳出核准視窗。這是為了防止別人 commit 進來的檔案偷偷讀你電腦上的東西。你自己的
~/.claude/CLAUDE.md匯入外部檔案,一般不用核准。
匯入只是整理方便,不省 context:被匯入的內容跟 CLAUDE.md 一起載入,一樣佔空間1。
Codex 的 AGENTS.md 文件沒有提到匯入語法3,所以共用的 AGENTS.md 裡不要依賴 @ 匯入。Codex 的建議是主檔保持精簡,特定任務的細節寫在另外的 Markdown 檔,從主檔指過去4。Claude 專用的匯入就放在 CLAUDE.md。
規則檔裡該寫什麼?
兩邊官方文件的建議大致相同:寫 AI 從程式碼讀不出來、但每次都需要知道的事24。
- 確認做對的指令。測試、型別檢查、lint 怎麼跑,怎麼只跑一個測試檔。Claude Code 的文件說,repo 已經有測試的話,規則檔裡最有用的一行就是跑它的指令2。
- 容易誤導的地方。到處都是但新程式不能再學的舊寫法,看起來沒用其實還在用的資料夾。
- repo 裡看不到的決定。團隊選定的錯誤處理方式、怎麼部署、哪些改動要人看過。
- 已經糾正過兩次的事。Codex 的文件寫:同一個錯犯兩次,就請它檢討,然後更新 AGENTS.md4。
- 要先問人的操作。例如新增正式環境的套件前先確認。
寫法要具體到能檢查。「commit 前跑 npm test」比「記得測試」有用;「API handler 放在 src/api/handlers/」比「檔案要有條理」有用1。規則之間互相矛盾時,模型可能隨便挑一條照做,所以要定期回頭清掉過時和衝突的規則。
哪些東西不要寫進去?
- 架構和檔案結構。Claude Code 的文件說它會自己讀 repo,不用寫2。Codex 的建議清單則有列「repo 結構」4。我的折衷是只寫一行「從哪個檔案開始讀」,不逐一描述資料夾。
- 多步驟的做法。部署流程、發文流程這類寫成 skill,任務需要時才載入,平常不佔 context1。
- 只有某一塊才需要的規則。放到子資料夾的規則檔,或 Claude Code 的
paths規則。 - 一定不能違反的規則。規則檔是給模型讀的 context,模型可以判斷某條規則這次不適用。「絕對不能讀
.env」「不准動 migrations 資料夾」這類改用 hook 或權限規則2;格式和 lint 交給 CI3。 - 個人偏好。放全域檔或
CLAUDE.local.md,不放進團隊共用的檔案。 - 金鑰、token、帳號。規則檔會進版本控制,也會整份送進模型。
一直替某條規則加「IMPORTANT」、它還是被忽略,通常不是語氣不夠:要嘛檔案太長、那一行被淹沒,要嘛它是不能有例外的規則,應該交給 hook2。
想深入 AI Harness 是什麼?讓 AI agent 穩定做事的 7 個部分(2026) 規則檔之外,把規則寫成測試、skill、MCP、記憶、子代理和驗收。怎麼讓一份規則同時給 Codex 和 Claude Code 用?
我原本有三份全域指令,內容已經出現版本差異。後來我把共用規則收進 ~/ai-config/AGENTS.md,兩邊都讀這一份。~/ai-config 是一個 Git repo,每次改規則都有 commit 可以回查。
- Codex:
~/.codex/AGENTS.md是指向正本的 symlink。 - Claude Code:
~/.claude/CLAUDE.md只有一行@~/ai-config/AGENTS.md。 - skill:同一個 repo 裡的
setup.sh把每個 skill 用 symlink 同時連到兩個工具的 skill 資料夾。
我同時在替 Codex 和 Claude Code 搭 harness,要讓它們對同一個專案有一樣的記憶,規則就只能寫成同一份。
setup.sh --check 除了檢查 skill,也檢查這三件事,任何一件不對就報錯:
~/.codex/AGENTS.md是不是指向正本的 symlink,不是一份複製出來的檔案。~/.claude/CLAUDE.md是不是只有那一行匯入。有別的安裝程式在後面加了東西,就會被抓出來。- 家目錄底下有沒有
~/AGENTS.md。有的話,從家目錄啟動工具時,同一份規則可能被當成全域和專案各讀一次。
正本裡除了一般規則,我還寫了幾段跟「兩個工具同時在跑」有關的規則:
- 改檔案前先讀最新內容,只做局部修改,不拿舊的副本整份覆蓋。
- 修改失敗就重讀,不強行覆寫。
- commit 前看暫存區,只提交這次相關的修改,不把另一個 AI 的工作一起提交。
另外有一份專案索引:一行一個專案,寫名稱、別名、一句話用途和入口文件。我在對話裡提到某個專案,AI 就知道去哪裡讀細節,細節本身不寫進全域檔。
2026 年 10 月 12 日,我刪掉一整張「寫入路由」表:七種內容各寫到哪裡、要不要先問我。現在只剩一句:新專案在索引加一行,細節寫在那個專案自己的 repo。同一天,Claude Code 的 CLAUDE.md 也縮成只剩一行匯入。
專案這一層,建議照前面的做法:規則寫在專案的 AGENTS.md,CLAUDE.md 用 @AGENTS.md 匯入。同一個專案分別維護兩份內容相近的檔案,久了一定會分岔。
可以直接複製的範本
全域規則,存成 ~/ai-config/AGENTS.md(路徑自己決定):
# 全域規則
## 溝通
- 用繁體中文回答。
- 不確定的事說不確定,不要編造。
## 修改檔案
- 改檔案前先讀最新內容;只做局部修改,不整份覆寫。
- commit 前看暫存區,只提交這次相關的修改。
- push、刪除資料、正式環境的操作,先問我。
## 完成的標準
- 說完成之前,跑過測試,告訴我跑了哪個指令、結果是什麼。
## 專案索引
- <專案代號> | <名稱> | <一句話用途> | <入口文件路徑>
接到兩個工具上(原本已經有 ~/.codex/AGENTS.md 或 ~/.claude/CLAUDE.md 的話,先把內容搬進正本,再刪掉舊檔):
mkdir -p ~/.codex ~/.claude
ln -s ~/ai-config/AGENTS.md ~/.codex/AGENTS.md
echo '@~/ai-config/AGENTS.md' > ~/.claude/CLAUDE.md
專案規則,存成 repo 根目錄的 AGENTS.md:
# <專案名稱>
## 指令
- 安裝:npm install
- 測試:npx vitest run
- 只跑一個測試檔:npx vitest run tests/<檔名>.test.ts
- 建置:npm run build
## 約定
- 改畫面前先讀 DESIGN.md。
- src/legacy/ 還在用,但新程式不要照它的寫法。
## 要先問人
- 資料庫 migration 套到正式環境前。
- push 到 main(push 就會部署)。
旁邊的 CLAUDE.md:
@AGENTS.md
## Claude Code
- 只有 Claude Code 需要知道的規則寫在這裡。
怎麼確認工具真的讀到了?
- Claude Code:在對話裡跑
/context all,看 Memory files 底下有沒有列出你的檔案。沒列出來,它就看不到1。 - Codex:在 repo 根目錄跑
codex --ask-for-approval never "Summarize the current instructions.",看它複述的規則對不對;子資料夾的規則用codex --cd <子資料夾>再跑一次3。Codex 每次啟動都會重新組合規則,改完重開就生效。
常見問題
CLAUDE.md 寫越長越好嗎?
不是。每一行都會在每個任務裡佔一點注意力,不管跟任務有沒有關係。Claude Code 建議每個檔案 200 行以內1,Codex 預設所有 AGENTS.md 合計 32 KiB,超過的部分不會載入3。
規則檔可以寫給人看的註解嗎?
Claude Code 會在載入前拿掉區塊層級的 HTML 註解(<!-- … -->),可以拿來寫給維護者看的說明,不佔 context1。Codex 的文件沒有提到這件事,共用的 AGENTS.md 裡別太依賴它。
一個工具的規則檔,另一個工具會不會讀錯?
Claude Code 讀 AGENTS.md 時,@ 匯入一樣會展開1;Codex 的文件沒有提到匯入,@ 那一行在 Codex 看來只是文字。所以共用檔寫成不依賴匯入也能讀懂的樣子,工具專用的部分各放在各自的檔案。
資料來源