Context 工程與 CLAUDE.md 系統論

14.1　為什麼臃腫的 CLAUDE.md 反而讓 Claude 忽略你

第 5 章教過你：CLAUDE.md 是 Claude 每次開工就自動讀進去的「常駐記憶」。正因為它每次都載入，很多人會犯一個直覺上的錯——把所有想得到的規則一股腦塞進去，覺得寫越多、Claude 越聽話。實際上剛好相反。

官方最佳實踐講得很白：臃腫的 CLAUDE.md 會讓 Claude 開始忽略你的指令 ✅官方。原因不難理解——當一份檔案塞了八百行，裡面一半是「Claude 自己本來就會」的常識（例如「請寫乾淨的程式碼」「記得處理錯誤」），真正關鍵的那幾條規則就被稀釋淹沒了。模型每一行都得讀，但分不出哪句是鐵律、哪句是廢話，結果就是整份都打折扣。

所以心法第一條：像修剪程式碼一樣修剪 CLAUDE.md。官方建議的判準很簡單——逐行問自己「這行刪掉，Claude 會不會做錯？」不會，就砍。只留下 Claude 推不出來、非告訴它不可的東西：不可能猜到的自訂指令、跟預設不同的風格規則、測試怎麼跑、這個 repo 的特殊禮儀、環境的怪癖。其餘一律刪掉。

💡 對照：同一個專案，臃腫版 vs 精簡版的差別

# ❌ 臃腫版（節錄）—— 一半是 Claude 本來就會的常識，反而稀釋重點
- 請務必寫出乾淨、可讀、可維護的程式碼
- 記得處理所有的錯誤情況與邊界條件
- 變數命名要有意義，函式要簡短
- 請遵循 SOLID 原則與最佳實踐
- 寫程式時請仔細思考，不要犯錯
- 我們使用 React（後面還有 600 行類似的話…）

# ✅ 精簡版 —— 只留 Claude 猜不到的高訊號資訊（~150 行內）
- 測試：用 `pnpm test`，單檔測試 `pnpm test -- path/to/file`
- 這個 repo 用 Vitest，不是 Jest（常被搞錯）
- API 路由一律要過 zod 驗證，無例外
- commit 訊息用台灣繁中、結尾不加署名
- 改 src/payment/ 之前先問我，那是金流核心

那「精簡」到底要精簡到多少？這裡有個源自 Boris Cherny（Claude Code 的創造者）、再經 Matthias Herbert 整理轉述的實務數字 🌐社群：把 CLAUDE.md 控制在 大約 150 行以內（約 2,500 個 token），Claude 能可靠遵循；再長就開始打折。這是二手轉述的經驗值、不是官方硬性規範，當參考基準就好——當你的 CLAUDE.md 快破 200 行，就該停下來修剪了。

精簡到什麼程度才算「夠」？官方文件其實留了白紙黑字的數字 ✅官方：建議每份 CLAUDE.md 控制在 200 行以內，並直接點名「臃腫的 CLAUDE.md 檔案會讓 Claude 忽略你真正的指令」。這跟上面 Boris／Matthias 那個「~150 行」的經驗值互相印證——一個是官方畫的上限，一個是實務上更早就開始打折的警戒線，兩個數字對得上，不是巧合。

也有更激進的主張。HumanLayer 團隊建議把 CLAUDE.md 壓到 60 行以內，其餘一律搬去 Skills（隨選載入，第 8 章教過）🌐社群。他們的理由值得記下來：前沿模型能穩定遵循的指令數，粗抓大約 150～200 條，而 Claude Code 自己的 system prompt 就已經先用掉大約 50 條。換句話說，你的 CLAUDE.md 不是寫在一張白紙上，是寫在一張已經被填掉三分之一的考卷上，剩下的額度比你以為的少——這也說明了為什麼有些「還沒破官方 200 行上限」的檔案，用起來卻早就感覺不太聽話。

14.2　四層 CLAUDE.md：全域、專案、私密、模組各司其職

第 5 章你建的是「專案根目錄那一份」CLAUDE.md。但其實 Claude Code 會從好幾個層級同時讀取記憶，由廣到窄疊起來，後面的層級可以覆蓋前面的。搞懂這個分層，你才能把「對的規則放對的地方」，順便省 token。

以下這套分層 cascade，是 Boris Cherny 的實務做法（經 Matthias Herbert 整理轉述）🌐社群。原始來源稱它為 5-scope（把模組層再細拆成資料夾與模組兩級），本章按實用簡併成下面這四層；它不是官方文件明列的硬性規格，而是達人歸納出來的好用框架，方向上跟官方的分層機制一致：

規則是「越靠近的層級越優先」（last-scope-wins）：當全域和專案的規則衝突，以專案的為準；專案和模組衝突，以模組的為準。這讓你可以在全域定一個通則，再到特定專案或模組「就地覆寫」例外。

這套分層最實用的一招是把模組知識放進子目錄。假設你的 src/payment/ 有一堆只跟金流有關的規矩，你不必把它塞進根目錄那份每次都載入的 CLAUDE.md（那會佔掉所有任務的 token 預算）；放一份 src/payment/CLAUDE.md，Claude 只有在動到那個資料夾時才載入。通用規則放根目錄、專屬知識放子目錄——既精準又省 context，正好呼應 14.1 的「最小高訊號」原則。

14.3　用 WHAT／WHY／HOW 三段，把 CLAUDE.md 寫得有條理

知道了「放哪裡」，接著是「裡面怎麼排」。一份東拼西湊、想到什麼寫什麼的 CLAUDE.md，自己過幾週都看不懂。Matthias Herbert 提出一個好記的三段框架 🌐社群，把內容分成 WHAT／WHY／HOW，照這個順序排，結構立刻清楚：

這框架的價值不在「規定你非這樣分不可」，而在逼你想清楚每條規則的性質：它是在描述事實（WHAT）、講原則（WHY）、還是給步驟（HOW）？分類的過程本身，就會把重複的、廢話的、放錯地方的內容篩出來——這跟 14.1 的修剪是同一件事的兩面。

14.4　把錯誤寫成規則：Error-to-CLAUDE.md loop

這是大師篇最值得內化的一個習慣，來自 Boris Cherny 👤達人。它的概念一句話就講完：每當 Claude 犯了一個錯，不要只是當場糾正它，而是把「正確做法」寫進 CLAUDE.md，讓這個錯誤永遠不再發生。

差別在哪？如果你只是在對話裡糾正（「不對，這裡要用 X」），這次的記憶下次 /clear 或換 session 就沒了，同樣的錯它還會再犯。但如果你把它沉澱成 CLAUDE.md 裡的一條規則，這條知識就永久化了——而且因為 CLAUDE.md 進了 git，整個團隊、未來每一個 session 都自動受惠。錯誤修一次、受用無限次，這就是它威力所在。

1. 1
   👀觀察

   Claude 犯了一個錯

   例如它用了 Jest 的寫法，但你的專案其實是 Vitest；或它改了一個你不希望它碰的設定檔。

2. 2
   ✋動手做

   把「正確做法」寫進 CLAUDE.md，而不是只在對話裡糾正

   加一條精簡的規則，例如：「本專案測試用 Vitest，不要用 Jest 的 API」。一句話就好，符合 14.1 的高訊號原則。

3. 3
   ✋動手做

   commit 這次的 CLAUDE.md 變更

   讓這條新規則進版控，跟程式碼一起被追蹤、被整個團隊共享。

   ✅ 預期效果

   下次（以及之後每一次）Claude 都會自動讀到這條規則，同一個錯不再重演。隨著時間累積，你的 CLAUDE.md 會越來越貼合這個專案的真實脾氣。

一個延伸用法：當你讓 Claude 長時間自主跑（例如第 22 章的無人值守工作流），這條原則會升級成鐵則——「每一個錯誤都要進 CLAUDE.md」。因為跑得越久、越沒人盯，靠的就是它能從每次失誤裡學到東西、不在同一個坑裡反覆跌倒。

14.5　Context minimalism：一開始就給最少，需要再去拿

前面講的都是「怎麼把 CLAUDE.md 寫好」。這一節談一個更上層、而且在 2026 年明顯轉向的觀念：不只是 CLAUDE.md 要精簡，連你一開始餵給 Claude 的整體 context，都該從「最少」開始。

傳統做法是「怕它不懂，先把所有相關檔案、文件、背景全塞進去」。Boris Cherny 在 2026 年的個人做法則反過來 👤達人：一開始只給目標，加上「自己去拿 context 的手段」（檔案搜尋、MCP 等），其餘讓 Claude 需要時自己抓。他的原話精神是「只告訴模型它需要的，剩下的讓它自己想辦法」。這跟新一代模型（Opus 4.6 之後）越來越會「隱式規劃」有關——它有能力自己決定要去讀哪些檔，你不必先幫它預載。

有趣的是，這個「按需取用」的精神，官方工程部落格也用更系統化的方式講過，叫做 Just-In-Time（即時）Context Retrieval ✅官方：與其前期載入所有資料，不如讓 agent 只保留輕量的識別符（檔案路徑、URL、查詢字串），真正要用時才動態 glob／grep 抓進來。這樣做有兩個好處——避免你預載的資料「過期」（stale），也讓 context window 保持精瘦、不被一堆當下用不到的東西塞爆。

把這節和前面串起來看，你會發現它們是同一個哲學的不同切面：context 是稀缺資源，要花在刀口上。CLAUDE.md 精簡是它、一開始給最少是它、需要再去拿也是它。

14.6　context 蒸餾與外部記憶：清掉雜訊，把進度寫在身外

再會精簡，長時間工作下來，context 還是會慢慢被填滿。這節講三組「清理與保存」的工具，讓你在長 session 裡維持清醒。

第一組是主動管理 context 的指令 ✅官方：/clear 在切換到不相關的任務時，把 context 整個重置（最乾淨）；/compact 在快滿時做定向摘要、保留重點；/rewind（或連按兩下 Esc）從某個檢查點重來；/btw 讓你問一個臨時的側問題、而它不會污染正式的對話歷史。這幾個你在前面章節見過，這裡補一條 2026 年的用法演進：當你發現同一個問題糾正兩次都沒搞定，別在已經被污染的 context 裡硬拗——直接 /clear、重寫一個更好的 prompt，往往比繼續糾纏快得多。

第二組是外部記憶，也就是「把記憶寫在 context 之外」。官方工程部落格提到一種 結構化筆記（structured note-taking）／agentic memory 的做法 ✅官方：讓 agent 定期把待辦、進度寫到一個外部檔案，之後再讀回來。這樣它就能跨越「context 重置」持久記住事情，而不必把所有東西都扛在 window 裡。背後支撐這件事的，是 Anthropic 的檔案式 memory tool（目前 public beta）。

第三組是把上面兩者結合的實戰招式，叫 document-and-clear（先記錄、再清空），來自 Shrivu Shankar 👤達人：面對複雜的多步驟長任務，讓 Claude 先把「目前進度」整理成一份 markdown 檔，然後 /clear 重啟、再讀那份檔接著做。這招專門用來避開長 session 裡 auto-compaction 帶來的品質衰退——與其讓它在越來越糊的 context 裡硬撐，不如主動把進度存到身外、輕裝重啟。

官方工程部落格在講長任務的記憶延續時，其實明確列了三招，你剛學完的前兩招（壓縮、外部筆記）都已經有了，第三招是子代理架構 ✅官方：與其讓主線自己一份份讀完所有資料、把 context 塞爆，不如把「翻資料」這件事外包給子代理——它在自己獨立、乾淨的 context 裡把資料嚼碎，回傳給主線的只有一份濃縮摘要（官方部落格提到的量級大約是 1,000～2,000 token）。細節搜尋和高層判斷因此被切成兩塊，主線的腦袋不會被搜尋過程中的雜訊污染。

這裡有個記帳細節值得知道：子代理不是「免費」的獨立空間。內建的 Explore 和 Plan 這兩個子代理，第 5 章提過為了輕量會刻意跳過 CLAUDE.md；但除了這兩個例外，其他所有子代理（不論內建或自訂）預設都會載入完整一份 CLAUDE.md，只是這份份量算在它自己的 context 額度裡，不會佔用主線一分一毫。子代理拿到的也只是一份簡短的 system prompt 加環境資訊，不是主線的完整對話歷史；回傳給主線的，同樣只有最終文字結果加一小段 metadata，它讀過的原始檔案內容不會逆流回來污染你的主對話。這正是「派一個子代理去做又髒又長的搜尋」划算的原因——貴的、亂的那部分，永遠關在它自己的額度裡不出來。子代理的實戰玩法，第 16 章有完整一章專門講。

壓縮之後，CLAUDE.md 和記憶內容到底「還在不在」，第 5 章 5.8 節已經整理成一張存活對照表，這裡不重複。但還有一個常被搞混、跟壓縮性質不同的機制——快取（cache）——它決定的是另一件事：你「改了」CLAUDE.md 之後，什麼時候才會真的生效。這個困惑幾乎每個用過幾週的人都遇過，下一節專門拆給你看。

14.7　Prompt Caching：為什麼「明明改了 CLAUDE.md」卻感覺沒生效

這是一個幾乎人人都踩過的困惑：對話中途發現 CLAUDE.md 少寫了一條規則，順手打開編輯器補上、存檔，回到 Claude 面前——結果它的行為完全沒變，好像根本沒讀到你剛剛的修改。你開始懷疑是不是自己存錯檔，還是這功能本來就不可靠。其實兩者都不是，答案藏在 prompt caching（提示詞快取）這個機制裡 ✅官方。

Claude Code 為了省時間、省成本，會把每次請求的內容分成三層，越底層的東西變動越少、越適合被快取起來重複利用：

知道「什麼時候會重讀」還不夠，更實用的是知道什麼動作會讓整個快取失效——失效代表下一輪請求變成從頭全量重算，是整個 session 裡最慢、最貴的一次。官方列出的清單 ✅官方：會讓快取失效的動作包括切換 model、切換 effort（推理力氣，第 22 章會細講）、開啟 fast mode、連接或斷開 MCP server（前提是那個伺服器的工具定義原本就在 prefix 裡、沒被延後載入）、啟用或停用含 MCP server 的 plugin、對整個工具下 deny 規則（例如整條擋掉 Bash）、執行 /compact（這是設計上的必然，畢竟摘要出來的是全新內容），以及升級 Claude Code 版本後的第一輪請求。不會讓快取失效的動作則有 /rewind、/recap、切換 permission mode、呼叫 skill 或自訂指令，還有編輯一份「已經被讀過」的檔案。

想親眼確認這個 session 的 token 究竟花去哪、快取幫你省了多少，第 4 章已經教過用 /context 看即時用量——這裡把畫面實際攤開，教你怎麼讀懂它：

💡 /context 的輸出大致長這樣（示意，實際數字每個 session 都不同）

# 依類別列出目前這個 session 的 token 分布
System prompt:        2.6k tokens  (1.3%)
System tools:        17.6k tokens  (8.8%)
MCP tools:              907 tokens  (0.5%)
Custom agents:          935 tokens  (0.5%)
Memory files:           302 tokens  (0.2%)
Skills:                  61 tokens  (0.0%)
Messages:             30.5k tokens (15.3%)
Free space:            114k tokens (57.0%)
Autocompact buffer:     33k tokens (16.5%)

這份範例數字來自社群實測記錄，只是示意，你自己跑出來的比例一定不同 🌐社群，但判讀邏輯是共通的：System tools 佔比異常高，通常代表你裝了很多平常用不到的工具或 MCP；MCP tools／Custom agents 佔比偏高，該回頭想想是不是有掛著沒在用的伺服器或子代理定義；Messages 一路往上爬、Free space 越來越薄，就是該考慮 /compact 或切換任務時 /clear 的訊號——這比憑感覺猜「這個 session 是不是快滿了」準確太多。

14.8　一條總綱：找出「最小的高訊號 token 集」

這章講了這麼多招，其實背後都指向官方工程部落格的同一條指導原則 ✅官方，可以當作 context 工程的總綱記住：

這條原則具體怎麼落實？官方的建議是：讓 system prompt（以及你的 CLAUDE.md）保持在「對的海拔」——夠具體，讓 Claude 知道該怎麼做；又留有啟發空間，不把它綁死到動彈不得。太抽象它會亂猜，太細瑣它會被淹沒，中間那個剛好的高度才是目標。

另一個實作技巧是把內容分段，常見分成這幾塊：背景脈絡（background）、指令（instructions）、工具使用指引（tool-guidance）、輸出格式（output）。分段不是為了好看，而是讓不同性質的資訊各居其位、彼此不打架——這跟 14.3 的 WHAT／WHY／HOW 是同一種「先分類再下筆」的紀律，只是套用在更廣的 system prompt 層級。

這條原則不只用在「怎麼寫 CLAUDE.md 本身」，官方在討論怎麼控制成本時，也給了幾個服膺同一條原則、但發生在 CLAUDE.md 之外的具體戰術，一併整理在這裡：

還有一招更進階，先預告概念，細節留給第 19 章 Hooks：與其讓 Claude 自己讀完一大段測試輸出再判斷有沒有過，不如用一個 PreToolUse hook 在它看到輸出之前先過濾一次。官方給的範例是偵測到 npm test／pytest／go test 這類指令，自動在指令尾巴接上「只留 FAIL／ERROR 那幾行」的過濾管線，把原本可能上萬 token 的完整測試輸出，壓成只剩失敗片段的幾百 token。這跟這章從頭到尾講的道理是同一件事——訊噪比才是重點，能在「進 context 之前」就把雜訊濾掉，永遠比塞進去再指望 Claude 自己挑重點划算。

讀到這裡，回頭看 14.1 到 14.7，你會發現它們全是這條總綱的分身：精簡 CLAUDE.md、分層放置、按需取用、主動清理、看懂快取、把細節交給 Skills——每一招都在做同一件事，把寶貴的 context 留給真正高訊號的東西。

14.9　Specs-Before-Code：先寫 spec，讓 Claude 訪談你

最後一節，把 context 工程往前推一步：在開始寫任何 code 之前，先把「要做什麼」整理成一份規格文件（spec）。這是 Addy Osmani（前 Google Chrome 團隊）大力推廣的做法 🌐社群。

流程是這樣：動手前先跟 Claude 一起腦力激盪需求，讓它對你提出澄清問題，把模糊的地方問清楚，再一起編出一份完整的 spec.md——涵蓋需求、架構、資料模型、測試策略。這份 spec 的價值在於：它讓「人腦裡的想法」和「AI 的理解」在動工前就對齊，避免做到一半才發現雙方想的根本是兩回事。

💡 一份 spec.md 的骨架長這樣（依你的專案調整）

# spec.md — 功能規格

## 需求（要做什麼、給誰用、解決什麼問題）
- ...

## 架構（用什麼技術、怎麼拆模組）
- ...

## 資料模型（有哪些資料、欄位、關聯）
- ...

## 測試策略（怎麼驗證它真的做對了）
- ...

## 不做什麼（Out of scope，明確劃清邊界）
- ...

官方也有對應的進階做法 ✅官方：面對一個大功能，從最小的 prompt 開始，請 Claude 用 AskUserQuestion 來正式訪談你——把技術實作、UI/UX、邊界情況、各種取捨都問過一輪，然後寫出一份能獨立看懂的 SPEC.md。一份好的 spec 會點名要動到哪些檔案和介面、講明哪些「不做」、並以「怎麼做端到端驗證」收尾。

為什麼把 spec 放在「Context 工程」這一章收尾？因為一份好的 spec，本質上就是為整個任務準備的、最高訊號的 context。你前面學的所有精簡與分層心法，到這裡匯流成一句話：與其讓 Claude 在模糊指令裡瞎猜，不如花點時間把目標寫清楚——這是你能給它的、最划算的一筆 context 投資。

14.10　小結

這一章把 CLAUDE.md 從「一份記憶檔」升級成「一套系統工程」。核心就一句話：context 是稀缺資源，少即是多。把它收進幾個帶得走的重點：

• 精簡優先：像修剪程式碼一樣修剪 CLAUDE.md，逐行問「刪了會不會出錯」；官方建議 200 行以內、更早開始打折的警戒線約 150 行、更激進的看法是 60 行內都有人主張 ✅官方 👤達人 🌐社群。它是 ~70% 遵循的「建議」，連寫死的規則都可能輸給訓練資料裡的舊慣性，鐵律交給 hook（第 19 章）。
• 放對位置：全域／專案／私密／模組四層各司其職，模組知識放子目錄省 token，越靠近越優先 🌐社群。
• 寫得有條理：用 WHAT／WHY／HOW 三段排版，逼自己想清楚每條規則的性質 🌐社群。
• 把錯誤寫成規則：Error-to-CLAUDE.md loop，犯錯就沉澱成規則、永不再犯，進階可以掛 Stop hook 自動提案（別叫它「Compounding Engineering」）👤達人。
• 一開始就給最少：context minimalism + 即時取用，需要再去抓 👤達人 ✅官方；長任務除了 document-and-clear，官方講的第三招是子代理架構——外包搜尋、只回傳濃縮摘要，主線不被雜訊污染。
• 看懂快取：session 中途改 CLAUDE.md 不會讓快取失效、但也不會生效，要 /clear／/compact／重啟才吃得到新內容；放棄走岔的路用 /rewind 比 /compact 省錢；定期用 /context 看 token 都花去哪 ✅官方。
• 總綱：找出「最小的高訊號 token 集」，MCP 別空掛著燒錢、特定工作流程的細節搬去 Skills、雜訊在進 context 前就濾掉 ✅官方。
• 先寫 spec：動工前讓 Claude 訪談你、寫成 spec.md，這是最划算的 context 投資 🌐社群 ✅官方。

下一章接著講大師篇的另一根支柱——驗證心法：怎麼讓 Claude 拿證據說話、別再「假裝做完了」，順便把這章提到的 auto mode 講透。

動手試試

1. 打開你手邊一個專案的 CLAUDE.md，逐行問「刪了會不會出錯」，把 Claude 本來就會的常識句砍掉，看能瘦下幾行。
2. 找一條「只跟某個子目錄有關」的規則，從根目錄的 CLAUDE.md 搬到那個目錄底下新建的 子目錄/CLAUDE.md，體會一下分層省 token 的感覺。
3. 下次 Claude 犯錯時，別只在對話裡糾正——把正確做法寫成一句規則加進 CLAUDE.md 並 commit，實際跑一次 Error-to-CLAUDE.md loop。
4. 打一次 /context，看看手邊這個 session 的 token 都花去哪；如果 MCP 或 messages 佔比出乎意料的高，試著關掉一個沒在用的 MCP、或 /clear 一次，感受一下差別。
5. （進階）挑一個還沒動工的功能，請 Claude 先對你提出澄清問題、一起寫一份 spec.md，再開始實作，比較看看跟「直接叫它寫」差在哪。