CLAUDE.md 最佳實踐：9 條讓 Claude 不再無視你的規則（2026）
大多數關於 CLAUDE.md 最佳實踐的文章只給你一個範本就宣稱大功告成，但你上週撰寫的檔案可能早已被忽略，而你卻不知其原因。解決方案很少是「添加更多規則」，通常恰恰相反。我們在近期每個客戶專案中都部署了 Claude Code，而這 9 條規則才是真正產生影響的關鍵：符合 Claude 載入檔案方式的層級結構、不可突破的指令預算、AGENTS.md 的決策，以及導致 Claude 在對話中途靜默丟棄你檔案的六個原因。
重點摘要
- CLAUDE.md 是載入 Claude Code 上下文中的專案記憶，請保持在 200 行以內，否則規則開始會被丟棄。
- 檔案由上而下載入：全域、專案根目錄、子目錄（延遲載入）以及 CLAUDE.local.md（個人專用，已加入 gitignore）。
- 如果你也使用 Cursor 或 Copilot，請使用 AGENTS.md；將 CLAUDE.md 符號連結至 AGENTS.md 以同時支援兩者。
- 如果 Claude 無視你的檔案，90% 的情況是因為篇幅過長、表述模糊或缺乏「原因說明」。
CLAUDE.md 實際作用（及其重要性）
簡而言之： CLAUDE.md 是一個 Markdown 檔案，Claude Code 會在每次對話開始時將其作為專案記憶讀取。它不是系統提示詞（system prompt）、鉤子（hook）或技能（skill），而是引導 Claude 朝向團隊規範的建议性上下文。與其說它是文件，不如說它是你的 AI 配對程式設計師真正會閱讀的設定檔。
許多團隊將 CLAUDE.md 寫得像 README。這是第一個錯誤。README 是給人類看的，他們可以略讀和跳過。CLAUDE.md 則是由 Claude Code 在對話開始時全數消耗，每一行都消耗 token 並影響遵循度。它更接近設定檔或一組測試固定裝置（test fixtures），而非一般文件。
這也不是引導 Claude 的唯一方式。**鉤子（Hooks）**執行確定性動作（如格式化、阻止提交）。**技能（Skills）**打包可重複使用的工作流程。CLAUDE.md 介於兩者之間，作為建議性上下文；Claude 會評估它，有時會覆蓋它，如果你寫得太多，它肯定會忘記其中一部分。這種區別是以下所有內容的基礎，也是為什麼 CLAUDE.md 只是 上下文工程 更廣泛實踐中的一個工具，而非萬靈丹。
**規則 #1：將其視為程式碼，而非文件。**進行版本控制。在 PR 中審查它。像重構臃腫模組一樣精簡它。根據 Anthropic 的 CLAUDE.md 指南，該檔案的載入優先級與任何系統指令相同，這意味著六個月前的過時規則今天仍在積極塑造每個回應。
CLAUDE.md 如何載入：四層階層結構
簡而言之： Claude Code 從四個層級載入 CLAUDE.md：全域（
~/.claude/CLAUDE.md）、專案根目錄、用於個人覆寫的CLAUDE.local.md，以及僅在 Claude 讀取該目錄內檔案時才延遲載入的子目錄檔案。同級子目錄永遠看不到彼此的 CLAUDE.md，這使得 claude code 記憶保持緊密範圍。
層級結構是 CLAUDE.md 中最被誤解的部分，也是前 5 大搜尋引擎結果頁面（SERP）中沒有任何一個深入探討的地方。以下是底層實際發生的情況：
| 層級 | 位置 | 載入時機 | 範圍 | Git 狀態 |
|---|---|---|---|---|
| 全域 | ~/.claude/CLAUDE.md | 對話開始 | 你機器上的所有專案 | 個人專屬 |
| 專案根目錄 | ./CLAUDE.md | 對話開始 | 整個儲存庫 | 已提交 |
| 本機 | ./CLAUDE.local.md | 對話開始 | 此檢出版本，你的機器 | 手動加入 gitignore |
| 子目錄 | ./frontend/CLAUDE.md 等 | 延遲載入，當 Claude 讀取該目錄中的檔案時 | 該子樹 | 已提交 |
有兩個術語值得釐清：延遲載入（lazy loading）和同級隔離（sibling isolation）。
延遲載入意味著子目錄的 CLAUDE.md 不會進入 Claude 的上下文，直到 Claude 實際打開該目錄內的檔案。如果你問「修復登入錯誤」且 Claude 只觸及 backend/，那麼你的 frontend/CLAUDE.md 永遠不會載入。這很好，它保持了上下文視窗的乾淨，但這會讓那些將關鍵規則放在子目錄中並期望它們始終生效的團隊吃苦頭。
同級隔離是其推論：frontend/CLAUDE.md 和 backend/CLAUDE.md 永遠不會互相載入。它們只共享專案根目錄中的內容。因此，如果你的前端規則與後端規則衝突，那沒問題。如果它們需要共享某個規範，請將其提升至根目錄檔案。
CLAUDE.local.md 是逃生艙口。它會被載入但不會提交，非常適合「我偏好 pnpm 但團隊標準化使用 npm」這類覆寫。缺點是：它不會自動加入 gitignore。你必須自行添加。忘記這一點，你就會將個人規則提交到團隊的儲存庫中。
規則 #4：將指令匹配到 Claude 實際讀取的位置。 React 元件的樣式規則應位於 frontend/CLAUDE.md，而非根目錄。資料庫遷移規則應位於 backend/。Anthropic Memory 文件（2025 年 11 月更新）確認了這一點，延遲載入行為是有意為之且至關重要的。
CLAUDE.md 中該放什麼（以及該省略什麼）
簡而言之： CLAUDE.md 中應包含任何 Claude 無法從你的程式碼中推斷出的內容：建構命令、命名規範、團隊曾踩過的反模式，以及每條規則背後的原因。省略 README 中已有的內容、
package.json中的內容，以及每週變化的任何規則。claude code 指令應具備可測試性和具體性。
這是一個真正發揮作用的極簡 CLAUDE.md：
# Project: techsy-app
## Commands
- Build: `pnpm build` (Turbopack — Webpack flags don't apply)
- Test: `pnpm test --run` (we use Vitest, not Jest)
- Lint: `pnpm lint` (will fail CI on warnings, not just errors)
## Conventions
- Server components by default. Add `'use client'` only when truly needed.
Why: we hit 8s LCP last quarter from over-clienting.
- Database access only via `lib/db/` helpers — never raw SQL in routes.
Why: row-level security policies live in those helpers.
- Tests colocate as `*.test.ts` next to the file under test.
## Don'ts
- Don't add a new dependency without opening a PR comment first.
- Don't use `any` — use `unknown` and narrow.
## Where to look
- Schema: `db/schema.ts`
- Auth flow: `lib/auth/README.md`現在將其與大多數團隊發布的反模式版本進行比較：
# Project Rules
- Write clean, maintainable code.
- Follow best practices.
- Use TypeScript properly.
- Make sure tests pass.
- Be consistent with existing patterns.
- Document complex logic.第二個檔案並非錯誤。它只是無用。Claude 已經想要編寫乾淨的程式碼。「保持一致」並沒有告訴 Claude 要與哪個模式保持一致。Anthropic 工程師 Boris Cherny 的公開範例強烈傾向於第一種風格：具體的命令、命名的工具，以及僅從程式碼庫本身無法顯見的決策背後的原因。
規則 #2：要具體，不要空泛願景。「編寫乾淨的程式碼」是空泛願景。「預設使用伺服器元件；僅在真正需要時添加 'use client'」則是可測試的。同樣的紀律支撐著良好的 提示工程：無論存在於提示詞還是 CLAUDE.md 中，具體、可測試的指令都勝過模糊的願景。
規則 #3：解釋每條規則重要的原因。「原因」並非廢話，它是 Claude 決定邊緣情況的方式。帶有原因的規則（「我們因過度使用用戶端元件導致 LCP 達到 8 秒」）可以推廣到類似情況。沒有原因的規則在上下文轉變時會被忽略。這種模式也記錄在 Builder.io 的 CLAUDE.md 指南 中。
為什麼 Claude 無視你的 CLAUDE.md？指令預算
簡而言之： Claude 並非惡意，它只是注意力耗盡。超過大約 80 行，你會注意到規則開始丟失；超過 200 行，大塊內容會被完全忽略；超過 500 字的密集規則，遵循度就會崩潰。解決方案是建立指令預算。將每一行視為對 claude code 記憶和單條規則遵循度的成本。
近期研究證實了生產環境用戶不斷發現的事實：指令遵循能力隨規則數量增加而非線性下降。關於指令遵循能力的 arxiv 論文 2507.11538 顯示，隨著規則堆疊，單條規則的遵循度會下降，而 HumanLayer 的分析 也呼應了這一發現。
翻譯過來就是：你添加的每一條規則都會使其他每條規則被遵循的可能性略微降低。因此，400 行的 CLAUDE.md 並非比 100 行的有效 4 倍。它往往更無效，因為你真正關心的規則被你三個月前某個週五寫下卻從未刪除的規則稀釋了。
在我們的 CLAUDE.md 檔案中，超過第 150 行的內容開始明顯失去遵循度。到了第 250 行，我們曾見過 Claude 跳過整個章節。所以我們設定了上限。
wc -l CLAUDE.md這就是整個工具。執行它。如果你超過 200 行，你就超支了。我們提供給客戶的硬性規則：
將 CLAUDE.md 視為 200 行的預算。每一行都消耗遵循度。將資源花在刀刃上。
**強化規則 #1：保持簡短。**低於 200 行。低於 500 字的密集規則。如果你發現自己想添加自動化規則（「編輯後始終運行 prettier」），這些可能應該放在 Claude Code hooks 中，hooks 是確定性的，且不消耗指令預算 token。
應該使用 CLAUDE.md、AGENTS.md、.cursorrules 還是 copilot-instructions？
簡而言之： 如果你只使用 Claude Code，CLAUDE.md 即可。如果你使用兩個或更多代理 CLI（Codex、Cursor、Copilot、Sourcegraph），請切換到 AGENTS.md 並將 CLAUDE.md 符號連結至 AGENTS.md。AGENTS.md 於 2025 年底作為跨工具標準出現，大多數現代代理都會回退使用它，因此單一檔案即可供給整個生態系統。
這是前 5 大結果中沒有任何一個實際回答的問題。以下是矩陣：
| 檔案 | 工具 | 範圍 | 何時使用 | 回退機制 |
|---|---|---|---|---|
CLAUDE.md | Claude Code | 每專案 + 全域 | 僅使用 Claude Code 的團隊 | Claude 僅讀取此檔案 |
AGENTS.md | OpenAI Codex, Cursor, Sourcegraph, Factory, Google | 每專案 | 使用 2+ 個代理 CLI | 大多數代理回退使用它 |
.cursorrules | Cursor | 每專案 | 僅使用 Cursor 或作為 Cursor 特定補充 | 僅限 Cursor |
.github/copilot-instructions.md | GitHub Copilot | 每專案 | 僅使用 Copilot | 僅限 Copilot |
雙目標技巧只需一行：
ln -s AGENTS.md CLAUDE.md就這樣。現在 Claude Code、Codex 和任何感知 AGENTS.md 的工具都會讀取同一個檔案。更新一次，每個代理都會獲取。AGENTS.md 規範 是開放且刻意簡約的，它只是帶有慣用章節的 markdown。
兩個現實世界的細節。第一：如果你的團隊有 Cursor 重度用戶，Cursor 的 .cursorrules 採取不同的方法，單一檔案，無層級結構，格式更嚴格。一些團隊同時保留兩者：AGENTS.md 用於共享規則，.cursorrules 用於 Cursor 特定的怪癖。第二：Copilot 的 .github/copilot-instructions.md 不會回退到 AGENTS.md，因此重度使用 Copilot 的團隊需要單獨的檔案。
如果你從零開始選擇代理堆疊，我們的 Claude Code vs Cursor vs Copilot 分解涵蓋了使用層面的權衡取捨。簡短版本：Claude Code 的層級結構對於 monorepo 最強大，Cursor 的 UX 在單獨作業時獲勝，Copilot 的 IDE 整合在漸進式採用方面仍然最順暢。
**規則 #9：如果你運行多個代理 CLI，請使用 AGENTS.md。**不要維護兩個說著同樣事情的檔案。選擇你堆疊中大部分工具讀取的檔案，並符號連結其餘檔案。
CLAUDE.md vs Hooks vs Skills：決策三角形
簡而言之： **CLAUDE.md = 建議性上下文。Hooks = 確定性動作。Skills = 打包的能力。**選錯工具，你會將指令預算浪費在應該由 hook 處理的事情上，或者為只有 skill 才能交付的內容編寫 CLAUDE.md 規則。這個三角形是保持 CLAUDE.md 精簡的最便宜方式。
三個工具，三種工作。我們最常看到的錯誤：將「編輯後始終運行 prettier」放入 CLAUDE.md。Claude 讀取了它。Claude 有時運行 prettier。你很沮喪。解決方法是將該行從 CLAUDE.md 移出並放入 hook，因為 hooks 每次都會確定性地觸發，沒有建議性的迴旋餘地。
| 使用案例 | 工具 | 原因 |
|---|---|---|
| 儲存時運行 prettier | Hook | 確定性，必須始終發生 |
| 使用 2 空格縮排 | CLAUDE.md | 建議性樣式偏好 |
| 使用我們的配置運行測試管道 | Skill | 可重複使用的打包工作流程 |
| 阻止提交到 main | Hook | 硬性規則，無協商餘地 |
| 偏好函數式元件而非類別 | CLAUDE.md | Claude 評估的樣式指導 |
| 生成 Sanity schema | Skill | 帶有資產的多步驟能力 |
如果規則必須始終觸發，它屬於 hook。如果是 Claude 可以針對上下文評估的樣式偏好，它屬於 CLAUDE.md。如果是帶有打包資產（模板、腳本、提示詞）的多步驟工作流程，它屬於 skill。
**規則 #8：正確選擇 CLAUDE.md vs hooks vs skills，將 hook 放入 CLAUDE.md 是指令預算最常见的浪費。**使用 Claude Code hooks 配置確定性動作，並將可重複使用的工作流程打包為 Claude skills。你的 CLAUDE.md 變得更短，你的防護欄更堅固，Claude 停止「忘記」重要的規則。
Monorepo 模式：嵌套 CLAUDE.md、@imports 和 .claude/rules/
簡而言之： 在 monorepo 中，保持根目錄 CLAUDE.md 極小，僅包含指標和共享規範。將具體內容推送到
apps/*/CLAUDE.md，以便每個子樹擁有範圍限定的規則。使用 @imports 透過.claude/rules/共享模組化規則檔案。這是漸進式揭露，Claude 僅在相關時提取每個部分。
典型的 monorepo CLAUDE.md 樹狀結構：
.
├── CLAUDE.md # 30 lines — points to subdirs and shared rules
├── .claude/
│ └── rules/
│ ├── style.md
│ ├── testing.md
│ └── security.md
├── apps/
│ ├── web/
│ │ └── CLAUDE.md # Next.js-specific rules
│ └── api/
│ └── CLAUDE.md # Fastify-specific rules
└── packages/
└── shared/
└── CLAUDE.md # Library author rules@import 語法允許根目錄檔案拉入共享規則區塊而無需重複聲明：
# Root CLAUDE.md
This is a Turborepo. See subdir CLAUDE.md for app-specific rules.
@import .claude/rules/style.md
@import .claude/rules/testing.md
@import .claude/rules/security.md
## Top-level commands
- `pnpm dev` runs all apps in parallel
- `pnpm test` runs every workspace's test script這是實踐中的漸進式揭露。根目錄檔案是一個 30 行的指標。每個子目錄 CLAUDE.md 添加 50–80 行的聚焦規則。.claude/rules/ 檔案持有多个子目錄可以拉入的規範區塊。沒有重複，沒有遺漏，沒有任何單一檔案超過指令預算。
前面提到的延遲載入規則在這裡更重要：當 Claude 處理 apps/web/Button.tsx 時，它看到根目錄檔案加上 apps/web/CLAUDE.md 加上 @import 引入的規則檔案。它看不到 apps/api/CLAUDE.md。這就是重點，後端規範不會污染前端上下文，你的上下文視窗保持可用。
規則 #6：使用 @imports 保持根目錄檔案在 200 行以內。 Anthropic Claude Code 最佳實踐 指南將此視為標準 monorepo 模式。子代理也會繼承父級 CLAUDE.md 上下文，如果你嵌套工作流程，這點值得注意，請參閱 上下文工程 了解其如何與子代理設計互動。
Claude 無視你檔案的 6 個原因（及各自的修復方法）
簡而言之： 當 Claude 無視 CLAUDE.md 時，幾乎總是以下六個原因之一：檔案過長、措辭模糊、缺少「原因」、上下文壓縮、與父級檔案衝突或檔案名稱錯誤。每個都有 60 秒的修復方法。每次更改後在新對話中測試，這就是規則 #7。
1. 檔案過長（>200 行 / >500 字）
運行 wc -l CLAUDE.md。如果超過 200，積極修剪。將自動化規則移至 hooks。將工作流程移至 skills。將共享區塊拆分到 .claude/rules/ 並使用 @import 拉入。Claude「停止遵循」你規則的最常見原因是檔案隨著時間變得過長，遵循度靜默崩潰。
2. 措辭模糊（「編寫乾淨的程式碼」）
將每個空泛願景規則替換為具體、可測試的規則。「保持一致」對 Claude 來說是隱形的。「預設使用伺服器元件；僅在表單或互動式 UI 中添加 'use client'」是 Claude 實際可以應用的內容。
3. 缺少「原因」
沒有原因的規則無法推廣。Claude 無法推斷何時可以彎曲規則，因為它不知道該規則旨在保護什麼。每個非顯而易見的規則都獲得一行說明：「我們使用 unknown 而非 any，因為上季度我們有三次因 API 回應被類型化為 any 而導致的運行時崩潰。」
4. 上下文壓縮將其丟棄
長對話觸發壓縮，Claude 總結早期上下文以適應視窗，CLAUDE.md 內容有時會被總結到消失。修復方法：在大量消耗上下文後使用 /clear，或完全重新啟動對話。這正是 GitHub Issue #17530 不斷浮現的問題。
5. 與父級 CLAUDE.md 衝突
全域說「使用 4 空格」。專案根目錄說「使用 2 空格」。子目錄什麼都沒說。Claude 選擇其中一個，有時是錯誤的那個。審查 ~/.claude/CLAUDE.md 和專案根目錄是否存在矛盾。更具體的那個應該勝出，但前提是你明確指出這一點。
6. 檔案位置或檔案名稱大小寫錯誤
在 Linux 和 macOS 上，Claude.md 和 CLAUDE.md 是不同的檔案。claude.md 和 CLAUDE.md 也是如此。確認路徑確切為 ./CLAUDE.md（全大寫），並確認 Claude Code 是從包含該檔案的目錄啟動的。GitHub Issue #668 充滿了檔案存在但由於路徑問題 Claude 無法看到的案例。
**規則 #7：在新對話中測試。**任何 CLAUDE.md 更改後，開啟新對話並要求 Claude「總結 CLAUDE.md 中的規則」。如果總結遺漏了某些內容，則檔案未發揮作用。
10 分鐘內完成你的第一個 CLAUDE.md：5 步入門
簡簡而言： 運行
/init種子草稿，將其修剪為 6–10 條帶有原因的真正規則，添加 3 個 Claude 應該知道的命令，添加 2 個團隊曾遇到的反模式，然後在新對話中要求 Claude 總結檔案以進行測試。總時間：約 10 分鐘。這 5 步食譜是我們每個新儲存庫第一天使用的方法。
-
運行
/init種子草稿。 Claude Code 的/init命令掃描你的儲存庫並編寫starter CLAUDE.md。不要直接發布它寫的內容。/init輸出是起點，而非完成品，坦白說，它生成的內容大部分可以刪除。 -
**將其修剪為 6–10 行帶有原因的實際規則。**刪除任何通用內容。刪除 README 中已有的內容。僅保留 Claude 無法從程式碼本身推斷的規則。
-
**添加 3 個 Claude 應該知道的命令。**建構、測試、lint。包含確切命令和任何非顯而易見的標誌。如果你使用 Vitest 而非 Jest，請說明。
-
**添加 2 個該團隊曾遇到的反模式。**真實的案例。「不要使用
any，因為我們有三次運行時崩潰」每次都勝過「正確使用 TypeScript」。 -
**開啟新對話並驗證。**要求 Claude「總結 CLAUDE.md 中的規則」。如果它遺漏了某些內容，則檔案過長、過於模糊或缺少「原因」。修復並重複。
規則 #5：不要僅依賴 /init 自動生成。 /init 是起點，而非完成品。你花費 8 分鐘修剪它的過程才是價值所在。
常見問題
什麼是 CLAUDE.md 檔案？
CLAUDE.md 檔案是一個 Markdown 檔案，Claude Code 會在每次對話開始時將其作為專案記憶讀取。它告訴 Claude 你的規範、命令和反模式，這樣它就不必猜測。它在四個層級運作：全域、專案根目錄、子目錄（延遲載入）以及你保持 gitignore 的個人 CLAUDE.local.md。
CLAUDE.md 檔案應該多長？
低於 200 行且低於 500 字的密集規則。超過這些閾值，Claude 的指令遵循能力會下降，你添加的每條規則都會使其他每條規則被遵循的可能性略微降低。將其視為固定預算。如果你需要更多，拆分為子目錄 CLAUDE.md 檔案並使用 @import 獲取共享區塊。
我應該把 CLAUDE.md 放在哪裡？
主要的放在你的專案根目錄（./CLAUDE.md）並提交。在 monorepo 中為應用程式特定規則添加子目錄 CLAUDE.md 檔案。將跨專案偏好放在 ~/.claude/CLAUDE.md。使用 CLAUDE.local.md 用於你不想提交的個人覆寫，但記得手動將其加入 gitignore。
為什麼 Claude 無視我的 CLAUDE.md？
90% 的情況是以下三者之一：檔案過長（超過 200 行）、規則模糊（「編寫乾淨的程式碼」）或規則缺少 Claude 可用於應用它們的「原因」。運行 wc -l CLAUDE.md，然後審查具體性。通過要求 Claude 總結檔案，在新對話中測試更改。
我應該使用 CLAUDE.md 還是 AGENTS.md？
如果你的團隊只使用 Claude Code，堅持使用 CLAUDE.md。如果你使用兩個或更多代理 CLI（Codex、Cursor、Sourcegraph），切換到 AGENTS.md 並將 CLAUDE.md 符號連結至它：ln -s AGENTS.md CLAUDE.md。大多數現代代理 CLI 回退使用 AGENTS.md，因此一個檔案即可供給每個工具。
我應該運行 /init 來生成 CLAUDE.md 嗎？
是的，作為草稿。不，作為完成品。/init 掃描你的儲存庫並產生 starter，但它冗長且通用。Anthropic 和 HumanLayer 都建議在運行 /init 後積極修剪。你花費 8 分鐘刪減和添加「原因」行的過程才是檔案真正變得有用的地方。
CLAUDE.md 檔案在 monorepo 中如何運作？
根目錄 CLAUDE.md 保持極小，僅包含指標和共享規則。每個應用程式獲得自己的 apps/*/CLAUDE.md，帶有範圍限定的規範。子目錄檔案僅在 Claude 讀取該子樹內的檔案時延遲載入，因此同級保持隔離。使用 @import .claude/rules/style.md 共享模組化規則區塊，而無需在各個應用程式間重複它們。
CLAUDE.md、hooks 和 skills 之間有什麼區別？
CLAUDE.md 是建議性上下文，Claude 讀取它並通常遵循它。Hooks 是始終觸發的確定性動作（格式化、阻止提交）。Skills 是用於帶有資產的可重複使用工作流程的打包能力。使用 CLAUDE.md 進行樣式指導，使用 hooks 進行硬性規則，使用 skills 進行你將在各個專案中重複的多步驟工作。
Techsy 的方法
在 Techsy，我們發布的每個 Claude Code 專案都有一個低於 150 行的 CLAUDE.md 和一個 AGENTS.md 符號連結。我們將該檔案視為程式碼，進行版本控制，在 PR 中審查更改，並在合併前在新對話中重新測試。需要幫助將 AI 代理接入你的開發工作流程嗎？獲取免費諮詢。