我已經測試過數十種 Claude Code 的設定。
真正能改變產出的只有一個：一個 60 行的檔案，叫做 CLAUDE.md。
把這篇存起來 🔖
接下來你會完整了解它的運作方式、為什麼大多數人完全忽略它，以及你今天就能複製的完整模板。
沒人告訴你的 Claude Code 真相
在你輸入第一個提示之前。在你寫下第一行程式碼之前。在你工作階段中的任何動作發生之前。
Claude 只讀一個檔案。就只有一個。
CLAUDE.md。
而且它會把這個檔案當作整個工作階段的絕對真理。不是建議。不是眾多上下文之一。而是決定它每一步行動的明確指令。
這就是為什麼這個檔案是整個 Claude Code 堆疊中最被低估的變數。
大多數人根本沒有這個檔案。而那些有檔案的人，犯了兩個錯誤之一：要不是內容空洞，就是寫了 300 行的「請扮演一位經驗豐富、逐步思考的資深工程師」。
兩者都沒有用。原因不同。
為什麼大多數 CLAUDE.md 無法發揮作用：3 個真正的原因
原因 1：太長
Claude 在每個工作階段中，能可靠遵循的指令大約是 150 到 200 條。這是結構上的限制，不是它願不願意配合的問題。
問題在於：Claude Code 的內部系統提示已經包含了大約 50 條指令。這表示你的 CLAUDE.md 實際上只有 100 到 150 個指令的空間，超過之後 Claude 就會開始遺漏。
如果你的檔案有 200 行，Claude 不是故意忽略你的規則。而是機械性地忘記了。你遇到的不是遵守問題，而是注意力預算問題。
原因 2：內容不佳
大多數 CLAUDE.md 檔案裡塞滿了 Claude 自己就能推斷出來、或是不會實際改變它行為的東西。
「扮演資深工程師。」→ Claude 早就知道那是什麼意思，而且這不會錨定任何具體行為。「逐步思考。」→ 訓練資料裡就有了。你在浪費一行。「寫出乾淨且可維護的程式碼。」→ 沒有具體標準。Claude 不知道在你們的情境下「乾淨」是什麼意思。
每一行如果無法防止某個具體、實際的錯誤，就是從真正重要的指令那裡偷來的。測試很簡單：如果你刪掉這一行，Claude 會不會在某個具體事情上出錯？如果答案是否定的，那這行就不該存在。
原因 3：完全沒有階層
大多數人忽略了 Claude Code 有三個層級的指令，卻把所有東西塞在同一個地方。
~/.claude/CLAUDE.md→ 全域（適用你所有的專案）.claude/CLAUDE.md→ 專案（與團隊共享，納入 git）./CLAUDE.local.md→ 本機（個人覆蓋設定，被 git 忽略）
全域層級用來放你會在所有專案中重複的規則。專案層級用來放你技術堆疊和團隊特有的上下文。本機層級用來放你個人偏好，不需要跟別人共享。
正確使用這三個層級，才能讓每個檔案維持簡短、專注且真正有效。把所有東西塞進一個檔案，就像做了一個漏斗，讓你的重要規則淹沒在雜訊中。
一個有效的 CLAUDE.md 必備的 5 個區段
在翻閱了數十個在實際生產環境中使用的 CLAUDE.md——包括開源專案、官方 Anthropic 文件、社群最佳實踐儲存庫——之後，以下是所有有效檔案都有的 5 個區段：
區段 1：關鍵指令
Claude 在每次工作階段開始時，都不知道如何建置你的專案、執行你的測試，或修復 lint 錯誤。它會猜。而它的猜測會浪費你的回合。
直接告訴它要打什麼：
指令
- 建置：
npm run build - 開發：
npm run dev - 單一檔案測試：
npm test -- path/to/file - 完整測試：
npm test - Lint 並修正：
npm run lint:fix - 型別檢查：
npx tsc --noEmit
簡短。精確。可直接使用。
沒有這個區段，Claude 可能會在你們專案使用 pnpm vitest 時嘗試 npm test。它會花三個回合除錯一個根本不會成功的指令問題。三個回合，你本來可以用在真正的工作上。
區段 2：架構地圖
Claude 每次工作階段開始時，對你的程式碼庫一無所知。完全不知道。它不知道你的商業邏輯放在哪裡。它不知道你的元件應該是無狀態的。它不知道你的 API 路由不應該包含商業邏輯。
給它一張地圖：
架構
src/lib/services/→ 所有商業邏輯src/components/→ 僅限無狀態 UI 元件src/lib/store/→ 全域狀態 (Zustand)src/app/api/→ API 路由，這裡不要放商業邏輯- 僅能透過 Server Actions 或 API 路由存取資料庫
不需要完整列出你的目錄結構。只要讓 Claude 知道東西放在哪裡，更重要的是，不該放在哪裡。
這個區別——哪裡該放 vs. 哪裡不該放——正是防止最常見架構錯誤的關鍵。
區段 3：嚴格規則
這是整個檔案中最重要的區段。毫無例外。
這裡的每一條規則都必須回答一個問題：「如果我刪掉這一行，Claude 會不會犯一個具體的錯誤？」
如果會 → 規則保留。如果不會 → 它不該出現在這裡。
高價值規則範例：
規則
- 絕對不要提交 .env 檔案或機密
- 所有非同步呼叫必須包在 try/catch 中
- 僅限函式元件，零類別元件
- 強制提交前綴：feat:、fix:、docs:、refactor:
- 每個 PR 必須先通過
npm run verify才能合併 - 僅限靜態輸出，不使用 SSR（部署在 S3 上）
- 重要：每次修改程式碼後都要執行型別檢查
關於這個清單有兩點要注意。
首先，否定規則和肯定規則一樣重要。「絕對不要提交 .env 檔案」是一條看起來理所當然的規則，直到 Claude 真的這麼做的那一天為止。把它放進去。
其次，像「重要」或「你一定要」這樣的強調標記確實有效。
這不是道聽塗說。Anthropic 在他們自己的文件中有確認：在規則前加上「重要」或「你一定要」，能明顯提升 Claude 對那條規則的遵循程度。
謹慎使用：把它們留給那些忽略後果最嚴重的規則。
這個區段不要超過 15 條規則。超過之後，你會稀釋對真正重要規則的注意力。
區段 4：工作流程偏好
你一定經歷過這種事。你請 Claude 修正一行。它卻重寫了三個檔案，重新命名你的函式，還重構了一個跟你的請求完全無關的類別。
這個區段可以防止這種情況：
工作流程
- 開始複雜任務前，先問澄清問題
- 做最小限度的修改，不要重構無關的程式碼
- 每次變更後執行測試，在繼續之前修正失敗
- 每個邏輯變更建立獨立的提交，不要一個巨型提交
- 如果對兩種做法不確定，解釋兩者讓我選擇
這裡的每一行都在回應一個具體的痛點。47 個檔案的巨型提交。未經要求的完整重寫。Claude 獨自做出的架構決策，但它本來應該問你。
區段 5：不要放進 CLAUDE.md 的內容
這個區段和其他區段一樣重要。可能更重要。
不要包含：
- 個性化指令（「擔任資深工程師」）
- 你的 linter 已經處理的格式規則
- 把整個文件拉進每個工作階段的 @ 匯入
- 重複的規則（如果全域說「執行測試」，專案就不用重複）
- Claude 透過自動記憶自己學到的任何東西
最後一點被嚴重低估。
Claude 會在 ~/.claude/projects/<project>/memory/ 中維護自己的筆記。在工作階段中執行 /memory 就能看到它已經學到關於你專案的哪些資訊。經過幾次工作階段後，你常常會發現 Claude 已經記住了你原本打算手動寫進 CLAUDE.md 的內容。
不要把有限的指令浪費在 Claude 已經自己記住的東西上。
完整的模板，不到 60 行，可直接使用
刪除不適用於你專案的區段。目標不是填滿所有東西。目標是只保留那些能實際改變 Claude 行為的內容。
對我的產出影響最大的幾行：具體成果
在測試了數十種設定後，以下五個行帶來了最明顯的差異：
- 重要：每次修改程式碼後都要執行型別檢查 → 防止 Claude 交付型別有問題的程式碼，因為沒有明確提示它就不會檢查。
- 做最小限度的修改，不要重構無關的程式碼 → 防止未經要求的完整檔案重寫。
- 每個邏輯變更建立獨立的提交，不要一個巨型提交 → 防止無法閱讀的 47 個混合檔案的巨型提交。
- 如果對兩種做法不確定，解釋兩者讓我選擇 → 防止 Claude 獨自做出本來應該由你決定的架構決策。
- 僅限靜態輸出，不使用 SSR → 防止 Claude 在靜態部署於 S3 的專案中加入伺服器端程式碼。
這五行有什麼共同點：每一行都防止了一個具體、常見且除錯成本高昂的錯誤。
這是測試你 CLAUDE.md 每一行的終極標準。
根本錯誤以及它為何如此普遍
人們把 CLAUDE.md 當作願望清單或個性化提示。
「要資深。」「要徹底。」「像專家一樣思考。」
這不是一份指令。這是天真的想法。
你的 CLAUDE.md 應該是一份技術文件，不是一場激勵演講。技術堆疊、指令、架構、具體規則、工作流程。其他一切都是雜訊，只會干擾真正重要的指令。
把檔案維持在 80 行以下。每當 Claude 犯了一個你可以預防的錯誤，就修訂它。
最重要的是：了解這個檔案隨著時間會變成什麼。
一個好的 CLAUDE.md 在第一個月就能讓你在每次工作階段中節省時間。到了第三個月，它已經精確地捕捉了你的慣例和技術堆疊，讓 Claude 幾乎像團隊成員一樣運作。
到了第六個月，它包含了 Claude 在這個專案上犯過的所有錯誤，並且自動預防它們。
這個檔案會不斷增值。每一次修正都會讓它變得更好。它會逐漸成為你寫過最棒的入門指令。
不是給 Claude 的。是給你的。
