標籤: Agent Teams

Hook 看起來簡單，但它的威力來自於「在正確的時刻介入」。本篇深入 Hook 的生命週期，展示 6 個不同的 Hook 觸發點（lifecycle points），提供 12+ 個實戰場景範例，以及具體的配置和部署步驟。

🔄 Hook 的完整生命週期

Claude Code 在執行工作時，會經過多個檢查點。Hook 就是在這些檢查點上「攔截」執行流程，進行驗證、轉換或防禦。

用戶輸入
  ↓
[PreRequest Hook] ← Hook 1：攔截請求前
  ↓
驗證認證和權限
  ↓
[PreToolUse Hook] ← Hook 2：在工具執行前
  ↓
執行工具（bash、read、edit 等）
  ↓
獲取工具結果
  ↓
[PostToolUse Hook] ← Hook 3：在工具執行後
  ↓
結果驗證和轉換
  ↓
[Stop Hook] ← Hook 4：決定是否需要暫停和修正
  ↓
返回結果給用戶
  ↓
[PostResponse Hook] ← Hook 5：響應後的清理
  ↓
異常處理
  ↓
[OnError Hook] ← Hook 6：異常發生時的恢復
  ↓
完成

📍 6 個 Hook 觸發點詳解

1️⃣ PreRequest Hook（最上游的防禦）

觸發時機：用戶提交請求時，在任何工具執行前

使用場景：

• 🔴 防禦場景 1：檢查用戶是否試圖讀取敏感檔案（.env, .ssh, .config）
• 🟠 檢查場景 2：驗證請求是否包含危險關鍵字（git reset –hard, rm -rf）
• 🟡 轉向場景 3：根據時間或上下文自動拒絕某些類型的請求

# 配置位置：~/.claude/settings.json 或 settings.local.json

{
  "hooks": {
    "pre_request": {
      "enabled": true,
      "rules": [
        {
          "name": "block_sensitive_files",
          "pattern": "(read|cat).*(\\.env|\\.key|\\.ssh|credentials)",
          "action": "block",
          "message": "⚠️ Cannot access sensitive files"
        },
        {
          "name": "warn_destructive",
          "pattern": "git (reset --hard|push --force)|rm -rf",
          "action": "confirm",
          "message": "⚠️ This command is destructive. Continue?"
        }
      ]
    }
  }
}

2️⃣ PreToolUse Hook（工具執行前的最後檢查）

觸發時機：具體工具（bash、read、edit 等）即將執行時

使用場景：

• 🔴 防禦場景 1：攔截特定工具（禁止 rm、禁止 git push 到 main）
• 🟠 檢查場景 2：驗證檔案路徑存在性（避免編輯不存在的檔案）
• 🟡 轉換場景 3：修改命令參數（將 rm 改為 mv to trash）
• 🟢 記錄場景 4：記錄所有敏感操作的日誌

# 例子：PreToolUse Hook - 禁止直接刪除

{
  "hooks": {
    "pre_tool_use": {
      "enabled": true,
      "rules": [
        {
          "name": "prevent_direct_deletion",
          "tool": "bash",
          "pattern": "^rm ",
          "action": "transform",
          "transform": "echo 'Using rm is disabled. Use: mv $file ~/.trash' && false"
        },
        {
          "name": "verify_branch_safety",
          "tool": "bash",
          "pattern": "git push.*main",
          "action": "confirm",
          "message": "Push to main? This is permanent."
        },
        {
          "name": "auto_backup_on_edit",
          "tool": "edit",
          "action": "pre_action",
          "command": "cp {file} {file}.backup"
        }
      ]
    }
  }
}

3️⃣ PostToolUse Hook（工具執行後的驗證和轉換）

觸發時機：工具執行完畢，獲得結果後

使用場景：

• 🟡 驗證場景 1：檢查 bash 命令是否成功（exit code = 0）
• 🟠 轉換場景 2：格式化輸出（JSON 格式化、表格美化）
• 🟢 記錄場景 3：自動保存重要操作結果
• 🔵 優化場景 4：清理大型輸出（截斷日誌）

# 例子：PostToolUse Hook - 自動格式化和驗證

{
  "hooks": {
    "post_tool_use": {
      "enabled": true,
      "rules": [
        {
          "name": "validate_bash_success",
          "tool": "bash",
          "action": "validate",
          "check": "exit_code == 0",
          "on_fail": "log_error"
        },
        {
          "name": "auto_format_json",
          "tool": "bash",
          "pattern": "jq|json",
          "action": "transform",
          "transform": "jq '.' (automatically format JSON output)"
        },
        {
          "name": "save_large_results",
          "tool": "bash",
          "pattern": "curl|wget",
          "action": "post_action",
          "command": "save_to_file ~/.cache/last_result.json"
        },
        {
          "name": "truncate_verbose_output",
          "tool": "bash",
          "action": "transform",
          "condition": "output_size > 10000",
          "transform": "head -100 + '... (truncated {remaining} lines)'"
        }
      ]
    }
  }
}

4️⃣ Stop Hook（驗證器決策點）

觸發時機：結果返回給用戶前，決定是否需要暫停和修正

使用場景：

• 🔴 驗證場景 1：JSON 格式驗證（無效 JSON 需要修正）
• 🟠 邏輯場景 2：檢查結果合理性（SQL 查詢應該有行，否則可能是錯誤）
• 🟡 決策場景 3：判斷結果是否完整（檔案大小是否符合預期）

# 例子：Stop Hook with Validator - JSON 驗證和自動修復

{
  "hooks": {
    "stop_hook": {
      "enabled": true,
      "validator": {
        "name": "json_validator",
        "rules": [
          {
            "id": "valid_json",
            "check": "is_valid_json(result)",
            "on_fail": "stop_and_request_fix",
            "message": "JSON is malformed. Please fix and retry.",
            "auto_attempt": 3
          },
          {
            "id": "non_empty_result",
            "check": "len(result) > 10",
            "on_fail": "warn",
            "message": "Result might be incomplete (too short)"
          },
          {
            "id": "api_error_check",
            "check": "'error' not in result.lower()",
            "on_fail": "stop_and_request_fix",
            "message": "API returned an error. Review and retry."
          }
        ]
      }
    }
  }
}

5️⃣ PostResponse Hook（執行後的清理和通知）

觸發時機：結果已返回給用戶，工作完成後

使用場景：

• 🟢 清理場景 1：刪除臨時檔案（/tmp 下的中間結果）
• 🔵 通知場景 2：記錄到監控系統（重要操作記錄）
• 🟣 統計場景 3：更新執行統計（執行次數、成功率）

# 例子：PostResponse Hook - 清理和通知

{
  "hooks": {
    "post_response": {
      "enabled": true,
      "rules": [
        {
          "name": "cleanup_temp_files",
          "action": "cleanup",
          "targets": ["/tmp/*.temp", "/tmp/claude-*"],
          "condition": "age > 1h"
        },
        {
          "name": "log_sensitive_operations",
          "action": "log",
          "condition": "tool in ['bash', 'edit'] AND (git|deploy|delete) in command",
          "log_file": "~/.claude/audit.log"
        },
        {
          "name": "notify_on_error",
          "action": "notify",
          "condition": "exit_code != 0",
          "channels": ["stderr", "log_file"]
        }
      ]
    }
  }
}

6️⃣ OnError Hook（異常情況處理）

觸發時機：工具執行失敗或發生異常時

使用場景：

• 🔴 恢復場景 1：自動回滾（某個命令失敗，執行恢復操作）
• 🟠 重試場景 2：自動重試（網絡超時自動重試）
• 🟡 降級場景 3：使用備選方案（API 1 失敗，嘗試 API 2）

# 例子：OnError Hook - 自動恢復和重試

{
  "hooks": {
    "on_error": {
      "enabled": true,
      "rules": [
        {
          "name": "auto_retry_network_errors",
          "error_pattern": "(timeout|connection refused|ECONNREFUSED)",
          "action": "retry",
          "max_attempts": 3,
          "backoff": "exponential"
        },
        {
          "name": "rollback_on_git_error",
          "error_pattern": "git (push|merge|rebase)",
          "action": "execute",
          "command": "git reset --hard HEAD"
        },
        {
          "name": "fallback_api_endpoint",
          "error_pattern": "api1\\.example\\.com",
          "action": "retry_with",
          "new_command": "replace(api1, api2)"
        }
      ]
    }
  }
}

🛠️ 如何正確配置和部署 Hook

步驟 1：選擇配置位置

1. 全局配置：~/.claude/settings.json（所有項目適用）
2. 項目級配置：{project}/.claude/settings.local.json（單個項目）
3. 團隊配置：{team}/.claude/team-settings.json（團隊共享）

步驟 2：編寫 Hook 規則

Hook 規則的通用結構：

{
  "hook_type": "pre_tool_use",      // 觸發點
  "name": "rule_name",               // 規則名稱
  "tool": "bash",                    // 適用工具（可選）
  "pattern": "regex_pattern",        // 匹配模式（可選）
  "action": "block|confirm|transform|validate", // 動作類型
  "condition": "expression",         // 執行條件（可選）
  "message": "User-facing message",  // 給用戶的提示
  "auto_attempt": 3,                 // 自動重試次數（可選）
  "transform": "transformation",     // 轉換規則（如果 action=transform）
  "on_fail": "action_on_failure"    // 失敗時的行動
}

步驟 3：驗證 Hook 配置

# 1. 檢查 JSON 語法
jq '.' ~/.claude/settings.json

# 2. 列出所有啟用的 Hook
claude config list-hooks --enabled

# 3. 測試特定 Hook（乾跑）
claude hook test --name rule_name --dry-run

# 4. 查看 Hook 日誌
tail -f ~/.claude/hooks.log

步驟 4：分層部署（由簡到複雜）

1. 第 1 周：安全防禦
   • PreRequest Hook：阻止敏感檔案讀取
   • PostToolUse Hook：驗證 bash 執行成功
2. 第 2 周：工作流驗證
   • Stop Hook：JSON 驗證
   • PostToolUse Hook：自動格式化
3. 第 3 周：錯誤恢復
   • OnError Hook：自動重試
   • PostResponse Hook：清理臨時檔案

📋 12+ 個實戰範例速查表

範例	Hook 類型	動作	效果
保護 .env 檔案	PreRequest	Block	永不讀取敏感檔案
防止 git reset –hard	PreToolUse	Confirm	需要確認才能執行
禁止直接 rm	PreToolUse	Transform	改為移到回收站
自動格式化 JSON	PostToolUse	Transform	自動美化輸出
驗證 JSON 有效性	Stop	Validate	無效 JSON 拒絕返回
自動備份編輯檔案	PreToolUse	Pre-action	編輯前自動備份
日誌敏感操作	PostResponse	Log	所有敏感操作記錄
網絡超時自動重試	OnError	Retry	最多重試 3 次
清理臨時檔案	PostResponse	Cleanup	自動刪除 /tmp
驗證 bash 成功	PostToolUse	Validate	exit code ≠ 0 時警告
截斷大型輸出	PostToolUse	Transform	> 10KB 自動截斷
API 故障轉移	OnError	Fallback	用備選 API 重試

⚠️ Hook 配置的常見陷阱

陷阱 1：規則太寬鬆，誤傷正常操作

❌ 錯誤：
"pattern": "read"  // 任何包含 "read" 的命令都會觸發

✅ 正確：
"pattern": "read (.*\\.env|\\.key|\\.credentials)"  // 只針對特定檔案

陷阱 2：Hook 順序錯誤導致邏輯失效

❌ 錯誤順序：
1. PostToolUse（驗證）
2. PreToolUse（保護）  ← 太晚了，工具已經執行了

✅ 正確順序：
1. PreToolUse（攔截和保護）
2. PostToolUse（驗證結果）
3. Stop（決定是否修正）

陷阱 3：Transform 規則語法錯誤

❌ 錯誤：
"transform": "cmd.replace('old', 'new')"  // Python 語法，但 Hook 是 shell

✅ 正確：
"transform": "sed 's/old/new/g'"  // Shell 語法
或
"transform": "replace(cmd, old, new)"  // Hook 提供的函數

✅ Hook 部署檢查清單

• ☐ 配置檔案 JSON 語法正確（jq 驗證通過）
• ☐ Hook 規則的 pattern 足夠明確（不會誤傷）
• ☐ PreToolUse 規則在最關鍵的地方（防禦第一）
• ☐ Stop Hook 驗證邏輯清晰（什麼時候拒絕）
• ☐ OnError Hook 有適當的重試邏輯
• ☐ 測試了至少一個完整工作流
• ☐ 查看日誌確認 Hook 被正確觸發
• ☐ 團隊成員知道有這些 Hook（溝通重要）

🔗 與其他文章的連結

總結：Hook 的 6 個層次

• 🎯 L1：PreRequest（最上游，全局防禦）
• 🎯 L2：PreToolUse（工具前，細粒度保護）
• 🎯 L3：PostToolUse（結果驗證和轉換）
• 🎯 L4：Stop（決策點，是否修正）
• 🎯 L5：PostResponse（清理和通知）
• 🎯 L6：OnError（異常恢復）

掌握這 6 個層次，你就能在任何地方「攔截」執行流程，實現你想要的保護和自動化。

你是否發現自己每週都在重複做同樣的 5-8 步工作流？或者需要一個「虛擬助手」來幫你檢查代碼、驗證數據、管理流程？

Claude Code 有一個升級系統可以幫你自動化這些重複工作。從簡單的 Hook（5 分鐘）到複雜的 Custom Agent（2-3 小時），每個升級都能節省你數十小時的勞動。

這個完整指南將帶你從 0 到 1，掌握整個升級系統。

🎯 你將學到什麼

• ✅ 5 個具體場景：何時應該升級？
• ✅ Hook 快速指南：5 分鐘內建立自動規則
• ✅ Skill 完整教程：1 小時自動化複雜工作流
• ✅ Custom Agent 進階：打造會思考的自動化角色
• ✅ 數學原理：為什麼成功率從 32.8% 提升到 99.2%？

📚 5 篇文章系列地圖

第 1 篇：判斷升級時機（5 個具體場景）

第 2 篇：Hook 操作指南（5 分鐘快速升級）

第 3 篇：Skill 操作指南（1 小時建立完整工作流自動化）

第 4 篇：Custom Agent 完整指南（2-3 小時打造會思考的角色）

第 5 篇：原理深度解析（驗證器的數學 + 決策樹）

🛤️ 推薦學習路徑

路徑 A：我是初學者（第 1 次接觸 Claude Code 升級）

1. 📄 文章 1：認識 5 個升級場景（15 分鐘）
2. 📄 文章 2：建立你的第一個 Hook（5 分鐘 + 5 分鐘實作）
3. 📄 文章 3：升級到 Skill（30 分鐘閱讀 + 30 分鐘實作）
4. 📄 文章 4：認識 Custom Agent（20 分鐘）
5. 📄 文章 5：理解背後原理（20 分鐘）
6. ✅ 總時間：2.5 小時（閱讀 + 實作）

路徑 B：我已經在用 Claude Code（想優化現有工作流）

1. 📄 文章 1：快速掃讀場景判斷標準（5 分鐘）
2. 📄 跳到你需要的文章（Hook / Skill / Agent）
3. 📄 文章 5：查詢決策矩陣（2 分鐘）
4. ✅ 總時間：1 小時（快速查找 + 實作）

路徑 C：我想建立 Custom Agent（跳過 Hook / Skill）

• 文章 1：Claude Code 升級判斷：5 個具體場景
• 文章 2：Claude Code Hook 操作指南：5 分鐘強制執行安全規則
• 文章 3：Claude Code Skill 操作指南：1 小時建立重複工作流自動化
• 文章 4：Claude Code Custom Agent 完整指南：打造會思考的自動化角色
• 文章 5：Claude Code 升級原理深度：從 32.8% 到 99.2% 的驗證器數學

1. 📄 文章 1：看場景 3（跨任務角色）（5 分鐘）
2. 📄 文章 4：完整 Agent 指南（40 分鐘）
3. 📄 文章 5：原理和決策樹（20 分鐘）
4. ✅ 總時間：1.5 小時（閱讀 + 計畫）

💡 快速決策表

不知道該選哪篇？看這個表：

你的情況	直接閱讀	節省時間
同一條規則被違反 3+ 次	文章 2（Hook）	40 小時/年
每週執行相同的 5-8 步工作流	文章 3（Skill）	200 小時/年
需要跨 3+ 項目的相同角色	文章 4（Agent）	300+ 小時/年
不知道該選哪個	文章 1（場景）	決策時間 -10 分鐘

🚀 第一步：開始行動

不用一次讀完所有 5 篇。選擇最符合你現況的文章，花 30 分鐘看完，然後立即執行。

📚 文章索引

• 文章 1：Claude Code 升級判斷：5 個具體場景
• 文章 2：Claude Code Hook 操作指南：5 分鐘強制執行安全規則
• 文章 3：Claude Code Skill 操作指南：1 小時建立重複工作流自動化
• 文章 4：Claude Code Custom Agent 完整指南：打造會思考的自動化角色
• 文章 5：Claude Code 升級原理深度：從 32.8% 到 99.2% 的驗證器數學

• 評估 Skill 效果，考慮升級到 Agent 若需要自主決策
• 建立 Agent Team 若有多個角色
• 持續積累記憶，改進決策邏輯

最終目標：90% 的重複工作自動化，讓你專注於需要創意和判斷的工作。

• 週 1：建立 2 個 Hook（安全規則、自動格式化）
• 週 2：建立 1 個 Skill（複雜工作流）
• 週 3-4：優化和維護

第二個月及以後

• 評估 Skill 效果，考慮升級到 Agent 若需要自主決策
• 建立 Agent Team 若有多個角色
• 持續積累記憶，改進決策邏輯

最終目標：90% 的重複工作自動化，讓你專注於需要創意和判斷的工作。

第一個月

• 週 1：建立 2 個 Hook（安全規則、自動格式化）
• 週 2：建立 1 個 Skill（複雜工作流）
• 週 3-4：優化和維護

第二個月及以後

• 評估 Skill 效果，考慮升級到 Agent 若需要自主決策
• 建立 Agent Team 若有多個角色
• 持續積累記憶，改進決策邏輯

最終目標：90% 的重複工作自動化，讓你專注於需要創意和判斷的工作。

總結：升級路線圖

第一個月

• 週 1：建立 2 個 Hook（安全規則、自動格式化）
• 週 2：建立 1 個 Skill（複雜工作流）
• 週 3-4：優化和維護

第二個月及以後

• 評估 Skill 效果，考慮升級到 Agent 若需要自主決策
• 建立 Agent Team 若有多個角色
• 持續積累記憶，改進決策邏輯

最終目標：90% 的重複工作自動化，讓你專注於需要創意和判斷的工作。

結論：投入越早，收益越大。如果你每月執行 20+ 次工作，1 小時的投入在 2 週內就能回本。

總結：升級路線圖

第一個月

• 週 1：建立 2 個 Hook（安全規則、自動格式化）
• 週 2：建立 1 個 Skill（複雜工作流）
• 週 3-4：優化和維護

第二個月及以後

• 評估 Skill 效果，考慮升級到 Agent 若需要自主決策
• 建立 Agent Team 若有多個角色
• 持續積累記憶，改進決策邏輯

最終目標：90% 的重複工作自動化，讓你專注於需要創意和判斷的工作。

結論：投入越早，收益越大。如果你每月執行 20+ 次工作，1 小時的投入在 2 週內就能回本。

總結：升級路線圖

第一個月

• 週 1：建立 2 個 Hook（安全規則、自動格式化）
• 週 2：建立 1 個 Skill（複雜工作流）
• 週 3-4：優化和維護

第二個月及以後

• 評估 Skill 效果，考慮升級到 Agent 若需要自主決策
• 建立 Agent Team 若有多個角色
• 持續積累記憶，改進決策邏輯

最終目標：90% 的重複工作自動化，讓你專注於需要創意和判斷的工作。

升級成本 vs 收益分析

升級類型	初始投入	每次執行時間	年度節省時間	ROI 週期
Hook	5 分鐘	自動	≈ 40 小時	< 1 週
Skill	1 小時	5 分鐘 → 自動	≈ 200 小時	1-2 週
Custom Agent	2-3 小時	自動 + 自主決策	≈ 300+ 小時	1-2 週

結論：投入越早，收益越大。如果你每月執行 20+ 次工作，1 小時的投入在 2 週內就能回本。

總結：升級路線圖

第一個月

• 週 1：建立 2 個 Hook（安全規則、自動格式化）
• 週 2：建立 1 個 Skill（複雜工作流）
• 週 3-4：優化和維護

第二個月及以後

• 評估 Skill 效果，考慮升級到 Agent 若需要自主決策
• 建立 Agent Team 若有多個角色
• 持續積累記憶，改進決策邏輯

最終目標：90% 的重複工作自動化，讓你專注於需要創意和判斷的工作。

Hook 設計來執行簡單的、自動的規則檢查（如文件保護）。如果你想自動化 5 步工作流，Hook 會變得複雜且不可維護。

陷阱 2：Skill 沒有驗證器

Skill 最常見的失敗是「執行了但沒驗證」。務必添加步驟驗證，確保每一步都成功。

陷阱 3：Agent 工具權限設置太寬鬆

如果 Agent 有「執行任意 bash」權限，可能導致意外刪除。始終限制工具存取：允許讀，限制寫；允許查詢，限制刪除。

升級成本 vs 收益分析

升級類型	初始投入	每次執行時間	年度節省時間	ROI 週期
Hook	5 分鐘	自動	≈ 40 小時	< 1 週
Skill	1 小時	5 分鐘 → 自動	≈ 200 小時	1-2 週
Custom Agent	2-3 小時	自動 + 自主決策	≈ 300+ 小時	1-2 週

結論：投入越早，收益越大。如果你每月執行 20+ 次工作，1 小時的投入在 2 週內就能回本。

總結：升級路線圖

第一個月

• 週 1：建立 2 個 Hook（安全規則、自動格式化）
• 週 2：建立 1 個 Skill（複雜工作流）
• 週 3-4：優化和維護

第二個月及以後

• 評估 Skill 效果，考慮升級到 Agent 若需要自主決策
• 建立 Agent Team 若有多個角色
• 持續積累記憶，改進決策邏輯

最終目標：90% 的重複工作自動化，讓你專注於需要創意和判斷的工作。

Skill 沒有記憶（每次執行都從零開始），Agent 有。如果你需要「從上次的經驗中學習」，就需要 Agent。

Skill（無記憶）：
- 每次執行相同的步驟
- 不會記得「上次我們發現 X 會導致失敗」
- 適合「規則明確且不變」的工作

Agent（有記憶）：
- 記住「上次的教訓」並應用到新情況
- 可以根據過去經驗調整策略
- 適合「規則會隨經驗進化」的工作

常見陷阱

陷阱 1：把 Hook 當 Skill 用

Hook 設計來執行簡單的、自動的規則檢查（如文件保護）。如果你想自動化 5 步工作流，Hook 會變得複雜且不可維護。

陷阱 2：Skill 沒有驗證器

Skill 最常見的失敗是「執行了但沒驗證」。務必添加步驟驗證，確保每一步都成功。

陷阱 3：Agent 工具權限設置太寬鬆

如果 Agent 有「執行任意 bash」權限，可能導致意外刪除。始終限制工具存取：允許讀，限制寫；允許查詢，限制刪除。

升級成本 vs 收益分析

升級類型	初始投入	每次執行時間	年度節省時間	ROI 週期
Hook	5 分鐘	自動	≈ 40 小時	< 1 週
Skill	1 小時	5 分鐘 → 自動	≈ 200 小時	1-2 週
Custom Agent	2-3 小時	自動 + 自主決策	≈ 300+ 小時	1-2 週

結論：投入越早，收益越大。如果你每月執行 20+ 次工作，1 小時的投入在 2 週內就能回本。

總結：升級路線圖

第一個月

• 週 1：建立 2 個 Hook（安全規則、自動格式化）
• 週 2：建立 1 個 Skill（複雜工作流）
• 週 3-4：優化和維護

第二個月及以後

• 評估 Skill 效果，考慮升級到 Agent 若需要自主決策
• 建立 Agent Team 若有多個角色
• 持續積累記憶，改進決策邏輯

最終目標：90% 的重複工作自動化，讓你專注於需要創意和判斷的工作。

Skill 和 Agent 的成功率差異，來自驗證器。永遠先考慮「如何檢測失敗」，再考慮「如何修復」。

❌ 錯誤做法：
1. 執行步驟 A
2. 執行步驟 B
3. （沒有檢查 A 或 B 是否成功）

✅ 正確做法：
1. 執行步驟 A
2. 驗證步驟 A 成功（否則停止並報告）
3. 執行步驟 B
4. 驗證步驟 B 成功（否則停止並報告）

實踐 3：記憶是 Agent 的優勢

Skill 沒有記憶（每次執行都從零開始），Agent 有。如果你需要「從上次的經驗中學習」，就需要 Agent。

Skill（無記憶）：
- 每次執行相同的步驟
- 不會記得「上次我們發現 X 會導致失敗」
- 適合「規則明確且不變」的工作

Agent（有記憶）：
- 記住「上次的教訓」並應用到新情況
- 可以根據過去經驗調整策略
- 適合「規則會隨經驗進化」的工作

常見陷阱

陷阱 1：把 Hook 當 Skill 用

Hook 設計來執行簡單的、自動的規則檢查（如文件保護）。如果你想自動化 5 步工作流，Hook 會變得複雜且不可維護。

陷阱 2：Skill 沒有驗證器

Skill 最常見的失敗是「執行了但沒驗證」。務必添加步驟驗證，確保每一步都成功。

陷阱 3：Agent 工具權限設置太寬鬆

如果 Agent 有「執行任意 bash」權限，可能導致意外刪除。始終限制工具存取：允許讀，限制寫；允許查詢，限制刪除。

升級成本 vs 收益分析

升級類型	初始投入	每次執行時間	年度節省時間	ROI 週期
Hook	5 分鐘	自動	≈ 40 小時	< 1 週
Skill	1 小時	5 分鐘 → 自動	≈ 200 小時	1-2 週
Custom Agent	2-3 小時	自動 + 自主決策	≈ 300+ 小時	1-2 週

結論：投入越早，收益越大。如果你每月執行 20+ 次工作，1 小時的投入在 2 週內就能回本。

總結：升級路線圖

第一個月

• 週 1：建立 2 個 Hook（安全規則、自動格式化）
• 週 2：建立 1 個 Skill（複雜工作流）
• 週 3-4：優化和維護

第二個月及以後

• 評估 Skill 效果，考慮升級到 Agent 若需要自主決策
• 建立 Agent Team 若有多個角色
• 持續積累記憶，改進決策邏輯

最終目標：90% 的重複工作自動化，讓你專注於需要創意和判斷的工作。

不要一開始就跳到 Agent。先用 Hook 解決簡單問題，積累經驗，再升級。

週 1：識別 1 個簡單規則 → Hook → 5 分鐘完成
週 2：發現 1 個重複工作流 → Skill → 1 小時完成
週 3：規劃 1 個複雜角色 → Agent → 2 小時完成

成果：3 週內自動化了 3 個不同層級的工作

實踐 2：驗證器是必須，不是可選

Skill 和 Agent 的成功率差異，來自驗證器。永遠先考慮「如何檢測失敗」，再考慮「如何修復」。

❌ 錯誤做法：
1. 執行步驟 A
2. 執行步驟 B
3. （沒有檢查 A 或 B 是否成功）

✅ 正確做法：
1. 執行步驟 A
2. 驗證步驟 A 成功（否則停止並報告）
3. 執行步驟 B
4. 驗證步驟 B 成功（否則停止並報告）

實踐 3：記憶是 Agent 的優勢

Skill 沒有記憶（每次執行都從零開始），Agent 有。如果你需要「從上次的經驗中學習」，就需要 Agent。

Skill（無記憶）：
- 每次執行相同的步驟
- 不會記得「上次我們發現 X 會導致失敗」
- 適合「規則明確且不變」的工作

Agent（有記憶）：
- 記住「上次的教訓」並應用到新情況
- 可以根據過去經驗調整策略
- 適合「規則會隨經驗進化」的工作

常見陷阱

陷阱 1：把 Hook 當 Skill 用

Hook 設計來執行簡單的、自動的規則檢查（如文件保護）。如果你想自動化 5 步工作流，Hook 會變得複雜且不可維護。

陷阱 2：Skill 沒有驗證器

Skill 最常見的失敗是「執行了但沒驗證」。務必添加步驟驗證，確保每一步都成功。

陷阱 3：Agent 工具權限設置太寬鬆

如果 Agent 有「執行任意 bash」權限，可能導致意外刪除。始終限制工具存取：允許讀，限制寫；允許查詢，限制刪除。

升級成本 vs 收益分析

升級類型	初始投入	每次執行時間	年度節省時間	ROI 週期
Hook	5 分鐘	自動	≈ 40 小時	< 1 週
Skill	1 小時	5 分鐘 → 自動	≈ 200 小時	1-2 週
Custom Agent	2-3 小時	自動 + 自主決策	≈ 300+ 小時	1-2 週

結論：投入越早，收益越大。如果你每月執行 20+ 次工作，1 小時的投入在 2 週內就能回本。

總結：升級路線圖

第一個月

• 週 1：建立 2 個 Hook（安全規則、自動格式化）
• 週 2：建立 1 個 Skill（複雜工作流）
• 週 3-4：優化和維護

第二個月及以後

• 評估 Skill 效果，考慮升級到 Agent 若需要自主決策
• 建立 Agent Team 若有多個角色
• 持續積累記憶，改進決策邏輯

最終目標：90% 的重複工作自動化，讓你專注於需要創意和判斷的工作。

以下表格用顏色表示優先級，幫你快速判斷：

場景	步驟	頻率	推薦升級	時間投入
安全規則違反	1-2	> 3 次	🔴 HOOK	5 分鐘
複雜工作流	5-8	> 1 次/週	🟠 SKILL	1 小時
跨任務角色	不固定	> 3 個項目	🟣 AGENT	2-3 小時
成功率低	任意	< 80%	🟡 STOP HOOK	10 分鐘
優化完成	任意	任意	🟢 維護中	0

最佳實踐

實踐 1：從 Hook 開始，逐步升級

不要一開始就跳到 Agent。先用 Hook 解決簡單問題，積累經驗，再升級。

週 1：識別 1 個簡單規則 → Hook → 5 分鐘完成
週 2：發現 1 個重複工作流 → Skill → 1 小時完成
週 3：規劃 1 個複雜角色 → Agent → 2 小時完成

成果：3 週內自動化了 3 個不同層級的工作

實踐 2：驗證器是必須，不是可選

Skill 和 Agent 的成功率差異，來自驗證器。永遠先考慮「如何檢測失敗」，再考慮「如何修復」。

❌ 錯誤做法：
1. 執行步驟 A
2. 執行步驟 B
3. （沒有檢查 A 或 B 是否成功）

✅ 正確做法：
1. 執行步驟 A
2. 驗證步驟 A 成功（否則停止並報告）
3. 執行步驟 B
4. 驗證步驟 B 成功（否則停止並報告）

實踐 3：記憶是 Agent 的優勢

Skill 沒有記憶（每次執行都從零開始），Agent 有。如果你需要「從上次的經驗中學習」，就需要 Agent。

Skill（無記憶）：
- 每次執行相同的步驟
- 不會記得「上次我們發現 X 會導致失敗」
- 適合「規則明確且不變」的工作

Agent（有記憶）：
- 記住「上次的教訓」並應用到新情況
- 可以根據過去經驗調整策略
- 適合「規則會隨經驗進化」的工作

常見陷阱

陷阱 1：把 Hook 當 Skill 用

Hook 設計來執行簡單的、自動的規則檢查（如文件保護）。如果你想自動化 5 步工作流，Hook 會變得複雜且不可維護。

陷阱 2：Skill 沒有驗證器

Skill 最常見的失敗是「執行了但沒驗證」。務必添加步驟驗證，確保每一步都成功。

陷阱 3：Agent 工具權限設置太寬鬆

如果 Agent 有「執行任意 bash」權限，可能導致意外刪除。始終限制工具存取：允許讀，限制寫；允許查詢，限制刪除。

升級成本 vs 收益分析

升級類型	初始投入	每次執行時間	年度節省時間	ROI 週期
Hook	5 分鐘	自動	≈ 40 小時	< 1 週
Skill	1 小時	5 分鐘 → 自動	≈ 200 小時	1-2 週
Custom Agent	2-3 小時	自動 + 自主決策	≈ 300+ 小時	1-2 週

結論：投入越早，收益越大。如果你每月執行 20+ 次工作，1 小時的投入在 2 週內就能回本。

總結：升級路線圖

第一個月

• 週 1：建立 2 個 Hook（安全規則、自動格式化）
• 週 2：建立 1 個 Skill（複雜工作流）
• 週 3-4：優化和維護

第二個月及以後

• 評估 Skill 效果，考慮升級到 Agent 若需要自主決策
• 建立 Agent Team 若有多個角色
• 持續積累記憶，改進決策邏輯

最終目標：90% 的重複工作自動化，讓你專注於需要創意和判斷的工作。

這篇文章深入 Claude Code 升級系統的核心數學和決策邏輯。你將看到驗證器如何把成功率從 32.8% 提升到 99.2%，以及完整的決策樹讓你在 Hook、Skill、Agent 間做出正確選擇。

驗證器的魔力：數學原理

Claude Code 的自動化系統成功率取決於「驗證」。讓我們看看數據。

基礎：無驗證的成功率

在沒有驗證機制的情況下，假設每個步驟的成功率是 90%（已經很高了）：

工作流：8 個步驟（如 WordPress 發佈）
每步成功率：90%
總成功率：0.9^8 = 0.4305 = 43.05%

更現實的情況（考慮人工錯誤）：
每步成功率：85%
總成功率：0.85^8 = 0.2725 = 27.25%

實際觀察：32.8% ✓（與上面介於兩者之間）

驗證器的威力

添加「驗證器」意味著：如果第 i 步失敗，立即察覺並修正，不會「失敗一步、後續全失」。

引入驗證器的修正能力：

假設每步有驗證器：
- 失敗檢測率：100%（驗證器會立即發現）
- 自動修復率：85%（大多數錯誤可自動修復）
- 人工修復率：15%（複雜問題需要人工）

修復後重試成功率：95%

計算複合成功率：
Pr(成功 | 有驗證) = ∏(i=1 to 8) [Pr(步驟i成功) + Pr(步驟i失敗 × 驗證檢出 × 修復成功)]
                = ∏(i=1 to 8) [0.85 + 0.15 × 1.0 × 0.95]
                = ∏(i=1 to 8) [0.85 + 0.1425]
                = 0.9925^8
                = 0.938 ≈ 93.8%

如果引入重試機制（最多 3 次）：
Pr(成功後第3次重試) ≈ 1 - (1 - 0.938)^3 ≈ 0.9992 = 99.92%

實際觀察：99.2% ✓（接近理論預測）

決策樹：何時用 Hook / Skill / Agent

選擇正確的升級方向很重要。以下決策樹幫你做出最優選擇。

決策樹的結構

開始：你遇到重複的工作嗎？
│
├─ NO → 不需要升級，保持手工
│
└─ YES → 這個工作多複雜？
   │
   ├─ 很簡單（1-2 步，簡單判斷邏輯）
   │  └─ 升級到 HOOK
   │     ├─ 執行時間：5 分鐘
   │     ├─ 應用場景：自動格式化、檔案保護、簡單驗證
   │     └─ 成功率提升：90% → 99%
   │
   ├─ 中等複雜（5-8 步，有決策分支）
   │  └─ 升級到 SKILL
   │     ├─ 執行時間：1 小時
   │     ├─ 應用場景：工作流自動化、多工具整合
   │     └─ 成功率提升：32.8% → 99.2%
   │
   └─ 很複雜（涉及多角色、需要自主決策、跨項目）
      └─ 升級到 CUSTOM AGENT
         ├─ 執行時間：2-3 小時
         ├─ 應用場景：代碼審查、架構決策、複雜數據處理
         └─ 額外價值：記憶學習、自主規劃

決策矩陣表

以下表格用顏色表示優先級，幫你快速判斷：

場景	步驟	頻率	推薦升級	時間投入
安全規則違反	1-2	> 3 次	🔴 HOOK	5 分鐘
複雜工作流	5-8	> 1 次/週	🟠 SKILL	1 小時
跨任務角色	不固定	> 3 個項目	🟣 AGENT	2-3 小時
成功率低	任意	< 80%	🟡 STOP HOOK	10 分鐘
優化完成	任意	任意	🟢 維護中	0

最佳實踐

實踐 1：從 Hook 開始，逐步升級

不要一開始就跳到 Agent。先用 Hook 解決簡單問題，積累經驗，再升級。

週 1：識別 1 個簡單規則 → Hook → 5 分鐘完成
週 2：發現 1 個重複工作流 → Skill → 1 小時完成
週 3：規劃 1 個複雜角色 → Agent → 2 小時完成

成果：3 週內自動化了 3 個不同層級的工作

實踐 2：驗證器是必須，不是可選

Skill 和 Agent 的成功率差異，來自驗證器。永遠先考慮「如何檢測失敗」，再考慮「如何修復」。

❌ 錯誤做法：
1. 執行步驟 A
2. 執行步驟 B
3. （沒有檢查 A 或 B 是否成功）

✅ 正確做法：
1. 執行步驟 A
2. 驗證步驟 A 成功（否則停止並報告）
3. 執行步驟 B
4. 驗證步驟 B 成功（否則停止並報告）

實踐 3：記憶是 Agent 的優勢

Skill 沒有記憶（每次執行都從零開始），Agent 有。如果你需要「從上次的經驗中學習」，就需要 Agent。

Skill（無記憶）：
- 每次執行相同的步驟
- 不會記得「上次我們發現 X 會導致失敗」
- 適合「規則明確且不變」的工作

Agent（有記憶）：
- 記住「上次的教訓」並應用到新情況
- 可以根據過去經驗調整策略
- 適合「規則會隨經驗進化」的工作

常見陷阱

陷阱 1：把 Hook 當 Skill 用

Hook 設計來執行簡單的、自動的規則檢查（如文件保護）。如果你想自動化 5 步工作流，Hook 會變得複雜且不可維護。

陷阱 2：Skill 沒有驗證器

Skill 最常見的失敗是「執行了但沒驗證」。務必添加步驟驗證，確保每一步都成功。

陷阱 3：Agent 工具權限設置太寬鬆

如果 Agent 有「執行任意 bash」權限，可能導致意外刪除。始終限制工具存取：允許讀，限制寫；允許查詢，限制刪除。

升級成本 vs 收益分析

升級類型	初始投入	每次執行時間	年度節省時間	ROI 週期
Hook	5 分鐘	自動	≈ 40 小時	< 1 週
Skill	1 小時	5 分鐘 → 自動	≈ 200 小時	1-2 週
Custom Agent	2-3 小時	自動 + 自主決策	≈ 300+ 小時	1-2 週

結論：投入越早，收益越大。如果你每月執行 20+ 次工作，1 小時的投入在 2 週內就能回本。

總結：升級路線圖

第一個月

• 週 1：建立 2 個 Hook（安全規則、自動格式化）
• 週 2：建立 1 個 Skill（複雜工作流）
• 週 3-4：優化和維護

第二個月及以後

• 評估 Skill 效果，考慮升級到 Agent 若需要自主決策
• 建立 Agent Team 若有多個角色
• 持續積累記憶，改進決策邏輯

最終目標：90% 的重複工作自動化，讓你專注於需要創意和判斷的工作。