攻略
AGENTS.md、CLAUDE.md、GEMINI.md:三個 CLI 共用一份指示檔
Claude Code、Codex CLI、Gemini CLI 找的檔名不同,找的位置也不同。這篇整理三者現在實際讀哪些檔案,以及一套只寫一次專案規則的做法。
三個 CLI 各讀哪個指示檔?
三者都把這些檔案當成對話裡的背景資料,而不是強制執行的設定。細節的差異比檔名還多。
| Claude Code | Codex CLI | Gemini CLI | |
|---|---|---|---|
| 專案檔 | CLAUDE.md 或 .claude/CLAUDE.md | AGENTS.md | GEMINI.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 怎麼共用一份指示檔?
- 在 repo 根目錄寫 AGENTS.md這就是共用的那一份,Codex 不用任何設定就會讀。
- 加一個一行的 CLAUDE.md第一行寫
@AGENTS.md,需要的話在下面補 Claude 專用的說明。即使在無法直接讀AGENTS.md的 Session 也有效,之後加了CLAUDE.local.md也不受影響。 - 讓 Gemini CLI 指向它照上面把
context.fileName設成包含AGENTS.md;團隊有人用 Gemini CLI 的話,把.gemini/settings.json一起 commit。 - 逐一確認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 嗎?
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 嗎?
資料來源
- How Claude remembers your project,Anthropic(2026-11-19 查證)
- Extend Claude with skills,Anthropic(2026-11-19 查證)
- Custom instructions with AGENTS.md,OpenAI(2026-11-19 查證)
- Build skills,OpenAI(2026-11-19 查證)
- Provide context with GEMINI.md files,Google(2026-11-19 查證)
- Gemini CLI configuration,Google(2026-11-19 查證)
- Trusted Folders,Google(2026-11-19 查證)
- Agent Skills,Google(2026-11-19 查證)
- 建立符號連結(Create symbolic links),Microsoft(2026-11-19 查證)