CLAUDE.md 並非寫得越長越有效。反而越長，Claude 對 CLAUDE.md 的遵從性越差。

把 100 行的 CLAUDE.md 縮短到 35 行，並把其餘內容分離到 .claude/rules/。在相同指示下，後者的 Claude 輸出品質明顯更高。

本文基於官方規格說明為何會如此，並提出「保留哪行、移到哪裡、刪掉哪行」的逐行設計方法論。

CLAUDE.md 的注入機制 — 為何會「被埋沒」

作為使用者訊息（User Message）被注入的事實

官方文件寫道：

CLAUDE.md adds the contents as a user message following Claude Code's default system prompt.
— Claude Code Memory Documentation

CLAUDE.md 不是系統提示（System Prompt）的一部分，而是會在預設系統提示之後以「使用者訊息」的形式被加入。啟動時除了 CLAUDE.md，還會讀入 auto memory、MCP tool names、skills 列表等多個啟動上下文。

「作為使用者訊息」這個事實，是效果衰減的根本原因。

造成衰減的 4 個機制

CLAUDE.md 效果變弱並非單純因為「變舊」，而是四個機制疊加作用。

1. 位置偏差（Recency Bias）
   LLM 不會將所有 token 平等對待，會偏重較近期的發話。50 回合之前的 CLAUDE.md，相對於最新的使用者指令會變得較不重要。

2. 注意力稀釋（Attention Dilution）
   隨著上下文中的 token 數增加，分配給每個 token 的注意力被稀釋。CLAUDE.md 的 30 行所獲得的注意力，會在數千 token 的對話歷史中被攤薄。

3. 指令競合（Instruction Drift）
   當會話中累積了像「這次省略測試」「這部分例外處理」等臨時指示時，這些會與 CLAUDE.md 的原始方針產生衝突。LLM 通常優先直近指示，導致原有規則實質上被覆寫。

4. 摘要與壓縮的影響（Summarization / Compaction）
   Claude Code 會對長對話進行內部壓縮（compact）。在此過程中，CLAUDE.md 的內容可能被摘要，細節與語氣容易遺失。

回合數與效果的關係

以下為實務觀察的經驗值，會依專案複雜度與 CLAUDE.md 行數而變動。

• ~10 回合：幾乎維持。CLAUDE.md 的指示通常被遵守。對策：無特別需求。
• 10 ~ 30 回合：輕微偏差。細節規則可能開始不被嚴格遵守。對策：在會話中重新提示重要規則。
• 30+ 回合：明顯下降。即使是行為原則層級的指示也可能被忽略。對策：分割會話或在 /compact 後重新確認。

官方文件雖建議「CLAUDE.md 檔案每檔案應低於 500 行」，但實務上行數愈少通常能提高遵從度。本記事把此性質整理為「注意力資源的分配」。

CLAUDE.md 的每一行都有注意力成本

CLAUDE.md 的每行都會消耗 Claude 有限的注意力資源。比起行數本身，重要的是「每行能帶來多少判斷改善」。

注意力成本值得投入的行

## 技術堆疊
- Next.js 15 (App Router)          ← 效果：極高。可阻止生成以 Pages Router 為前提的程式碼
- TypeScript 5.7 (strict mode)     ← 效果：高。避免 any，產生型別安全的程式碼

指定技術堆疊與版本的描述，每行的效果通常最高。只要寫上「Next.js 15」，Claude 就會以 App Router、Server Components、Server Actions 為前提來生成程式碼。

注意力成本不值得投入的行

## 程式碼風格
- 縮排使用 2 個空格              ← 效果：低。可由 Prettier 自動修正
- 需加分號                      ← 效果：低。可由 ESLint 自動修正
- import 按字母順序排列         ← 效果：低。可由 eslint-plugin-import 自動修正

可以由 linter/formatter 強制的規則，放在 CLAUDE.md 的優先度較低。就算 Claude 一開始寫得不符合規範，保存時自動修正即可，沒有必要消耗稀有的注意力資源。

（官方範例中也會列出如 Use 2-space indentation 的範例。在未導入 linter 的專案中此類規則仍有價值，但在已導入自動化工具的環境中，應把注意力行數留給更重要的指示。）

最被忽略但效果最高的行

## 行為原則
- 三步以上的任務必須以 Plan 模式開始

這一行的效果非常顯著。它能從根本上避免 Claude 在處理複雜任務時，未做規劃就直接開始寫程式，導致途中崩潰。

- 不要在未閱讀程式碼的情況下就開始寫。務必先查看既有程式碼再進行修改

同樣地，這能防止 Claude 忽略既有實作而另起爐灶的問題。

總結：相比技術堆疊或程式碼風格，行為原則在每行所帶來的效果往往更高——這是實務經驗中最重要的發現。

應該寫入 CLAUDE.md 的行、應該移出的行

應該保留（寫在 CLAUDE.md 中）

應該移出（放到 .claude/rules/）

不該寫（也不放任何地方）

Conditional Rules — 即使在會話後半也有效的機制

將可分離的規則放到 .claude/rules/ 目錄中作為接收容器。

為何比 CLAUDE.md 更有效

.claude/rules/ 的檔案會在 Claude 處理「匹配到的檔案」時被注入到當下的上下文中。

紅色的 CLAUDE.md 可能在 50 則訊息前被埋沒，但綠色的 Conditional Rules 會在需要時直接注入到接近的位置，因此在會話後半仍能保持高效。

路徑指定的實作範例

在 .claude/rules/ 中，可透過 frontmatter 的 paths 欄位指定規則適用的目標。paths 使用逗號分隔（CSV 形式）來描述。注意：YAML 陣列（- "..."）在內部解析器中有 bug，會無法正確處理（參見修正 PR）。

.claude/rules/api-validation.md

---
paths: src/api/**/*.ts,src/routes/**/*.ts
---

# API 驗證規範

- 所有端點需使用 Zod schema 實作驗證
- Request body、query 參數、path 參數皆需驗證
- 驗證錯誤回傳 422，並在回應中包含錯誤細節

.claude/rules/react-components.md

---
paths: src/components/**/*.tsx,src/app/**/page.tsx
---

# React 元件規範

- 預設使用 Server Components，"use client" 最小化
- Props 使用 interface 定義，並放在元件上方
- 避免傳入 children 以外的渲染 props

.claude/rules/testing.md

---
paths: "**/*.test.ts,**/*.test.tsx,**/*.spec.ts"
---

# 測試規範

- 測試名稱採「當 X 發生時，會 Y」的格式
- 減少 mock，優先整合測試（integration test）打實際 DB/API
- 測試資料使用工廠函數（factory）生成

如此一來，當 Claude 在寫元件時會自動注入 React 規範，寫測試時會注入測試規範，確保在最合適的時機套用對應規則。

在哪裡寫什麼的判斷表

（以先前的「注意力成本分配」與「條件規則」原則來決定：啟動時必要的放 CLAUDE.md，檔案/情境專屬的放 .claude/rules/，可自動化修正的不要寫。）

行為原則的設計 — 控制 Claude 的思考過程

技術堆疊決定「要做什麼」，而行為原則決定「如何做」。在注意力成本分析中，行為原則是回報率最高的區塊。

應該控制的 3 種行為

1. 要求先做計畫

- 三步以上的任務必須以 Plan 模式開始
- 計畫需包含目的（為何要做）與選擇理由
- 若途中失敗，應停止並重新規劃，而非硬推下去

Claude 有在未做計畫就直接開始寫程式的傾向。對於複雜任務，缺乏計畫常導致設計崩潰及大量返工。

2. 強制驗證

- 未能證明動作正確前，不視為任務完成
- 必須執行測試、檢查日誌，並證明功能正確

「說做完了但其實有錯」的情況常見。強制驗證能大幅降低返工成本。

3. 要求自我管理上下文

- 不要在未閱讀程式碼的情況下就開始寫，務必先確認既有程式碼
- 當上下文剩餘不多時，要主動告知並建議切分任務
- 將大量調研交給子代理（sub-agent）以節省主上下文

當上下文視窗逼近上限時，Claude 常會為了趕進度而犧牲品質。這類規則明確要求：寧可暫停也不要降低品質。

Before / After — 不只是設定，行為會如何改變

Before：沒有行為原則（50 行的 CLAUDE.md）

# MyApp

## 技術堆疊
- Next.js 15 (App Router)
- TypeScript 5.7
- Tailwind CSS v4

## 指令
- npm run dev
- npm run build
- npm test

## 程式碼風格
- 2 空格縮排
- 不使用分號
- 單引號
- 檔名使用 kebab-case
- 元件使用 PascalCase
- 變數使用 camelCase
- 優先 const
- 型別註記必須
- 禁止 any
- 優先使用 interface
- 禁止 default export（頁面除外）
...（以下 30 行程式碼風格）

問題：

1. 將 30 行花在程式碼風格，行為原則為零
2. 多數可由 linter 強制的內容佔大半
3. Claude 的「如何工作」未定義

在這份 CLAUDE.md 下，若要求「新增使用者認證功能」，Claude 往往未先規劃就直接寫程式，設計在途中崩潰，產生數次返工。

After：注意力資源最佳分配（35 行 CLAUDE.md + 多個 rules 檔案）

# MyApp

以 React + TypeScript 建構的任務管理應用，使用 Supabase 作為後端。

## 技術堆疊
- Next.js 15 (App Router)
- TypeScript 5.7 (strict mode)
- Tailwind CSS v4 + shadcn/ui
- Supabase (PostgreSQL + Auth + Storage)

## 指令
| 指令 | 用途 |
|------|------|
| `npm run dev` | 開發伺服器 |
| `npm run build` | 建置 |
| `npm test` | Vitest |
| `npm run e2e` | Playwright |

## 目錄結構
| 路徑 | 角色 |
|------|------|
| `src/app/` | 頁面與 layout |
| `src/components/` | UI 元件 |
| `src/lib/` | 工具函式 |
| `src/types/` | 型別定義 |

## 行為原則
- 三步以上的任務必須以 Plan 模式開始
- 未能證明動作正確前，不視為任務完成
- 不要在未閱讀程式碼的情況下就開始寫
- 變更僅限必要範圍，將影響範圍最小化
- 當上下文逼近上限時要誠實告知

程式碼風格放到 .claude/rules/code-style.md，測試規範放到 .claude/rules/testing.md，安全性擷取到 .claude/rules/security.md。

在相同「新增使用者認證功能」的需求下，Claude 先提出計畫、待確認後再實作、並確認測試通過才標示完成，返工次數為零。

雖然 After 的行數較少，但那 5 行行為原則直接控制了 Claude 的思考流程與工作方式。

人格（Personality）設計 — 定義「想要怎樣的 Claude」

在行為原則中，指定人格與工作風格對輸出影響甚大。即使是同樣的「建立 React 元件」指令，不同的人格會導致不同輸出風格。

人格範例與輸出傾向：

• 最小化（Minimalist）
  最少的 props、最少的 state、不做多餘抽象。
• 重視設計（Quality-oriented）
  顧及邊界情境與型別設計，會自問「有沒有更好的方法」。
• 自主型（Autonomous）
  自發建立周邊型別與工具，報告簡潔、結果導向。
• 陪伴式（Concise / Supportive）
  與使用者互動時會問「這個方法可以嗎？」並分段推進。

沒有絕對正確的組合，依專案階段與任務性質選擇最合適的人格與工作風格。

建議場景與組合：

• 原型階段：Minimalist + Autonomous（偏向速度）
• 產品階段：Quality-oriented + Careful（偏向品質）
• 學習 / 新框架：Mentor + Supportive（偏向教學）
• 程式碼審查：Logical + Fact-checker（偏向精確、需要證據）

實際指定範例

## 行為原則

### 人格：論理型 + 最小化
- 結論優先
- 必須呈現變更的根據
- 說明簡潔，用程式碼說話
- 避免不必要的抽象與過度設計

### 工作風格：重視驗證 + 上下文管理
- 未能證明動作正確前，不視為任務完成
- 不可省略測試執行或建置檢查
- 當上下文逼近上限時誠實告知並建議切分
- 將研究工作委派給子代理以節省主上下文

這組合會產生「邏輯清晰、去蕪存菁且不放鬆品質檢驗」的 Claude。

可複製使用：最小 CLAUDE.md 範本

以下為濃縮後的即用範本，請將 {...} 替換為專案實際內容。

# {專案名稱}

{1–2 行專案概要}

## 技術堆疊
- {框架 + 版本}
- {語言 + 版本}
- {主要函式庫}

## 指令
| 指令 | 用途 |
|------|------|
| `{dev command}` | 開發伺服器 |
| `{build command}` | 建置 |
| `{test command}` | 測試 |
| `{lint command}` | Lint |

## 目錄結構
| 路徑 | 角色 |
|------|------|
| `{src dir}` | {角色} |
| `{components dir}` | {角色} |
| `{lib dir}` | {角色} |

## 行為原則
- 三步以上的任務必須以 Plan 模式開始
- 未能證明動作正確前，不視為任務完成
- 不要在未閱讀程式碼的情況下就開始寫
- 變更僅限必要範圍，將影響範圍最小化
- 當上下文逼近上限時要誠實告知

此範本約 30 行。填入專案資訊並視需要加入人格或工作風格等行為原則，就能產生高效的 CLAUDE.md。

若不想從零開始，我提供支援 40 多種語言與框架的範本與自訂產生器。

CLAUDE.md Builder — 將設計原則工具化

把前述設計原則每次手動套用並不現實，因此我做了 CLAUDE.md Builder 工具，將方法論自動化。

Builder（客製生成）

只需在 8 個步驟中選擇，便會即時生成一份注意力資源最佳分配的 CLAUDE.md。

步驟與選項範例：

• 專案概要：名稱與簡述（選填）
• 基底範本：40+ 類語言/框架（Frontend、Backend、Mobile、Infra、Data/AI、Game、Embedded）
• 使用情境：個人開發 / 團隊 / OSS / 企業 / 原型 / 學習
• 技術熟練度：初學 / 中級 / 高級
• 角色：Tech Lead / 合作者 / Reviewer 等（可複選）
• 人格：論理型 / 最小化 / Mentor 等（可複選）
• 工作風格：重視驗證 / 慎重 / 委派等（可複選）
• 語氣：禮貌 / 隨性 / 簡潔 / 詳細

右側預覽會即時反映選項，方便邊選邊調整。也可直接從範本列表一鍵複製。

總結 — CLAUDE.md 的落點檢查清單

決策準則與建議配置：

• 啟動階段即需且全域適用：放在 CLAUDE.md
• 僅在特定檔案/情境需要：放到 .claude/rules/ 並以 paths 指定
• 可由 Linter/Formatter 自動修正：不要寫入
• 任務專屬步驟：放在 skills

CLAUDE.md 的設計原則一句話總結：「寫得少，但控制更多」。

把 100 行的 CLAUDE.md 縮成 35 行，並把刪掉的內容移到 .claude/rules/。僅此一改，Claude 的輸出品質就會顯著提升。

原文出處：https://qiita.com/nogataka/items/d6c83ea50b82e1c2602c