攻略

AGENTS.md、CLAUDE.md、GEMINI.md:三個 CLI 共用一份指示檔

Claude Code、Codex CLI、Gemini CLI 找的檔名不同,找的位置也不同。這篇整理三者現在實際讀哪些檔案,以及一套只寫一次專案規則的做法。

三個 CLI 各讀哪個指示檔?

三者都把這些檔案當成對話裡的背景資料,而不是強制執行的設定。細節的差異比檔名還多。

Claude CodeCodex CLIGemini CLI
專案檔CLAUDE.md 或 .claude/CLAUDE.mdAGENTS.mdGEMINI.md
讀 AGENTS.md 嗎?v2.1.277 起,沒有 CLAUDE.md 時會讀;用 @AGENTS.md 匯入則一律讀得到原生就讀要列在 context.fileName 才讀
使用者層~/.claude/CLAUDE.md(另有 ~/.claude/rules/)~/.codex/AGENTS.md(或 CODEX_HOME)~/.gemini/GEMINI.md
個人/覆寫檔CLAUDE.local.md,建議加進 gitignore同一個資料夾裡 AGENTS.override.md 優先於 AGENTS.md文件沒有寫
資料夾範圍啟動時讀工作目錄與每一層上層;子資料夾的檔案在 Claude 動到那裡時才載入從 repo 根目錄往下到工作目錄,每個資料夾最多一個檔workspace 與上層直到 .git;工具碰到某個資料夾時再載入那裡的檔案
匯入@path,最多四層文件沒有寫@file.md,相對或絕對路徑
大小建議每個檔案 200 行以內;超過 4 MiB 的檔案整個略過合計預設到 32 KiB 就不再加檔(project_doc_max_bytes)文件沒寫大小上限;最多搜尋 200 個資料夾
確認載入了什麼/context all 或 /memory請它摘要目前的指示/memory show

三者都是把檔案合併起來,不是互相取代。Claude Code 和 Codex 會把離工作目錄最近的檔案放在最後;Codex 說較近的檔案會覆蓋前面的指示,Anthropic 則提醒兩條指示衝突時 Claude 可能照任何一條做。最好別讓檔案彼此矛盾。

Claude Code 會讀 AGENTS.md 嗎?

會,但有條件。v2.1.277 起有一個內建外掛會把 AGENTS.md 當成專案指示讀進來,不過在預設設定下,只有工作目錄與上層都沒有 CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md 時才讀。~/.claude/CLAUDE.md 與 .claude/rules/ 不算在這個判斷裡,會照常一起載入。

  • 兩個檔案都有時,Claude 只讀 CLAUDE.md;除非它匯入了 AGENTS.md,或你在 /config 把「Project instructions」設成 claude-md-and-agents-md。
  • 為了放自己的筆記而加一個 CLAUDE.local.md,預設就會讓 Claude 不再讀 AGENTS.md。
  • Claude Code 不讀 AGENTS.override.md、AGENTS.local.md,也不讀 .agents/ 底下的任何東西。
  • 有些 Session 沒辦法直接讀 AGENTS.md,例如舊版本。這時用 @AGENTS.md 匯入就行;Anthropic 說保留匯入不會讓同一個檔案被讀兩次。

Codex CLI 怎麼找 AGENTS.md

Codex 在啟動時組好一次指示鏈。先讀全域檔:~/.codex 裡的 AGENTS.override.md(存在且不是空的),否則讀 AGENTS.md。接著從專案根目錄(通常是 git 根目錄)往下走到工作目錄,每個資料夾依序找 AGENTS.override.md、AGENTS.md,以及 project_doc_fallback_filenames 裡的檔名,取第一個找到的。

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

合計大小到 project_doc_max_bytes(預設 32 KiB)後,Codex 就不再加入更多檔案。改完設定要重新啟動 Codex。

怎麼讓 Gemini CLI 讀 AGENTS.md

Gemini CLI 先讀 ~/.gemini/GEMINI.md,再讀 workspace 與上層資料夾的 GEMINI.md,之後工具打開某個資料夾時再載入那裡的檔案。context.fileName 可以填一個檔名或一串檔名。放在專案的 .gemini/settings.json,或放在 ~/.gemini/settings.json 讓所有專案都套用:

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

如果你開了 Gemini CLI 的 Trusted Folders 功能,不受信任資料夾裡的 .gemini/settings.json 會被忽略。要在信任資料夾之前就生效,請放在使用者層的設定檔。

Claude Code、Codex、Gemini 怎麼共用一份指示檔?

  1. 在 repo 根目錄寫 AGENTS.md這就是共用的那一份,Codex 不用任何設定就會讀。
  2. 加一個一行的 CLAUDE.md第一行寫 @AGENTS.md,需要的話在下面補 Claude 專用的說明。即使在無法直接讀 AGENTS.md 的 Session 也有效,之後加了 CLAUDE.local.md 也不受影響。
  3. 讓 Gemini CLI 指向它照上面把 context.fileName 設成包含 AGENTS.md;團隊有人用 Gemini CLI 的話,把 .gemini/settings.json 一起 commit。
  4. 逐一確認Claude Code 跑 /context all;在 repo 根目錄跑 codex --ask-for-approval never "Summarize the current instructions.";Gemini CLI 跑 /memory show。
# CLAUDE.md
@AGENTS.md

## Claude Code
Use plan mode for changes under src/billing/.

為什麼不用 symlink?

Anthropic 的文件也列出 ln -s AGENTS.md CLAUDE.md 這個做法,但有兩個問題。Claude 的 Edit 與 Write 工具不會透過 symlink 寫入。在 Windows 上,建立 symlink 需要系統管理員權限或開發人員模式;而且除非開了 core.symlinks,Git 會把 commit 進去的 symlink 簽出成一般文字檔,那份 clone 拿到的 CLAUDE.md 就只有一行路徑,不是你的規則。Microsoft 的「建立符號連結」(Create symbolic links)原則預設也只給 Administrators 群組。團隊裡只要有人用 Windows,就用匯入。

AGENTS.md 該寫什麼、不該寫什麼

寫下你每次開新 Session 都得重講一遍的事。要具體到能檢查:「commit 前先跑 npm test」比「記得測試」有用。

  • 要寫:建置、測試、lint 的確切命令;和一般預設不同的慣例;不容易找到的關鍵程式碼位置;不能動的資料夾與檔案;怎樣才算改完。
  • 不要寫:API Key、token、密碼,以及不想公開的內部網址。這個檔案通常會 commit 進 repo,內容也會隨每次請求送給模型供應商。
  • 不要寫:很長的逐步操作流程。Anthropic 建議改放在 Skill 或只對特定路徑生效的規則裡。
  • 不要寫:Agent 讀程式碼就知道的東西,例如目錄清單、相依套件清單。
  • 放到別處:個人偏好放使用者層的檔案或 CLAUDE.local.md,不要放共用的那份。
# AGENTS.md
## Commands
- Install: pnpm install
- Test: pnpm test (run before every commit)
- Lint: pnpm lint

## Conventions
- API responses use camelCase.
- New tests go in tests/ and use Vitest.

## Do not touch
- legacy/ and anything under generated/

指示是建議,不是鎖。要每次都擋下某個動作,Anthropic 建議用 hooks 與權限設定,而不是寫在 CLAUDE.md。

Skills:各 CLI 的 SKILL.md 資料夾

一個 Skill 就是一個含 SKILL.md 的資料夾:開頭是帶描述的 YAML frontmatter,後面是指示。和指示檔不同,Skill 只在用得到時才載入。三個 CLI 現在都支援 Skills,但放的資料夾不一樣。

使用者層專案層
Claude Code~/.claude/skills/<name>/SKILL.md.claude/skills/<name>/SKILL.md
Codex CLI~/.agents/skills工作目錄、它的上一層與 repo 根目錄的 .agents/skills
Gemini CLI~/.gemini/skills 或 ~/.agents/skills.gemini/skills 或 .agents/skills

一個 .agents/skills 資料夾可以同時給 Codex 與 Gemini CLI 用。Claude Code 不讀 .agents/,需要在 .claude/skills 另放一份。Codex 要求 frontmatter 同時有 name 與 description。

Pyloxa 能幫上什麼

Pyloxa 是免費的 Windows 桌面 App,讓 Claude Code 與 Codex CLI(Gemini CLI 為實驗性支援)在同一個專案上合作。它的共用記憶是放在你電腦上的一份記憶,Pyloxa 派工時三個 CLI 都會拿到它當背景資料:規則、偏好、決定、事實與踩過的坑。Agent 工作時可以提議新的記憶,但提議會先放進「待確認」,你接受之後才算數。共用記憶的所有功能都在免費版。

  • 「同步到各 CLI」把專案的記憶寫成 AGENTS.md 裡一段有標記的 Pyloxa 區塊,並在 CLAUDE.md 加上 @AGENTS.md,和上面的做法一樣。寫入前先讓你看差異,Pyloxa 不會替你 commit。
  • 「也寫進各 CLI 的使用者層記憶」(~/.claude/CLAUDE.md、~/.codex/AGENTS.md、~/.gemini/GEMINI.md)預設關閉;打開後,Pyloxa 第一次寫入前會先備份這些檔案。
  • 可以從既有的檔案匯入,例如 CLAUDE.md、.claude/rules/*.md、AGENTS.md、GEMINI.md,Pyloxa 只讀取這些檔案。
  • Skills 盤點(看每個 CLI 讀得到哪些 Skills)是免費的。把 Skills 集中在 ~/.agents/skills 並同步到各 CLI 的 Skills 庫,以及依專案或 Profile 指派 Skills,屬於 Pro。

如果你只用一個 CLI,或上面那套 AGENTS.md 加匯入已經夠用,這件事就不需要 Pyloxa。

常見問題

Codex 會讀 CLAUDE.md 嗎?
預設不會。Codex 找的是 AGENTS.override.md、AGENTS.md,以及你在 ~/.codex/config.toml 的 project_doc_fallback_filenames 加的檔名,而且每個資料夾最多用一個檔。把 AGENTS.md 當主檔,就不用煩惱這件事。
CLAUDE.md 和 AGENTS.md 都有,Claude Code 用哪個?
預設只用 CLAUDE.md。在裡面加 @AGENTS.md,或在 /config 把「Project instructions」設成 claude-md-and-agents-md,兩個都會載入。
為什麼 Claude Code 突然不讀我的 AGENTS.md?
最常見的原因是工作目錄或上層出現了 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md。版本早於 v2.1.277,或停用了讀 AGENTS.md 的內建外掛,也會這樣。放一個匯入 AGENTS.md 的 CLAUDE.md,以上情況都能解決。
GEMINI.md 可以匯入其他檔案嗎?
可以。在想放入內容的位置寫 @./path/file.md,相對與絕對路徑都可以。用 /memory show 看合併後的結果。
可以把 API Key 寫進 AGENTS.md 嗎?
不行。這個檔案通常會 commit 進 repo,內容也會隨每次請求送給模型供應商。金鑰交給 CLI 自己的登入或環境變數管理,不要放進指示檔。

資料來源

  1. How Claude remembers your project,Anthropic(2026-11-19 查證)
  2. Extend Claude with skills,Anthropic(2026-11-19 查證)
  3. Custom instructions with AGENTS.md,OpenAI(2026-11-19 查證)
  4. Build skills,OpenAI(2026-11-19 查證)
  5. Provide context with GEMINI.md files,Google(2026-11-19 查證)
  6. Gemini CLI configuration,Google(2026-11-19 查證)
  7. Trusted Folders,Google(2026-11-19 查證)
  8. Agent Skills,Google(2026-11-19 查證)
  9. 建立符號連結(Create symbolic links),Microsoft(2026-11-19 查證)

想把這些交給工具處理?

Pyloxa 是免費的 Windows App,執行你已經在用的 Claude Code 與 Codex CLI:依你的規則分工、自己跑你的測試,某一個額度用完時提出換手。