你的 CLAUDE.md 可能太長了：優化 Claude Code 提示詞的實用指南

讓 Claude 隨處可用，CLAUDE.md 是 Claude Code 尋找指令的方式。啟動時，Claude Code 會從你目前的工作目錄向上遍歷目錄樹，並載入沿途所有的 CLAUDE.md 檔案。例如，在 foo/bar/ 中執行，它會載入 foo/bar/CLAUDE.md 和 foo/CLAUDE.md。

然而，子目錄中的 CLAUDE.md 檔案會在 Claude 第一次讀取、寫入或編輯該子目錄中的檔案時才載入。如果你在一個單一儲存庫（monorepo）中，且其他團隊的 CLAUDE.md 檔案不斷混入，可以使用 claudeMdExcludes 設定來跳過特定檔案。

每個載入的 CLAUDE.md 都會消耗你的上下文。在反模式（antipatern）文章中，我曾說 CLAUDE.md 就像冰箱裡的必需品：牛奶、雞蛋、奶油。Claude 會在每個會話開始時載入它，所以其中的任何內容都會佔用每次對話的空間。

即使在執行 /compact 後，它也會從磁碟重新讀取並重新注入。你無法擺脫它，它就像垃圾郵件一樣：無論你取消訂閱多少次，它們還是會不斷出現。這就是 CLAUDE.md 的全部意義，但這也是問題所在。

Claude Code 的文件稱之為「過度指定的 CLAUDE.md」：如果你的 CLAUDE.md 太長，Claude 會忽略其中一半的內容，因為重要的規則會淹沒在噪音中。Anthropic 的指導方針是將每個 CLAUDE.md 檔案的目標長度設定在 200 行以下：「更長的檔案會消耗更多上下文並降低遵循度」。

claude-code-best-practice 儲存庫也重複了 200 行的目標（它還提到了 HumanLayer，他們將其保持在 60 行左右）。這裡有個反直覺的部分：當 Claude 忽略某條規則時，我的直覺是添加一些內容，然後再添加另一條規則，接著再添加一條更響亮的規則，例如「重要：務必執行測試」……這只會讓檔案更長，加劇問題。

Anthropic 以前確實建議過這種強調方式。他們 2025 年的最佳實踐文章提到調整指令時「用『重要』或『你必須』來加強語氣」。目前的文檔則更為保守：只強調一行，因為「如果你強調許多行，就沒有一行會脫穎而出」。這就像你在一個房間裡，一半的人都在大喊大叫，你什麼都聽不見。如果 Claude 忽略了某條規則，你的 CLAUDE.md 可能太長了，而不是太短。

閱讀「如何編寫有效的 Claude 文檔」，以下是 Anthropic 建議在 CLAUDE.md 中包含和排除的內容：

✅ 包含：Claude 無法猜測的 Bash 指令、與預設值不同的程式碼風格規則、儲存庫禮儀（分支命名、PR 慣例）、專案特有的架構決策、開發者環境怪癖（所需的環境變數）、常見的陷阱或不明顯的行為。

❌ 排除：Claude 可以透過閱讀程式碼理解的任何內容、標準語言慣例、Claude 已知的測試指令和偏好的測試執行器、詳細的 API 文件（改為連結到文件）、經常變動的資訊、冗長的解釋或教學、程式碼庫的逐檔案描述、不言自明的實踐，例如「編寫乾淨的程式碼」。

左欄是 Claude 無法知道的內容。右欄是 Claude 已經知道的，或者只需兩秒鐘用 grep 就能找到的內容。Claude 可以讀取你的 package.json，它不需要你告訴它你使用了 React。對於每一行，請問自己：移除這行會導致 Claude 犯錯嗎？如果不會，就刪除它。

如果 Claude 在沒有被告知的情況下已經做對了某件事，那這行就是多餘的。刪除它，或者如果它真的必須每次都發生，就將其變成一個 Hook。一個好的 CLAUDE.md 看起來會短得無聊。以下是 Anthropic 提供的一個範例：

```

Bash commands

• npm run build: Build the project
• npm run typecheck: Run the typechecker

Code style

• Use ES modules (import/export) syntax, not CommonJS (require)
• Destructure imports when possible (eg. import { foo } from 'bar')

Workflow

• Be sure to typecheck when you're done making a series of code changes
• Prefer running single tests, and not the whole test suite, for performance

```

如果我遺漏了什麼怎麼辦？當我開始使用 Claude 時（一年多前，時間過得真快！），我在網路上找到了一些 CLAUDE.md 範例檔案。我當時不知道自己在做什麼，所以很自然地複製貼上了網路上最全面（也就是最冗長）的 CLAUDE.md 檔案。

它們會說一些「遵循 SOLID 原則，保持 DRY 等」的內容。這些都是好的工程實踐。我的 CLAUDE.md 很快就膨脹成數百行的龐然大物，都是因為我擔心如果我不寫下來，Claude 就會開始輸出垃圾程式碼。

快轉到 2026 年，現在有了 Opus 5.5 和 Fable 5.1。Claude 甚至還需要被告知要遵循 SOLID 原則嗎？我認為它已經足夠聰明，能夠應用這些原則。為什麼要將 Claude 視為一個愚蠢但非常聰明的助手呢？

人們相信它能一次性完成 Mario Kart 遊戲，但不知何故它卻不實踐 SOLID 原則？我認為不是這樣。如果你遺漏了什麼，請不要擔心。Claude 不會因為你忘記寫一行就開始輸出垃圾。

Claude 很聰明（比我聰明多了！）。不要害怕在你的 CLAUDE.md 中遺漏一行。實驗看看遺漏一行是否會產生差異。提示 Claude 構建一些東西，然後移除一些「顯而易見」的良好工程原則，例如你的「遵循 SOLID 原則」。

開始一個新的會話，並給 Claude 相同的提示。比較輸出結果！不要複製網路上最冗長、評價最高的 CLAUDE.md 儲存庫。選擇最能引起你共鳴的那個。更好的是，自己填寫！或者請 Claude 寫你自己的 CLAUDE.md！

具體勝過模糊。模糊的指令會浪費兩次行數：一次是因為它們佔用空間，另一次是因為 Claude 無法依據它們行動。例如，使用「使用 2 個空格縮排」，而不是「正確格式化程式碼」。使用「提交前執行 npm test」，而不是「測試你的更改」。使用「API 處理器位於 src/api/handlers/」，而不是「保持檔案有條理」。

沒有人會不同意「正確格式化程式碼」，也沒有人能遵循它。哪種格式？誰說的？Claude 只會猜測，這與你添加這行之前它所做的沒有區別。一個具體的規則是可驗證的。縮排要麼是 2 個空格，要麼不是。你可以判斷 Claude 是否遵循了它，Claude 自己也能判斷。

如果你的 CLAUDE.md 中的所有內容都真的很有用怎麼辦？那麼就不要把它們都放在一個檔案中。你有幾個選擇，有些比其他的更好。路徑範圍規則：將指令放在 .claude/rules/ 中，每個主題一個 Markdown 檔案，並使用 paths 欄位來限定範圍：

```

---

paths:

• "src/api/**/*.ts"

---

API Development Rules

• All API endpoints must include input validation
• Use the standard error response format
• Include OpenAPI documentation comments

```

上面的範例來自 Anthropic 文檔。這條規則只會在 Claude 讀取、寫入或編輯匹配的檔案時載入。如果你整天都在處理前端，Claude 就不會理會你的 API 規則。請注意，沒有 paths 的規則會在啟動時載入，就像 CLAUDE.md 一樣。請務必限定你的規則範圍！

謹慎使用 @imports。CLAUDE.md 可以使用 @path/to/file 引入其他檔案：

```

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

Additional Instructions

• git workflow @docs/git-instructions.md

```

當我第一次讀到「如果你的指令變得很大，請使用引入來拆分它們」時，我感到很困惑。如果我的 CLAUDE.md 是 199 行，而我引入了另外 100 行，那不就是一個有額外步驟的 299 行 CLAUDE.md 嗎？是的。

文檔現在也這麼說：引入「有助於組織一個長檔案，但不會降低其上下文成本，因為引入的檔案也會在啟動時載入」。引入是為了整潔和共享，它們對長度沒有幫助。路徑範圍規則才有幫助。

不同層級的 CLAUDE.md：你可以在多個層級擁有 CLAUDE.md 檔案：

• ~/.claude/CLAUDE.md：你的個人偏好，適用於每個專案。
• ./CLAUDE.md：專案的共享指令，簽入 Git。
• ./packages/billing/CLAUDE.md：僅適用於程式碼庫該部分的指令，只有當 Claude 在那裡工作時才會載入。

正如 eesel 所說：「將詳細規則放在它們所管轄的程式碼旁邊，這樣可以使範圍更清晰，而不是創建一個巨大的根檔案。」

委託給技能（skills）和 Hook：還有兩個地方可以將內容從 CLAUDE.md 中移出：

• 技能（Skills）：適用於你偶爾才需要的流程，例如「我們如何發布版本」或「如何做筆記」。Claude 只會在相關時才載入技能。
• Hook：適用於你每次都需要執行的事項，例如編輯後執行格式化程式。Hook 不依賴於 Claude 記住規則，它是程式化的，會自動執行。

HTML 註解用於自由文本：區塊級 HTML 註解（<!-- 像這樣 -->）在 CLAUDE.md 注入之前會被剝離。你可以為維護檔案的人員留下註解，而不會消耗 Claude 的任何上下文。

像對待程式碼一樣對待 CLAUDE.md：根據文檔，像對待程式碼一樣對待 CLAUDE.md：當出現問題時審查它，定期修剪它，並透過觀察 Claude 的行為是否實際改變來測試更改。在實踐中：

將其簽入 Git。你的團隊可以像審查任何其他程式碼一樣審查其更改。當 Claude 的行為突然改變時，檢查 git log CLAUDE.md 以查看其歷史記錄。修剪它。規則會過時。關於你六個月前停止使用的函式庫的註解就像變質的牛奶。噁心！

測試它。更改了規則？嘗試之前出錯的任務。如果 Claude 的行為相同，那條規則就沒有任何作用。查看實際載入了什麼。/context 顯示你的會話中包含哪些 CLAUDE.md 和規則檔案。

較新版本的 Claude Code 還具有 /doctor prompt-audit，它會標記對不存在檔案的引用以及相互矛盾的指令。說到矛盾，如果兩條規則不一致，Claude 可能只會選擇其中一條。你擁有的檔案越多，這種情況就越可能發生。這是保持內容簡短的另一個原因。

最後，不要複製網路上的 CLAUDE.md。網路上有很多「終極 CLAUDE.md」檔案。來自 Every 關於複合工程的文章：「你的上下文應該反映你的程式碼庫、你的模式以及你來之不易的經驗教訓。十條你遵循的具體規則勝過一百條通用規則。當規則不再為你服務時，就刪除它們。」

別人的 CLAUDE.md 解決的是別人的錯誤。閱讀它們以獲取想法，但要編寫你自己的。你上次檢查你的 CLAUDE.md 檔案是什麼時候？

將 CLAUDE.md 視為憲法：Diwank 在《Field Notes From Shipping Real Code With Claude》中寫道，將 CLAUDE.md 視為你的程式碼庫的憲法。憲法不會列出每一條法律，它設定了大的原則，將細節留待以後處理。CLAUDE.md 的工作方式相同。

保留塑造整個程式碼庫的決策及其背後的原因。Claude 可以透過閱讀你的程式碼看到你使用了 Postgres，但它無法看到你為什麼選擇它。細節應該更接近程式碼。

使用錨點註解進行特定修正：有些修正只在一個小角落才重要。也許 Claude 不斷破壞 API 契約，或者某個檔案有一個沒人能猜到的慣例。CLAUDE.md 中的一行會載入到每個會話中，即使 Claude 從未接近該檔案。

Julep 的一個好主意根本不在 CLAUDE.md 中，而是錨點註解。在程式碼本身中加入帶有特殊前綴的註解：

```

AIDEV-NOTE: API Contract Boundary - v2.3.1

ANY changes require version bump and migration plan

See: docs/api-versioning.md

@router.get("/users/{user_id}/feed")

async def get_user_feed(user_id: UUID) -> FeedResponse:

...

```

Julep 的 CLAUDE.md 只告訴 Claude 慣例：使用 AIDEV-NOTE:、AIDEV-TODO: 或 AIDEV-QUESTION:，在掃描檔案之前搜尋現有的錨點，當程式碼更改時更新它們，並且在未經詢問的情況下絕不移除 AIDEV-NOTE。這在 CLAUDE.md 中只有幾行，卻取代了可能數百行的內容。

知識不是預先描述程式碼庫的每個脆弱角落，而是存在於它所關聯的程式碼旁邊，Claude 只在處理該部分時才會讀取它。Diwank 將它們稱為路標：「將你的程式碼庫視為一個城市，錨點註解視為路標。」這與路徑範圍規則的想法相同，只是在程式碼內部。