Vincent5588 Wiki

CLAUDE.md 4 層機制

閱讀時間約 4 分鐘

CLAUDE.md 四層生效機制

CLAUDE.md 不是只有「專案根目錄那一份」——它有四個層級，按優先序疊加生效，理解這個機制才能設計乾淨的 Claude Code 工作流。

四層機制（從低到高）

1. ~/.claude/CLAUDE.md           ← 全域個人偏好
2. {project}/CLAUDE.md           ← 專案手冊
3. {project}/{subfolder}/CLAUDE.md ← 子目錄局部規則
4. # 對話內 inline 內容          ← 臨時最高優先
層位置適合放什麼
L1 全域~/.claude/CLAUDE.md我是誰、語言偏好、工具偏好
L2 專案{repo}/CLAUDE.md該專案的技術棧、規範、業務規則
L3 子目錄{module}/CLAUDE.md該模組特殊規則（如 tests/CLAUDE.md）
L4 對話對話訊息中 # ...本次例外、臨時改變

疊加而非取代：所有層都會被 Claude 讀進上下文，下層規則疊在上層之上。

跟 上下文檔體系 的差異

CLAUDE.md 4 層上下文檔（about-me 等）
作用範圍Claude CodeCowork
檔名固定 CLAUDE.md自由命名（about-me / brand-voice / working-preferences）
觸發Claude Code 啟動自動讀Cowork 透過 Global Instructions 引入

兩者並存——Claude Code 用 CLAUDE.md，Cowork 用上下文檔。

範例：Vincent 的層級配置

L1: ~/.claude/CLAUDE.md
  「Vincent 是年代集團 IT 主管，技術名詞用英文，繁中回答」

L2: {ExamSystem}/CLAUDE.md
  「PAM 系統 .NET 8 + React 19，等第公式單一源在 GradingService」
  「Controller 不得 try-catch 吞例外，DB 操作禁拼 SQL」

L3: {ExamSystem}/Migrations/CLAUDE.md
  「migration 一律 Add_<Feature>_<Date> 命名」

L4: 對話中
  「# 此次只動前端，不要碰後端」

→ Claude 同時看 4 層，下層「migration 命名」覆蓋掉上層通用規則。

為什麼分層而不是 1 個大檔

文章作者強調這是避免「上下文污染」：

  • L1 寫太細 → 每個專案都被無關規則綁住
  • L2 寫太通用 → 每個專案重複貼相同內容
  • 用 L3 子目錄 → 模組專屬規則自動只套用於該目錄

維護建議

規則屬性該放哪層
「我語言偏好繁中」L1（個人，跨專案）
「PAM 系統用 EF Core」L2（該專案）
「前端元件命名 PascalCase」L2 或 L3（前端目錄）
「本次 PR 暫時用某 lib」L4（一次性）

跟 Rules Directory 的關係

兩個機制互補：

  • CLAUDE.md = 「規則的配方」（要怎麼做）
  • Rules Directory = 「規則的目錄」（什麼時候啟用哪份）

詳見 Rules Directory。

對 PAM 工作場景

~/.claude/CLAUDE.md
  「我是年代集團 IT 主管」
  「繁中、技術名詞英文」

ExamSystem/CLAUDE.md  ← 已存在，2400+ 行
  「.NET 8 + React 19 + EF Core」
  「等第公式呼叫 GradingService」
  「事假每小時 -0.125」

ExamSystem/client-app/CLAUDE.md  ← 可加
  「TanStack Query for state、Zustand for auth」
  「禁用 useEffect 抓 API（用 useQuery）」

ExamSystem/Migrations/CLAUDE.md  ← 可加
  「migration 名 Add_<Feature>_<Date>」

相關概念

強連結（原文明確提及）

← 回到 wiki

關係圖譜

反向連結