Claude Code 完整設定指南：CLAUDE.md + Skills + Hooks + Memory 四層架構實戰

你裝了 Claude Code，寫了幾行 CLAUDE.md，然後發現 Claude 有時候還是會忽略你的規則。你加了更多規則，CLAUDE.md 變成 500 行，但問題沒解決——因為你把所有東西塞進了錯誤的層級。

我們的 AI agent fleet（Sage、Mia、Luna、Rex 等 6 個 agents）每天在 CLAUDE.md + Skills + Hooks 的架構上自動運作，從選題、研究、撰寫到發布，全流程無人值守。根據這個第一手經驗，問題從來不是「CLAUDE.md 寫得不夠多」，而是「你沒有把正確的東西放在正確的層級」。

這篇文章會帶你從零建立完整的四層控制架構，每一層該放什麼、不該放什麼，附可直接複製的模板和設定。

TL;DR

• CLAUDE.md 是行為憲法（每 session 全量載入），不是 README——用 global/project/local 三層管理，搭配 .claude/rules/ 做路徑作用域
• Skills 2.0 是可執行模組（on-demand 載入），不是 prompt alias——用資料夾結構（SKILL.md + scripts/ + references/）取代舊版單檔
• Hooks 是唯一能把「建議」變成「強制執行」的機制——PreToolUse 可以 block 工具呼叫，PostToolUse 可以注入驗證結果
• Memory 有三套系統（CLAUDE.md / Auto Memory / Session Memory），混用會讓 Agent 行為不可預測
• 本文附三種場景模板：獨立開發者、團隊、Power User，可直接套用

你以為的 CLAUDE.md 和真實的 CLAUDE.md

大多數人把 CLAUDE.md 當成「給 Claude 看的 README」——放了專案描述、技術棧、幾條 coding style 就覺得設定完成了。

這個理解有根本性錯誤。

CLAUDE.md 是 Claude Code 每個 session 開始就強制全量載入的行為規範層。它不是「希望 Claude 參考」，而是 Claude 在整個對話中持續遵守的最高準則。根據 Anthropic 官方文件，CLAUDE.md 的內容是以使用者訊息的形式注入 context，優先級高於對話中的一般指令。

更關鍵的是，CLAUDE.md 支援三層優先級：

1. Global（~/.claude/CLAUDE.md）：所有專案共用的個人偏好
2. Project（{project}/CLAUDE.md 或 {project}/.claude/CLAUDE.md）：團隊共享的專案規則，commit 進 repo
3. Local（CLAUDE.local.md）：個人覆寫，加入 .gitignore

安全提醒：Project 層的 CLAUDE.md 會 commit 進 git repository 並與團隊共享。絕對不要在 CLAUDE.md 中放置 API 金鑰、token、密碼或任何敏感憑證。需要個人化設定的敏感內容，請使用 CLAUDE.local.md（記得加入 .gitignore）。

更少人知道的進階功能：.claude/rules/ 目錄可以做路徑作用域。你可以建立像 .claude/rules/frontend.md 這樣的檔案，裡面的規則只在 Claude 處理對應路徑的檔案時才載入——匹配邏輯基於子目錄名稱（例如 frontend.md 對應 src/frontend/ 相關檔案）。這讓 CLAUDE.md 從「靜態文件」進化成「動態規則引擎」，大幅減少不相關規則佔用 context 的問題。

根據我們部署 6 個 agents 的經驗：全域 CLAUDE.md 只放「絕對禁止事項」（如禁止虛構事實、禁止特定格式），專案 CLAUDE.md 放工作流程和架構規範，各 agent 的特定行為則用 Skills 和 .claude/rules/ 分流。這種分層讓每個 agent 的 context 效率最大化。

5 分鐘建立你的第一個 CLAUDE.md

如果你從零開始，以下是最小可用模板。在專案根目錄建立 CLAUDE.md：

# 專案名稱

## 技術棧
- Next.js 14 + TypeScript + Tailwind CSS
- 套件管理：pnpm
- 測試：Vitest

## Coding Style
- 使用 functional components，不用 class components
- 變數命名：camelCase
- 檔案命名：kebab-case
- import 順序：React → 第三方 → 本地模組 → 型別

## 禁止行為
- 不要使用 any 型別
- 不要在 component 內直接 fetch data，使用 server actions
- 不要自行發明 utility function，先檢查是否已存在

## 建置與測試
- 開發：pnpm dev
- 測試：pnpm test
- 建置：pnpm build

三個常見誤區：

1. 寫太少：只放專案名稱和技術棧。Claude 從 package.json 就能推斷技術棧——CLAUDE.md 的價值在於放「Claude 從程式碼看不出來的隱性知識」
2. 寫太多：500 行以上的 CLAUDE.md 會浪費大量 context window。官方建議：指令越具體越精簡，Claude 越容易遵守
3. 一次寫完：最有效的方式是「有機成長」——每次 Claude 做出錯誤假設時，告訴它「把這點加入我的 CLAUDE.md」，讓規則反映真實踩過的坑

接著建立全域偏好。建立 ~/.claude/CLAUDE.md：

# 個人偏好

- 回覆使用繁體中文
- commit message 使用英文，格式：type(scope): description
- 不要在程式碼中加入多餘的註解，除非邏輯特別複雜
- 優先使用既有的 library，不要重造輪子

這兩個檔案加起來不到 5 分鐘，但已經能解決「每次 session 重新解釋背景」和「coding style 不一致」兩大痛點。

三層架構全貌：CLAUDE.md + Skills + Hooks + Memory 如何協作

理解四層架構的關鍵不是「每一層能做什麼」，而是「每一層不該做什麼」：

層級	職責	載入時機	不該放的東西
CLAUDE.md	行為規則、禁止事項、專案架構	每 session 全量載入	步驟型操作指令（用 Skills）
Skills	可執行的工作流模組	On-demand（呼叫時才載入）	永久性規則（放 CLAUDE.md）
Hooks	確定性強制執行	工具呼叫前後自動觸發	靈活判斷邏輯（那是 AI 的事）
Memory	跨 session 狀態延續	自動累積、自動載入	不變的規則（放 CLAUDE.md）

我們的 Shareuhack fleet 就是這樣分工的：

• CLAUDE.md：定義品牌語調、frontmatter 規範、絕對禁止事項（全 agent 共用）
• Skills：每個工作流程一個 Skill（/scout 選題、/collect 研究、/write 撰寫、/content-review 審查），只在需要時才載入對應指令
• Hooks：強制所有 file write 後跑格式檢查
• Memory：各 agent 累積的工作筆記（哪些來源可靠、哪些 pattern 有效）

這種分層的核心好處是 context 效率：CLAUDE.md 的規則永遠在場，但 Skills 只在被呼叫時佔用 context。如果你把 30 個工作流的指令全塞進 CLAUDE.md，每個 session 都會浪費大量 token 在當下用不到的指令上。

Hooks — 把「建議」變成「強制執行」的唯一方法

這是整個架構中最被低估的一層。

AI 天生是概率性的。即使你在 CLAUDE.md 寫明「每次修改程式碼後必須跑 lint」，Claude 在某些情境下——特別是多步驟任務的中間環節——仍可能跳過。這不是 bug，而是語言模型的本質：它會「自行判斷」哪些步驟在當下是「必要的」。

Hooks 是把「最佳實踐建議」變成「確定性強制執行」的唯一機制。

Hook 事件類型

Claude Code 目前支援以下 Hook 事件：

事件	觸發時機	是否需要 matcher
PreToolUse	工具呼叫前	是（匹配工具名稱）
PostToolUse	工具呼叫後	是（匹配工具名稱）
Notification	Claude 發送通知時	否
Stop	Claude 準備結束時	否
SubagentStart	Subagent 啟動時	否
SubagentStop	Subagent 結束時	否

設定方式

Hooks 設定在 .claude/settings.json（專案層級）或 ~/.claude/settings.json（全域層級）：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '請確認此指令安全性' >&2"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '任務完成，請檢查所有修改的檔案'"
          }
        ]
      }
    ]
  }
}

最實用的三個 Hook 食譜

1. 寫檔後自動 lint（PostToolUse + Write）：

{
  "matcher": "Write",
  "hooks": [
    {
      "type": "command",
      "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\""
    }
  ]
}

2. 阻止危險的 shell 指令（PreToolUse + Bash）：

{
  "matcher": "Bash",
  "hooks": [
    {
      "type": "command",
      "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|DROP TABLE|force push'; then echo '{\"hookSpecificOutput\":{\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"危險指令被 Hook 阻擋\"}}'; fi"
    }
  ]
}

3. 結束前強制跑測試（Stop）：

{
  "hooks": [
    {
      "type": "command",
      "command": "npm test 2>&1 | tail -5"
    }
  ]
}

關鍵觀念：CLAUDE.md 裡寫「每次都要跑測試」，根據社群普遍反饋，Claude 的遵守率不穩定，壓力情境下常被跳過。設定 Stop Hook 強制跑測試，遵守率是 100%，因為這是確定性的 shell 執行，不受 LLM 的概率性影響。這就是「建議」和「法律」的差距。

Skills 2.0 — 資料夾模組化 + Subagent 委派

Skills 是 Claude Code 的可執行模組系統。如果 CLAUDE.md 是「憲法」，Skills 就是「標準作業程序」——只在需要時才拿出來用。

Skills 2.0 vs 舊版 Slash Commands

2026 年的 Skills 2.0 更新引入了 folder-based 結構，這是和舊版最大的差異：

舊版（.claude/commands/）：

.claude/commands/
├── deploy.md
├── review.md
└── debug.md

Skills 2.0（.claude/skills/）：

.claude/skills/
├── deploy/
│   ├── SKILL.md          # 觸發邏輯 + YAML frontmatter
│   ├── scripts/           # 可執行腳本
│   │   └── deploy.sh
│   └── references/        # 按需載入的參考文件
│       └── deploy-checklist.md
├── review/
│   └── SKILL.md
└── debug/
    └── SKILL.md

關鍵升級：

• SKILL.md 的 YAML frontmatter 定義 name 和 description，讓 Claude 知道何時自主載入
• scripts/ 可以放可執行腳本，Skills 觸發時自動可用
• references/ 的內容是 on-demand 載入，不佔平時的 context
• 舊版 .claude/commands/*.md 仍可呼叫，但不再出現在新版 UI 的自動完成清單（截至 2026 年 4 月，官方尚未公布正式 deprecation 時間表）

SKILL.md 範例

---
name: review
description: "執行程式碼審查，檢查型別安全、效能、安全性問題"
---

# Code Review Skill

## 審查步驟

1. 讀取所有變更的檔案（git diff）
2. 逐檔檢查：
   - 型別安全：是否有 any、型別斷言是否合理
   - 效能：是否有不必要的 re-render、N+1 query
   - 安全性：是否有 XSS 風險、未處理的 user input
3. 產出結構化報告，按嚴重度排序

## 輸出格式

每個 finding 包含：
- 檔案路徑 + 行號
- 嚴重度（Critical / Warning / Info）
- 問題描述 + 修正建議

遷移 Checklist

如果你有舊版 .claude/commands/ 的指令：

1. 在 .claude/skills/ 建立同名資料夾
2. 將原始 .md 檔改名為 SKILL.md
3. 加上 YAML frontmatter（name 和 description）
4. 把原有邏輯照搬到 SKILL.md 的 markdown 內容
5. 如果有需要的腳本或參考文件，分別放進 scripts/ 和 references/
6. 舊檔案可以保留（不衝突），但建議最終移除

Subagent 委派

Skills 可以觸發獨立的 Subagent，每個 Subagent 有自己的 context window。Subagent 定義在 .claude/agents/ 目錄：

---
name: test-runner
description: "獨立執行測試套件並回報結果"
---

# Test Runner Agent

執行完整的測試套件，包含：
- 單元測試
- 整合測試
- 型別檢查

回報格式：通過/失敗數量 + 失敗測試的詳細錯誤訊息。

建立後，你可以在對話中用 @agent-test-runner 直接呼叫，或讓 Skills 流程自動委派。

我們的 fleet 經驗：Shareuhack 目前有超過 20 個 Skills（/scout、/collect、/synthesize、/write、/content-review、/translate 等），每個 Skill 都是獨立資料夾。因為 Skills 是 on-demand 載入的，這 20 多個 Skills 不會互相干擾 context。如果全部塞進 CLAUDE.md，光是指令文件就超過 5,000 行，不可能正常運作。

三套記憶系統的正確用法

Claude Code 有三套完全不同的記憶機制，很多人以為它們是同一件事。混用它們是 Agent 行為不穩定的最常見原因。

三套系統對比

系統	誰寫的	載入時機	適合放什麼
CLAUDE.md	你（人類）	每 session 全量載入	永久性規則、禁止事項、架構規範
Auto Memory	Claude 自己	跨 session 累積載入	工作筆記、debug 心得、偏好學習
Session Memory	系統自動	對話延續時載入	「上次做了什麼」的摘要

正確用法

• 規則和規範 → CLAUDE.md。例如：「commit message 用英文」、「不用 any 型別」
• Claude 的學習記錄 → Auto Memory（讓 Claude 自己管理）。例如：「這個專案的 build 會在 M1 Mac 上失敗，需要先跑 xxx」
• 臨時狀態 → 不需要手動管理，Session Memory 自動處理

常見錯誤

1. 把規則放進 Auto Memory：Auto Memory 的優先級低於 CLAUDE.md，而且 Claude 可能在後續 session 中修改自己的筆記，導致規則「漂移」
2. 把工作狀態放進 CLAUDE.md：每 session 都會載入這些過期的狀態資訊，浪費 context
3. 不知道 Auto Memory 存在：Claude 會自動記錄你的校正（當你說「不要用 var，用 const」），這些會累積在 ~/.claude/ 目錄下的 memory 檔案中

進階設定（適用於大型 Monorepo）

如果你的專案規模較大或使用 monorepo 結構，可以在 settings.json 中用 autoMemoryDirectory 自訂 Auto Memory 的存放位置，用 claudeMdExcludes 排除特定 CLAUDE.md 檔案——讓不同子專案載入不同的規則集。大多數獨立開發者或單一專案無需修改這些預設值。

三種使用場景模板

場景一：獨立開發者（30 分鐘搞定）

~/.claude/CLAUDE.md              # 全域偏好
{project}/CLAUDE.md              # 專案規則
{project}/.claude/skills/
├── deploy/SKILL.md              # /deploy 一鍵部署
├── debug/SKILL.md               # /debug 結構化除錯
└── review/SKILL.md              # /review 程式碼審查
{project}/.claude/settings.json  # 1 個 Hook：PostToolUse auto-lint

重點：先把 CLAUDE.md 寫好（15 分鐘），再建 3 個最常用的 Skills（15 分鐘）。Hooks 只設一個 auto-lint 就夠了。

場景二：開發團隊（2 小時）

{project}/CLAUDE.md              # 團隊規範（commit 進 repo）
{project}/CLAUDE.local.md        # 個人覆寫（加入 .gitignore）
{project}/.claude/rules/
├── frontend.md                  # 前端專屬規則（路徑作用域）
└── backend.md                   # 後端專屬規則
{project}/.claude/skills/
├── review/SKILL.md              # 統一的 code review 標準
├── pr-template/SKILL.md         # PR 模板生成
└── onboarding/SKILL.md          # 新人入職指南
{project}/.claude/settings.json  # Hooks：lint + test 強制執行

重點：CLAUDE.md commit 進 repo 讓全團隊共用，個人偏好用 CLAUDE.local.md 覆寫。.claude/rules/ 做前後端分流，避免前端工程師被後端規則干擾。

場景三：Power User — Agent Fleet（半天）

這是我們 Shareuhack 的實際設定架構：

{project}/CLAUDE.md              # 全域規範（品牌語調、禁止事項）
{project}/.claude/CLAUDE.md      # 系統層規範
{project}/.claude/rules/
├── content-pipeline.md          # 內容 pipeline 規則
└── dev-standards.md             # 開發標準
{project}/.claude/skills/
├── scout/SKILL.md               # 選題偵察
├── collect/SKILL.md             # 來源收集
├── synthesize/SKILL.md          # 知識合成
├── writer/SKILL.md              # 文章撰寫
├── reviewer/SKILL.md            # 品質審查
└── translate/SKILL.md           # 多語翻譯
{project}/.claude/agents/
├── researcher.md                # 研究 agent
├── writer.md                    # 撰寫 agent
└── reviewer.md                  # 審查 agent
{project}/.claude/settings.json  # 多層 Hooks

這個架構讓 6 個 agents 可以並行運作：Scout 選題後自動觸發 Collect，Collect 完成後自動進入 Synthesize，一路到發布。每個環節都有對應的 Skill 定義流程，Hooks 確保品質門檻不被跳過。

CLAUDE.md vs GEMINI.md vs System Prompt — 架構哲學差異

如果你同時使用多種 AI coding 工具，理解它們的設定哲學差異很重要：

維度	CLAUDE.md（Claude Code）	GEMINI.md（Gemini CLI）	System Prompt（API）
載入方式	三層優先級自動載入	類似的 global/project 階層	每次請求手動注入
持久化	檔案系統，跨 session	檔案系統，跨 session	無持久化
強制執行	Hooks 確定性執行	Plan Mode 預設唯讀	無原生機制
模組化	Skills 2.0 + Subagents	無等效的 Skills 系統	需自行實作
context 管理	On-demand 載入、rules 路徑作用域	子資料夾層級規則	手動控制
生態系統	社群 Skills、Hooks 生態豐富	早期發展階段	不適用

核心差異在於控制哲學：

• Claude Code 的設計是「規則 + 強制執行 + 模組化」，適合需要穩定、可重複的工作流
• Gemini CLI 從 Plan Mode 出發，預設唯讀分析再寫入，適合謹慎型工作流
• System Prompt 是最底層的 API 控制，靈活但沒有內建的持久化和執行保障

如果你在團隊中同時使用 Claude Code 和 Gemini CLI，可以讓兩者共享同一份設定（部分開發者會設定 Gemini CLI 讀取 CLAUDE.md），但 Hooks 和 Skills 是 Claude Code 專屬的差異化功能。

社群生態 + 常見錯誤 + Debug 方式

社群資源

Claude Code 的社群生態在 2026 年已經相當成熟：

• awesome-claude-code：28,500+ 個社群資源的精選清單
• awesome-claude-code-toolkit：135 個 agents、35 個精選 Skills（透過 SkillKit 可存取 400,000+）、42 個 commands、176+ plugins、20 個 hooks
• antigravity-awesome-skills：1,400+ 個可安裝的跨 agent Skills，支援 Claude Code、Codex、Gemini CLI、Cursor

常見錯誤 Top 5

1. CLAUDE.md 過長導致 context 浪費：超過 300 行的 CLAUDE.md 應該拆分到 .claude/rules/ 做路徑作用域
2. Skills 未遷移到 2.0 format：舊版 .claude/commands/*.md 仍能執行，但不出現在 UI 自動完成清單，容易被遺忘
3. Hooks 設定路徑錯誤：Hooks 在 .claude/settings.json 的 hooks 欄位，不是 CLAUDE.md 裡
4. Auto Memory 和 CLAUDE.md 混用：規則放 CLAUDE.md，學習記錄讓 Auto Memory 自行管理
5. 忘記設定 CLAUDE.local.md：團隊專案中，個人偏好（如回覆語言、commit style）應該用 local 覆寫，不要改動 team 的 CLAUDE.md

Debug 流程

當 Claude 的行為不符預期時：

1. 確認 CLAUDE.md 是否被載入：在對話中問 Claude「你目前載入了哪些 CLAUDE.md？」
2. 檢查 settings.json：確認 Hooks 設定語法正確，特別是 matcher 大小寫（case-sensitive）
3. 檢查 Skills 路徑：Skills 2.0 必須在 .claude/skills/{name}/SKILL.md，不是 .claude/skills/{name}.md
4. 查看 Hook 日誌：Hook 的 stdout 會回傳給 Claude，stderr 會顯示在終端，善用這兩個通道 debug
5. 排除 claudeMdExcludes：如果特定規則沒生效，檢查 settings.json 裡是否不小心排除了對應的 CLAUDE.md 檔案

從 0 到完整設定的 Checklist

Milestone 1：基礎設定（30 分鐘）

• 建立 ~/.claude/CLAUDE.md，放個人偏好（回覆語言、命名風格、禁止行為）
• 建立 {project}/CLAUDE.md，放專案規範（技術棧、coding style、架構規則）
• 建立 {project}/CLAUDE.local.md（加入 .gitignore），放個人覆寫
• 建立第一個 Skill：.claude/skills/review/SKILL.md
• 驗證：開新 session，確認 Claude 遵守你的 coding style

Milestone 2：進階設定（2 小時）

• 設定 PostToolUse Hook：寫檔後自動 lint
• 設定 PreToolUse Hook：阻擋危險 shell 指令
• 設定 Stop Hook：結束前自動跑測試
• 建立 .claude/rules/ 目錄，將長規則拆分為路徑作用域檔案
• 將 CLAUDE.md 和 Skills commit 進 repo，與團隊共享

Milestone 3：完整架構（半天）

• 建立 3-5 個專案核心 Skills（deploy、debug、review、test、docs）
• 設計 Subagent 分工（如果你的工作流涉及多步驟任務）
• 從社群安裝 5 個適合你技術棧的 Skills
• 建立 Auto Memory 的管理習慣：定期檢視 Claude 的自動記錄是否準確
• 完整測試：執行一次端到端的工作流，確認四層架構正常協作

結論

Claude Code 的四層架構——CLAUDE.md、Skills、Hooks、Memory——不是四個獨立的功能，而是一個完整的控制系統。把正確的東西放在正確的層級，才是讓 AI agent 行為穩定可預測的關鍵。

根據我們運作 Shareuhack AI fleet 的經驗，最常見的問題不是「不知道有這些功能」，而是「把所有東西塞進 CLAUDE.md」。一旦你理解了四層分工的邏輯——規則在 CLAUDE.md、流程在 Skills、強制執行在 Hooks、學習記錄在 Memory——你的 Claude Code 生產力會有質的提升。

從 Milestone 1 開始，30 分鐘就能看到效果。