小編精選 - 技術文章翻譯 · 03月28日

Claude Code 的五個熟練層級：關於還停留在 CLAUDE.md 的人所不知道的 Skills、Hooks、Orchestration 的世界

はじめに

晚上好，我是 miruky。

正在使用 Claude Code 的你，是否已經撰寫 CLAUDE.md？

最近 Reddit 上有篇名為「The 5 Levels of Claude Code」的討論很受矚目。發文者 DevMoses 報告了他驚人的運作：在 32 個 session 中並行啟動 198 個代理（agents），合併衝突率僅 3.1%。

這篇操作的核心在於把 Claude Code 的熟練度分成 5 個等級。多數人停留在 Level 2 的 CLAUDE.md，但往前還有 Skills、Hooks、Orchestration 這個完全不同次元的世界。

本文根據官方文件與社群心得，系統性地說明 Claude Code 的 5 個等級。

出典：The 5 levels of Claude Code - Reddit r/ClaudeAI / Claude Code 官方文件

1. 5 個等級的全貌

1-1. 框架概要

Claude Code 的熟練度可分為 5 個等級。每個等級都是為了解決前一個等級的痛點而向上堆疊，且不可跳級。

等級名稱 / 核心 / 代幣（Token）消耗

Level 1：Raw Prompting — 每次手動輸入指示，需每次重複
Level 2：CLAUDE.md — 專案規則永久化，於 session 開始時被讀取
Level 3：Skills — 手順文件按需注入，僅於呼叫時消耗
Level 4：Hooks — 在生命週期插入自動處理（多為外部腳本），幾乎不消耗 tokens（由外部執行）
Level 5：Orchestration — 多代理並列協調，消耗與代理數成正比

1-2. 「升級」的機制

DevMoses 的重要洞察是：「你不會因為自己決定就畢業。你會撞到上限，摩擦會把你推上去。」

You don't graduate by deciding to. You graduate because you hit a ceiling and the friction forces you up.

換句話說，當 Level 2 的 CLAUDE.md 超過 ~150 行且遵守率下降時，自然會產生進入 Level 3（Skills）的需求；當 Skills 無法保證品質時，就會需要 Level 4（Hooks），以此類推。

2. Level 1：Raw Prompting（純 Prompt）

2-1. 是什麼狀態

安裝 Claude Code 後直接使用的階段：

claude

> 在這個 React 應用新增深色模式（dark mode）。
> 使用 Tailwind CSS，並做一個切換按鈕（toggle）。

對於小型任務這樣就足夠。Claude Code 很強，單一檔案變更通常沒問題。

2-2. 為何會撞到上限

隨著專案成長，會出現：

每次都要重複相同指示：「用 TypeScript 寫」「也要寫測試」「通過 ESLint」
程式碼風格不一致：每個 session 風格可能不同
上下文斷裂：每次開新 session 都需要重新說明專案結構

當這些摩擦累積到一定程度，就是升到 Level 2 的訊號。

3. Level 2：CLAUDE.md（專案記憶）

3-1. 什麼是 CLAUDE.md

CLAUDE.md 是 Claude Code 在 session 開始時會自動讀取的 Markdown 檔案。把專案規則、程式碼規範、建置指令等寫在裡面，就不需要每次再手動指示 Claude。

範例 CLAUDE.md：

# 專案概要
前端: React 19 + TypeScript + Tailwind CSS
後端: Hono + Drizzle ORM
測試: Vitest

# 程式碼規範
- 僅使用函式元件（禁止類別元件）
- 型別定義集中於 `types/` 目錄
- 匯入使用別名 `@/`

# 指令
- 建置: `pnpm build`
- 測試: `pnpm test`
- Lint: `pnpm lint`

3-2. 放置位置與作用範圍

CLAUDE.md 可以放在多個位置，且每個位置的作用域不同：

./CLAUDE.md：整個專案（團隊共用的程式碼規範與建置流程）
./.claude/CLAUDE.md：整個專案（跟上面相同，但可隱藏於 .claude/ 目錄）
~/.claude/CLAUDE.md：跨專案共用（個人偏好或工作流程）
子目錄的 CLAUDE.md：該目錄以下有效（適合 monorepo 中的 package 特定規則）

此外，執行 /init 指令會自動生成基礎 CLAUDE.md。若已存在 CLAUDE.md，則會提供改善建議。

3-3. 透過 `.claude/rules/` 模組化

當 CLAUDE.md 變長，可以把內容拆成 .claude/rules/ 的多個主題檔案：

your-project/
├── .claude/
│   ├── CLAUDE.md           # 主要指示（精簡）
│   └── rules/
│       ├── code-style.md   # 程式碼規範
│       ├── testing.md      # 測試規範
│       └── security.md     # 安全性需求

另外可以用 paths front matter 定義僅對特定檔案模式生效的規則：

---
paths:
  - "src/api/**/*.ts"
---

# API 開發規則
- 對所有 endpoint 實作輸入驗證
- 使用標準錯誤回應格式
- 包含 OpenAPI 文件註解

3-4. 為何會撞到上限

Anthropic 官方建議 CLAUDE.md 保持在 200 行以內，社群有人回報約 77 行最佳。

常見問題：

遵守率下降：CLAUDE.md 越長，後面規則越容易被忽略
tokens 持續消耗：CLAUDE.md 每次 session 都會全文載入
不可能把所有內容塞一個檔案：部署流程、審查標準、測試策略等角色不同

這時就需要「只有在需要時才被讀取」的技能檔案（Skills）。

4. Level 3：Skills（按需技能）

4-1. Skills 是什麼

Skills 是放在 .claude/skills/ 目錄下的 Markdown 檔案，用來教 Claude 特定任務的流程。與 CLAUDE.md 最大的差別是：Skills 只有在被呼叫時才會被注入到上下文中。

不使用時 → token 消耗為零
被呼叫時 → 手順文件會注入到上下文

4-2. Skill 檔案的結構

Skill 檔案命名為 SKILL.md，由 YAML front matter 與 Markdown 內容組成，通常放結構如下：

.claude/skills/
├── deploy/
│   └── SKILL.md          # 部署手順書
├── code-review/
│   └── SKILL.md          # 程式碼審查手順書
└── fix-issue/
    └── SKILL.md          # Issue 修正手順書

4-3. Skill 檔案的寫法範例

以下為修正 GitHub Issue 的 Skill 範例：

---
name: fix-issue
description: 修正 GitHub Issue
disable-model-invocation: true
---

請按照以下步驟修正 GitHub Issue $ARGUMENTS：
1. 確認 Issue 內容
2. 調查相關程式碼
3. 實作修正
4. 新增測試
5. 建立 commit

front matter 欄位說明：

name：命令名稱（可用 /fix-issue 呼叫）
description：Claude 用於自動判斷時的說明文字
disable-model-invocation：若設為 true，只有手動呼叫可以使用（Claude 不會自動選用）
allowed-tools：執行 Skill 時允許 Claude 使用的工具（可限制）
context：若設為 fork，表示在子代理（subagent）上下文中執行

4-4. 實用 Skill 範例

讀取式研究員（Read-only Researcher）

---
name: deep-research
description: 對程式碼庫進行深入調查
context: fork
agent: Explore
---

請針對 $ARGUMENTS 進行徹底調查：
1. 使用 glob 與 grep 找到相關檔案
2. 讀取並分析程式碼
3. 以具體檔案參考整理調查結果

PR 要約 Skill（動態注入上下文）

---
name: pr-summary
description: 摘要 PR 的變更內容
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## PR 資訊
- PR 差異: !`gh pr diff`
- PR 評論: !`gh pr view --comments`
- 變更檔案列表: !`gh pr diff --name-only`

## 任務
請為此 PR 撰寫要約...

! 指令語法說明：

!<command> 會在 Skill 內容被送給 Claude 之前先執行 shell 指令，並把輸出結果取代該指令位置。Claude 接收到的是命令的輸出資料，而非命令本身。

4-5. CLAUDE.md vs Skills 的分工

比較要點：

讀取時機：
- CLAUDE.md：每個 session 自動讀入
- Skills：僅於呼叫時讀入
token 消耗：
- CLAUDE.md：持續消耗
- Skills：只有使用時才消耗
適合內容：
- CLAUDE.md：程式碼規範、建置指令
- Skills：部署手順、審查流程、Issue 修正
呼叫方式：
- CLAUDE.md：自動生效
- Skills：/skill-name 或由 Claude 自動判斷是否使用

若想更深入 Skills 的實務技巧，筆者另有整理 10 種實戰模式：
→ 【2026 年最新版】Claude Code Skills 實踐技巧 10 選

4-6. 為何會撞到上限

Skills 是告訴 Claude「該怎麼做」，但不是用來「驗證 Claude 做了什麼」的機制。即便指示 Claude 執行測試，它也可能忘記去執行。

Skills 的限制：可以告訴 Claude「執行測試」，但無法保證 Claude 一定會去做。

這時需要把品質檢查變成自動執行的基礎設施，也就是 Level 4 的 Hooks。

5. Level 4：Hooks（生命週期自動化）

5-1. 什麼是 Hooks

Hooks 是在 Claude Code 的生命週期特定時點會自動執行的腳本。它不是告訴 Claude 去驗證，而是建立「用於驗證的基礎設施」。

範例說明：

Skills：會告訴 Claude「檔案修改後執行 lint」
Hooks：在檔案修改後自動執行 lint（真正自動化）

5-2. Hooks 的種類

Hooks 有許多事件可供攔截，覆蓋 Claude Code 生命週期的各個階段：

SessionStart（session 開始時）：設定開發環境、環境變數等
PreToolUse（工具使用前）：攔截危險命令、做驗證
PostToolUse（工具使用後）：自動執行 lint、型別檢查、測試
Stop（Claude 回應完成時）：品質閘門，檢查任務是否真的完成
SubagentStart/Stop（子代理啟動/結束時）：監控子代理
TaskCompleted（任務完成時）：強制確認測試是否通過
UserPromptSubmit（使用者送出 prompt 時）：驗證 prompt 或補充上下文

5-3. 實作範例①：攔截危險命令

下面的 Hook 會自動攔截包含 rm -rf 的 Bash 命令。

設定檔（.claude/settings.json）：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

腳本（.claude/hooks/block-rm.sh）：

#!/bin/bash
COMMAND=$(jq -r '.tool_input.command' < /dev/stdin)

if echo "$COMMAND" | grep -q 'rm -rf'; then
  echo "Blocked: rm -rf commands are not allowed" >&2
  exit 2  # exit 2 = block
fi

exit 0  # exit 0 = allow

5-4. 實作範例②：檔案編輯後自動 lint

每次 Claude 編輯檔案後，自動執行 lint 腳本。

設定檔：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
          }
        ]
      }
    ]
  }
}

5-5. 實作範例③：品質閘門（Stop Hook）

當 Claude 判定要「完成並停止」時，透過 Stop Hook 驗證任務是否真已完成。若使用 Prompt 型 Hook，可以把判定交給另一個 LLM。

設定範例（Stop 事件使用 prompt）：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "請評估以下上下文： $ARGUMENTS\n\n1. 使用者要求的所有任務是否已完成？\n2. 是否仍有未處理的錯誤？\n3. 是否需要後續跟進？\n\n請以 JSON 格式回覆：{\"ok\": true} 代表允許停止，{\"ok\": false, \"reason\": \"理由\"} 代表需繼續",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

5-6. 4 種 Hook 處理器類型

type: command — 執行 shell 指令（用途：lint、測試、檔案驗證）
type: http — 向 HTTP endpoint 發 POST（用途：整合外部服務、送 log）
type: prompt — 向另一個 LLM 發單回合詢問（用途：品質判定、安全檢查）
type: agent — 啟動可使用工具的子代理（用途：讀碼並做複雜檢查）

非同步 Hook：

設定 "async": true 可使 Hook 在背景執行而不阻塞 Claude，適合耗時流程如完整測試執行。

若想完整了解 Hooks 的全部事件，筆者另有整理 21 個事件的詳解：
→ 【保存版】Claude Code Hooks 全 21 事件完全解說

5-7. 在 Skill 的 front matter 內定義 Hook

可以在 Skill 的 front matter 裡定義 Hook，這樣該 Skill 在被啟用期間，相關 Hook 才會生效。

範例：

---
name: secure-operations
description: 以安全檢查流程進行操作
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

5-8. 為何會撞到上限

Hooks 能把品質變成基礎設施，但單一 Claude Code session 能處理的工作量依然有限。大規模重構、跨數十檔案的變更或多面向的審查，無法 realistic 地在一個 session 裡完成。

這時需要「並列啟動多個代理」的機制，也就是 Level 5。

6. Level 5：Orchestration（並列代理人協調）

6-1. 為什麼需要並列化

到 Level 4 為止，優化仍是在「單一 Claude session」內。但實務上會遇到以下情境：

大規模重構：超出上下文視窗（context window）
並列程式碼審查：無法同時覆蓋安全、效能、測試等面向
多重假說調查：會被侷限在單一假說上
前後端同時開發：可能對同一檔案造成衝突

這些情況需要把任務切分並平行執行。

6-2. Subagents（子代理）

Claude Code 內建子代理（subagents），Claude 會自動把任務委派給它們。

常見子代理模型與用途：

Explore（Haiku，快速）— 檔案搜尋、程式碼庫探索（唯讀）
Plan — 計畫擬定
General-purpose — 通用任務

自定義子代理：

在 .claude/agents/ 建 Markdown 檔來定義自訂子代理

範例自訂子代理：

---
name: code-reviewer
description: 審查程式碼品質與最佳實踐
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是資深程式碼審查員。啟動後：
1. 用 git diff 檢視近期變更
2. 專注於變更的檔案
3. 立即開始審查

審查清單：
- 程式碼是否清晰易讀
- 是否有適當的錯誤處理
- 是否存在資安問題
- 是否有足夠的測試覆蓋

註：子代理無法再產生其他子代理；若需巢狀委派，請從主會話串接（chain）處理。

6-3. Agent Teams（代理人團隊）

Agent Teams 是讓多個 Claude Code 實例作為團隊協作的機制。與 Subagents 最大差異在於：團隊成員可以直接互相溝通。

比較：

Subagents：僅回傳結果給父代理，彼此沒有直接通訊
Agent Teams：團隊成員間可直接傳訊、共享狀態
協調方式：
- Subagents：由父代理管理
- Agent Teams：有共享任務清單，能自我協調
適用情境：
- Subagents：只需要結果時
- Agent Teams：需要成員間討論與協作的複雜任務

Agent Teams 是實驗性功能，預設關閉。可透過設定啟用：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

使用範例：並列程式碼審查

建立一個 agent team 來審查 PR #142。產生三位審查員：
- 一位專注於資安影響
- 一位檢查效能面向
- 一位驗證測試覆蓋
讓他們各自審查並回報發現。

由一位 lead 統籌，團隊成員各自獨立工作，最後由 lead 整合結果。

6-4. /batch Skill — 大規模並列變更

內建的 /batch skill 用於以並列代理執行大規模變更：

範例指令：

/batch migrate src/ from Solid to React

執行流程：

調查程式碼庫
把工作拆成 5～30 個獨立單元
提出計畫（等待核准）
核准後，為每個單元在獨立的 git worktree 生成代理
各代理負責實作、測試、建立 PR

6-5. DevMoses 的運營實績

在 Reddit 上被分享的 DevMoses 報告了以下數據：

並列代理數：198
fleet session（群組 session）數：32
合併衝突率：3.1%

這套運作是透過名為 Citadel 的開源系統實現的。

出處：Citadel - GitHub

Level 5 的注意事項：

token 消耗會隨代理數量線性增加
多個代理同時編輯同一檔案會產生衝突
建議先從 3～5 名團隊成員開始
Agent Teams 為實驗性功能，在重開 session 時團隊成員可能不會完整還原

7. 升級的路線圖

7-1. 逐步前進

最重要的原則：不要跳級。

每一層的基礎設施都是讓下一層成為可能的條件。如果沒有 CLAUDE.md，直接寫 Skills 也會因為基本規範未統一而導致 Skills 品質不穩。

建議流程：

Step 1：撰寫 CLAUDE.md（可用 /init 自動生成後再優化）
↓
Step 2：當 CLAUDE.md 變長，拆分到 .claude/rules/
↓
Step 3：把重複的工作流程切出成 Skills
↓
Step 4：在需要保證品質的環節加入 Hooks
↓
Step 5：用 Subagents 委派任務 → 以 Agent Teams 做並列化

7-2. 今日就能開始的行動清單

目前狀態 / 下一步行動 / 預估所需時間

Level 0（尚未導入 Claude Code）：執行 npm install -g @anthropic-ai/claude-code — 5 分鐘
Level 1（無 CLAUDE.md）：執行 /init 自動生成 CLAUDE.md — 10 分鐘
Level 2（已有 CLAUDE.md）：把常重複的流程抽成一個 Skill — 30 分鐘
Level 3（已有 Skills）：設定 PostToolUse Hook 以自動執行 lint — 30 分鐘
Level 4（已有 Hooks）：定義一個 Subagent 嘗試委派任務 — 30 分鐘

7-3. 官方文件中值得深入的頁面

Level 2：How Claude remembers your project（CLAUDE.md）
https://code.claude.com/docs/en/memory
Level 3：Extend Claude with skills
https://code.claude.com/docs/en/skills
Level 4：Hooks reference / Hooks guide
https://code.claude.com/docs/en/hooks
https://code.claude.com/docs/en/hooks-guide
Level 5：Create custom subagents / Agent teams
https://code.claude.com/docs/en/sub-agents
https://code.claude.com/docs/en/agent-teams

おわりに

感謝閱讀至此。總結 Claude Code 的 5 個等級要點：

Level 1（Raw Prompting）：直接使用 Claude Code。對小任務足夠，但專案擴大後會遇上限
Level 2（CLAUDE.md）：把專案規則永久化。建議簡潔（200 行以下）
Level 3（Skills）：按需注入的手順書。不使用時 token 消耗為零
Level 4（Hooks）：在生命週期中加入品質閘門。從「指示做」轉為「以基礎設施保證」
Level 5（Orchestration）：透過 Subagents、Agent Teams 與 /batch 做並列統籌

重要的是，不需要一次把所有層級都導入。當你撞到上限，就是升到下一層的時機。先從撰寫 CLAUDE.md 開始吧。

下次見。

參考連結

官方文件

Claude Code Overview: https://code.claude.com/docs/en/overview
How Claude remembers your project（CLAUDE.md）: https://code.claude.com/docs/en/memory
Extend Claude with skills: https://code.claude.com/docs/en/skills
Hooks reference: https://code.claude.com/docs/en/hooks
Automate workflows with hooks（Guide）: https://code.claude.com/docs/en/hooks-guide
Create custom subagents: https://code.claude.com/docs/en/sub-agents
Orchestrate teams of Claude Code sessions: https://code.claude.com/docs/en/agent-teams

社群

The 5 levels of Claude Code - Reddit r/ClaudeAI: https://www.reddit.com/r/ClaudeAI/comments/1lgyw33/the_5_levels_of_claude_code/
Citadel - GitHub（Claude Code Orchestration 系統）: https://github.com/SethGammon/Citadel

原文出處：https://qiita.com/miruky/items/43a6828c806a9ebcfdd1

小編精選 - 技術文章翻譯

精選技術文章翻譯，幫助開發者持續吸收新知。

0個讚 0留言 36瀏覽

共有 0 則留言

登入之後發表留言

文字內容提供幾種功能：
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式

小編精選 - 技術文章翻譯

精選技術文章翻譯，幫助開發者持續吸收新知。

🏆 本月排行榜

🥇

站長阿川

📝12 💬10 ❤️2

361

🥈

我愛JS

📝2 💬9 ❤️2

🥉

💬1

評分標準：發文×10 + 留言×3 + 獲讚×5 + 點讚×1 + 瀏覽數÷10

本數據每小時更新一次

Claude Code 的五個熟練層級：關於還停留在 CLAUDE.md 的人所不知道的 Skills、Hooks、Orchestration 的世界

Claude Code 的五個熟練層級：關於還停留在 CLAUDE.md 的人所不知道的 Skills、Hooks、Orchestration 的世界

はじめに

目次

1. 5 個等級的全貌

1-1. 框架概要

1-2. 「升級」的機制

2. Level 1：Raw Prompting（純 Prompt）

2-1. 是什麼狀態

2-2. 為何會撞到上限

3. Level 2：CLAUDE.md（專案記憶）

3-1. 什麼是 CLAUDE.md

3-2. 放置位置與作用範圍

3-3. 透過 .claude/rules/ 模組化

3-4. 為何會撞到上限

4. Level 3：Skills（按需技能）

4-1. Skills 是什麼

4-2. Skill 檔案的結構

4-3. Skill 檔案的寫法範例

4-4. 實用 Skill 範例

讀取式研究員（Read-only Researcher）

PR 要約 Skill（動態注入上下文）

4-5. CLAUDE.md vs Skills 的分工

4-6. 為何會撞到上限

5. Level 4：Hooks（生命週期自動化）

5-1. 什麼是 Hooks

5-2. Hooks 的種類

5-3. 實作範例①：攔截危險命令

5-4. 實作範例②：檔案編輯後自動 lint

5-5. 實作範例③：品質閘門（Stop Hook）

5-6. 4 種 Hook 處理器類型

5-7. 在 Skill 的 front matter 內定義 Hook

5-8. 為何會撞到上限

6. Level 5：Orchestration（並列代理人協調）

6-1. 為什麼需要並列化

6-2. Subagents（子代理）

6-3. Agent Teams（代理人團隊）

6-4. /batch Skill — 大規模並列變更

6-5. DevMoses 的運營實績

7. 升級的路線圖

7-1. 逐步前進

7-2. 今日就能開始的行動清單

7-3. 官方文件中值得深入的頁面

おわりに

參考連結

官方文件

社群

小編精選 - 技術文章翻譯

🏆 本月排行榜

3-3. 透過 `.claude/rules/` 模組化