04-1 CLAUDE.md 與記憶檔：用途、最佳化、長度、格式

這個單元解決什麼問題CLAUDE.md 是每個 session 起手自動注入的常駐指令，是你給 agent 的「常識」。寫太長吃 context、寫太空沒約束力。本單元拆解它的載入時機、覆寫層級、最佳長度與模組化結構，並把指令型 CLAUDE.md 與事實型自動記憶的分工講清楚，最後對照各家工具的專案級指令檔命名。

學習目標

說出 CLAUDE.md 的四種放置位置（managed / user / project / local）與其載入優先序。
用「跨任務複利」篩選標準判斷哪些內容該進 CLAUDE.md、哪些不該。
用 @path 匯入語法與 .claude/rules/ 路徑範圍把規則模組化，避免單一巨型檔案。
分清 CLAUDE.md（指令型）與自動記憶（事實型）的差異，並識別記憶污染的風險與處置。
對應 OpenAI Codex、Google Antigravity、GitHub Copilot、Cursor 等工具的專案級指令檔名。

1. `CLAUDE.md` 是什麼、何時載入

CLAUDE.md 是放在磁碟上的純文字 Markdown 檔。Claude Code 在每個 session 開頭讀進來，作為使用者訊息注入到對話脈絡中。讀進來之後，它就跟你說的每一句話一起佔用 context window 的 token 預算。兩個關鍵事實先記起來：

它是 context，不是 enforced configuration。Claude 會「試著遵守」，但遇到衝突或遺漏時沒有硬保證。硬保證機制見第 8 節 Hook 的保證執行差異。
它是 每次 session 都全量注入 的常駐訊息，不像 Skill 是按需載入（見 04-4 Skill）。所以寫每一行都要算 token 帳。

用 /init 起步最快在一個新專案目錄裡跑 /init，Claude Code 會自動掃你的 codebase、產生一份起手 CLAUDE.md（建構指令、測試流程、專案慣例）。它讀的是「可以被機械推斷的事」，你再依領域知識補上「它推斷不出但每次都要交代」的規則。

2. 放置位置與覆寫層級

Claude Code 在啟動時會依下列順序尋找並載入 CLAUDE.md（截至 2026-06，依官方記憶章節 [1]）：

範疇	位置	用途	誰會看到
Managed policy	macOS `/Library/Application Support/ClaudeCode/CLAUDE.md`、Linux/WSL `/etc/claude-code/CLAUDE.md`、Windows `C:\Program Files\ClaudeCode\CLAUDE.md`	組織級強制規範（資安、編碼標準、合規）	全組織機器
使用者級	`~/.claude/CLAUDE.md`	個人跨專案偏好（縮排、工具捷徑、語言）	只有你
專案級	`./CLAUDE.md` 或 `./.claude/CLAUDE.md`	團隊共用的專案慣例	透過版控共享給團隊
本地覆寫	`./CLAUDE.local.md`	個人在本專案的私有設定（沙盒 URL、本機測試資料）	只有你，加進 `.gitignore`

載入順序不是「覆寫」多個檔案是串接進 context，不是後者覆蓋前者。從 root 往工作目錄的順序串接，本地檔最後讀。CLAUDE.md 與 CLAUDE.local.md 在同一層時，本地檔附加在後。意思是：寫在某個資料夾下的 CLAUDE.md，會被任何在它子目錄啟動的 session 一起讀進來。

Managed policy 是組織發布、不可被個人關閉的；個人與專案層的 CLAUDE.md 則可用 claudeMdExcludes 排除特定檔案（任何設定層皆可設，陣列跨層合併），這在大型 monorepo 裡避免「別的團隊的 CLAUDE.md 污染你」很實用；但 Managed policy 的 CLAUDE.md 無法被排除 [1]。

3. 該寫什麼、不該寫什麼：跨任務複利原則

篩選標準只有一個：一條規則如果下次 session 還會用得到，就寫進來；只用一次的就別寫。 用這個標準可以快速過濾掉 80% 的候選內容。適合放進 CLAUDE.md 的：

角色與語言：第二人稱、回應語言、術語表。
編碼風格：縮排、命名、引號風格、模組拆分慣例。
建構與測試指令：make test、uv run pytest、pnpm lint 這類。
專案結構與邊界：「API 處理器在 src/api/handlers/」「不要動 dist/」。
禁則：「不要改 migrations/ 既有檔案」「不要 commit 任何 .env」。
常用工作流：「修完 bug 先跑 make lint 再 commit」。

不該放進來的：

一次性任務細節（「幫我把 PR #1234 接上 main」）。
頻繁變動的版本號、套件名單（這些會過期，且應由 lockfile 管）。
機密（API key、密碼、token）。CLAUDE.md 進版控，機密應在 .env 與 .gitignore 處理。
冗長背景（超過一頁的專案沿革、設計理念）。背景應在對話脈絡裡傳入，而不是常駐。
屬於另一條主軸的內容：多步程序、跨檔重構 SOP、發版流程，拆成 Skill（見 04-4 Skill）。

寫「祈使句」而不是「描述」CLAUDE.md 對模型來說是「該遵守的事」，不是「專案介紹」。同樣的內容，祈使句版本比描述句版本效果好數倍。不要：「我們的測試使用 pytest 框架，跑在 Python 3.11+ 環境，主要用 fixture 與 parametrize…」（描述）寫成：「跑測試用 uv run pytest，單一測試檔案用 uv run pytest path/to/test_x.py -k name」（祈使）祈使句讓模型更容易抽取出「該做什麼」。

4. 長度與 token 預算

Anthropic 官方對 CLAUDE.md 的長度建議是 每個檔案 200 行以內 [1]。不是硬限制，但有兩個理由：

adherence 會掉。檔案越長，模型在多輪對話後記住並遵循的規則比例越低；越簡短越一致。
每次 session 都在燒 token。CLAUDE.md 載入後就不會從 context 移除（除非你手動 /compact 並重新觸發載入），寫得越長，後續每次互動都付同樣成本。

如果一條規則只在某個子目錄或副檔名才需要，把它拆到 .claude/rules/<topic>.md 並用 paths frontmatter 限定（見 04-2 rules）；這樣它不會在所有 session 全量載入，只在 Claude 觸及對應檔案時才讀。

真實成本：200 行 vs 800 行的差異假設 CLAUDE.md 約 200 行、平均每行 25 token，單次 session 起手就吃掉 5,000 token 靜態開銷。同一份內容膨脹到 800 行，變成 20,000 token；在 200k 脈絡視窗下，800 行版本永遠先少掉約 7.5% 的對話空間。Claude Opus 4.5 單次輸入成本高，800 行版本一年下來可多付數百美元；這還不包含 adherence 下降帶來的回頭修正成本。

結構化分段

把段落用 Markdown 標題明確分組，並避免大段散文。模型會掃結構，把同一主題的規則集中放在一個 ## 標題下，比把規則散落在三段散文裡更穩定。

區塊註解會被剝除官方在載入 CLAUDE.md 前會把  形式的 HTML 區塊註解移除 [1]。意思是：你可以留給人類維護者的註解（例如「這段來自 2026-04 的 linting 討論」），它不會佔 token。code block 內的註解不會被剝。直接用 Read 工具開啟 CLAUDE.md 時，註解仍然可見，被移除的只是注入給模型的那份。

5. 模組化：避免單一巨檔

兩種正交工具可以幫你拆檔。

5.1 用 `@path` 匯入

CLAUDE.md 內可以用 @path/to/import 語法匯入其他檔案 [1]：

# CLAUDE.md
See @README for project overview and @package.json for available npm commands.

# Coding standards
- Python style: @docs/python-style.md
- API design: @docs/api-conventions.md

規則：

相對路徑以含 @ 的檔案為基準，不是當前工作目錄。
匯入可遞迴，最深 4 層。
匯入的檔案在 session 啟動時也一起全量載入，所以 @ 匯入是組織結構用，不是省 token 用。要省 token 請用 .claude/rules/ 的 path-scoped 機制。
第一次使用外部匯入時，Claude Code 會跳信任核取對話框；按拒絕後該專案就停用匯入 [1]。

跨工作流共享個人偏好如果你有多個 git worktree，把個人跨 worktree 共用的偏好放在 ~/.claude/my-project-instructions.md，然後在每個 worktree 的 CLAUDE.md 用 @~/.claude/my-project-instructions.md 引用，省去重複編輯。

5.2 拆到 `.claude/rules/`

當某條規則只在特定副檔名或子目錄才需要，把整個規則拆到 .claude/rules/<topic>.md 並用 paths frontmatter 限定觸達範圍（見 04-2 rules）。.claude/rules/ 內的檔案不寫 paths 時與 CLAUDE.md 等價，都會在 session 啟動時全量載入；寫了 paths 之後只在 Claude 觸及符合 glob 的檔案時才載入。

拆分前（單檔膨脹，320 行）
拆分後（只載必要）

# 角色與語言（20 行）
# 建構與測試（30 行）
# Python 編碼風格（120 行）
# API 設計規範（80 行）
# 前端 React 規範（70 行）

每次 session 啟動，這 320 行全量注入。

CLAUDE.md            # 50 行：角色、語言、建構、測試、全域禁則
.claude/rules/
  python-style.md    # 120 行，paths: ["**/*.py"]
  api-design.md      # 80 行，paths: ["src/api/**"]
  react-style.md     # 70 行，paths: ["src/components/**/*.{ts,tsx}"]

每次 session 啟動只花 50 行的成本；改 Python 檔時多載 120 行、改 API 時多載 80 行。「只在相關時載入」是把 token 用在刀口上的關鍵。

6. 自動記憶：事實型記憶

CLAUDE.md 是你寫給 Claude 的指令。自動記憶是 Claude 自己寫給未來自己的事實筆記 [1]。兩者並用：

	`CLAUDE.md`	自動記憶
誰寫	你	Claude 自己
內容	指令、規則、慣例	觀察到的事實：建構指令、除錯心得、發現的偏好
範疇	專案、使用者、組織	依 git repo（同一 repo 的所有 worktree 與子目錄共享；不在 git repo 內時以專案根目錄為鍵）
載入	每次 session 全量	每次 session 載入 `MEMORY.md` 前 200 行或 25KB（取先達），topic 檔按需
適用於	編碼標準、工作流、專案結構	建構指令、除錯觀察、Claude 從對話裡學到的偏好

儲存位置：~/.claude/projects/<project>/memory/，裡面有 MEMORY.md 索引檔與多個 topic 檔（debugging.md、api-conventions.md 等）[1]。這是機器本地的，不跨機器、不同步雲端，跨 worktree 但同 repo 會共享。啟用條件：Claude Code v2.1.59 以上 [1]。預設開啟；用 /memory 命令或在 settings.json 設 autoMemoryEnabled: false 關閉；用環境變數 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 也可關。要改上述預設儲存位置，用 settings.json 的 autoMemoryDirectory（吃絕對路徑或 ~/ 前綴；設在專案或 local 層需先通過 workspace 信任對話才生效）[1]。

自動記憶是雙刃Claude 會依「未來對話是否還用得到」決定要不要寫。它寫進去的東西你可能不想要（例如把某次你口頭實驗的怪招當成偏好記下來）。/memory 命令可以瀏覽、開啟、編輯、刪除記憶檔。把它當成你自己寫的筆記：定期 review 一次。

7. 記憶污染：自動記憶的供應鏈風險

外部內容進到 agent 後被寫進自動記憶，下個 session 載入時它就影響行為，這就是記憶污染。具體攻擊面見 03-3 安全、隱私與供應鏈風險，這裡只點與本單元有關的處置：

不可信內容的工作流結束後清除或輪替 ~/.claude/projects/<project>/memory/ 的內容。
定期 review 自動記憶：跑 /memory 開啟資料夾，至少掃一眼 MEMORY.md 與各 topic 檔。
機密不該進自動記憶：Claude 可能把你貼過的 API key、token 寫進去。MEMORY.md 是純文字本機檔，沒有加密；備份或同步時它就一起走。

8. 與 Hook 的分工：`CLAUDE.md` 是「請你遵守」，Hook 是「強制執行」

CLAUDE.md 是 context，被模型在生成回應時參考；遇到「不要 commit .env」這種禁則，模型可能在長鏈任務裡漏掉。Hook 才是硬保證（見 04-6 Hooks）：

CLAUDE.md：「不要 commit .env 檔案」，模型多半會記得，但偶爾會漏。
Hook（PreToolUse on Bash）：Bash(git commit *) 觸發時，shell 端檢查 staged 檔案含 .env 就 exit code 2 中斷，任何時候都擋下。

判準：需要模型「記得」就寫 CLAUDE.md；需要「不論如何都擋下來」就寫 Hook。

9. 工具對照：各家專案級指令檔

AGENTS.md 已成為多家工具原生支援的跨工具共通專案規則檔，由 Linux Foundation 下的 Agentic AI Foundation 維護，截至 2026-06 已被 60,000+ 開源專案採用（採用面與治理主張的來源是 [4]，非 Anthropic 官方文件）。Claude Code 原生讀的是 CLAUDE.md，但可以 @AGENTS.md 匯入進來 [1]。

官方說法：Claude 讀 CLAUDE.md，不讀 AGENTS.mdAnthropic 官方記憶章節的原文是：「Claude Code 讀取 CLAUDE.md，而不是 AGENTS.md。如果您的儲存庫已經為其他編碼代理使用 AGENTS.md，請建立一個 CLAUDE.md 來匯入它，以便兩個工具讀取相同的指令而不重複。」來源：Claude Code 記憶章節 AGENTS.md 段（官方）（截至 2026-06）[1]。官方給的最小作法：CLAUDE.md 第一行 @AGENTS.md 匯入，下面再接 Claude 專屬指令；若不需要 Claude 專屬內容，ln -s AGENTS.md CLAUDE.md 符號連結也行。Windows 建符號連結需系統管理員權限或開發者模式，所以官方建議在 Windows 上改用 @AGENTS.md 匯入。

命名澄清本表「主範本」欄採官方現用命名。Claude Code 對應的常駐指令檔是 CLAUDE.md（不是 AGENTS.md）；但若專案已有 AGENTS.md，可用 @AGENTS.md 匯入讓 Claude 也讀它。Google Antigravity 讀 GEMINI.md 與 AGENTS.md，兩者的優先序各來源說法不一，詳見 02-6 其他工具對照。Cursor 為第三方 IDE（Anysphere），本 Playbook 僅短提一欄。

10. 自我檢核動手做

刪減

把現有 CLAUDE.md（如果有）的每一條用「跨任務複利」標準過濾，刪掉只對一次性任務有用的。比較刪前刪後行數。

拆分

把 Python 或前端編碼風格（若超過 30 行）抽到 .claude/rules/<lang>-style.md，加 paths frontmatter 限定。

本機層

把個人本機才需要的設定（沙盒 URL、測試資料位置）搬到 CLAUDE.local.md 並加進 .gitignore。

驗證

在同一個工作目錄用 claude 啟動，跑 /memory 檢查所有該載入的檔案都在清單上。

trust 對話框

第一次用 @path 匯入外部檔案時，會跳信任核取。決定好策略：要全專案信任、還是要個別檔案放行。

11. 常見誤區

反模式清單

照抄別人的 CLAUDE.md：別人的慣例反映別人的工作流。照抄會引入你不需要的約束，甚至安全風險（見 03-3 安全、隱私與供應鏈風險）。先看骨架，再依自己的工作流改寫。
CLAUDE.md 越寫越長，層層疊加自相矛盾：模型在衝突時會任選其一，你可能不知道。多檔疊加後定期 review、刪掉過期規則。
把「保證執行」寫成祈使句：需要 hook 強制的事寫在 CLAUDE.md，模型可能漏；需要確定性保證的場合見 04-6 Hooks。
把 .env 寫進 CLAUDE.md：它進版控，機密就不機密了。機密放 .env 與 .gitignore。
跨工具照抄單一一個檔名：Claude 不讀 AGENTS.md（除非你 @ 匯入），GitHub Copilot 不讀 CLAUDE.md。跨工具時，請用 AGENTS.md 作為共通底盤，工具特定設定各自加掛。

自我檢核

通過本單元的標準

你能在 1 分鐘內說出 CLAUDE.md 的四種放置位置、載入順序，以及哪一種可以關閉、哪一種不行嗎？
你能對自己 CLAUDE.md 裡的每一條，說出「刪掉會有什麼後果」嗎？說得出的留，說不出的刪。
你能說出「這條該進 CLAUDE.md、.claude/rules/、Skill 還是 Hook」的判準嗎？
你知道自動記憶存哪、怎麼看、怎麼清嗎？

來源與延伸閱讀

事實主張依官方文件，快變動項標註截至 2026-05。

[1] Anthropic, “How Claude remembers your project,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/memory （截至 2026-06）
[2] Anthropic, “Extend Claude with skills,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/skills （截至 2026-06；含 Skill 與指令機制整合說明）
[3] Cursor, “Rules,” cursor.com, 2026. [Online]. Available: https://cursor.com/docs/context/rules （截至 2026-06；.mdc 與 globs frontmatter 機制）
[4] Agentic AI Foundation (Linux Foundation), “AGENTS.md, a simple, open format for guiding coding agents,” 2026. [Online]. Available: https://agents.md/ （截至 2026-06；60,000+ 開源專案採用、支援工具完整清單見該頁）

設定層級模型見 02-1 設定的層級模型。
Hook 強制執行見 04-6 Hooks。
規則檔 path-scoped 機制見 04-2 rules。
Skill（按需載入的程序）見 04-4 Skill。
自動記憶的供應鏈風險見 03-3 安全、隱私與供應鏈風險。

總覽

Part I 基礎與進階認識

Part II 進階調適與設定

Part III 認知與思維

Part IV 客製化、整合與自動化

Part V Agentic 案例研究

附錄

04-1 CLAUDE.md 與記憶檔：用途、最佳化、長度、格式

學習目標

1. `CLAUDE.md` 是什麼、何時載入

2. 放置位置與覆寫層級

3. 該寫什麼、不該寫什麼：跨任務複利原則

4. 長度與 token 預算

結構化分段

5. 模組化：避免單一巨檔

5.1 用 `@path` 匯入

5.2 拆到 `.claude/rules/`

6. 自動記憶：事實型記憶

7. 記憶污染：自動記憶的供應鏈風險

8. 與 Hook 的分工：`CLAUDE.md` 是「請你遵守」，Hook 是「強制執行」

9. 工具對照：各家專案級指令檔

10. 自我檢核動手做

11. 常見誤區

自我檢核

來源與延伸閱讀

​學習目標

​1. CLAUDE.md 是什麼、何時載入

​2. 放置位置與覆寫層級

​3. 該寫什麼、不該寫什麼：跨任務複利原則

​4. 長度與 token 預算

​結構化分段

​5. 模組化：避免單一巨檔

​5.1 用 @path 匯入

​5.2 拆到 .claude/rules/

​6. 自動記憶：事實型記憶

​7. 記憶污染：自動記憶的供應鏈風險

​8. 與 Hook 的分工：CLAUDE.md 是「請你遵守」，Hook 是「強制執行」

​9. 工具對照：各家專案級指令檔

​10. 自我檢核動手做

​11. 常見誤區

​自我檢核

​來源與延伸閱讀

學習目標

1. `CLAUDE.md` 是什麼、何時載入

2. 放置位置與覆寫層級

3. 該寫什麼、不該寫什麼：跨任務複利原則

4. 長度與 token 預算

結構化分段

5. 模組化：避免單一巨檔

5.1 用 `@path` 匯入

5.2 拆到 `.claude/rules/`

6. 自動記憶：事實型記憶

7. 記憶污染：自動記憶的供應鏈風險

8. 與 Hook 的分工：`CLAUDE.md` 是「請你遵守」，Hook 是「強制執行」

9. 工具對照：各家專案級指令檔

10. 自我檢核動手做

11. 常見誤區

自我檢核

來源與延伸閱讀