分類: 💻 技術實踐

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% 的重複工作自動化，讓你專注於需要創意和判斷的工作。

Skill 是把複雜的重複工作流變成「一個命令」的最有效升級。如果你發現自己每週要執行同樣的 5-8 步工作流不止一次，就該考慮 Skill 了。本篇教你如何從 CLAUDE.md 中提取工作流、建立 Skill 文件、以及用真實的 WordPress 發佈 Skill 驗證整個過程。

何時升級到 Skill？判斷標準

Skill 適合「重複的多步工作流」。以下判斷標準會幫你決定：

1. 步驟 ≥ 5 步：Hook 是 1-2 步的快速規則，Skill 是 5+ 步的完整工作流
2. 頻率 > 1 次/週：如果你每週只做一次，Hook 就夠了。如果超過一次，Skill 更划算
3. 跨檔案協調：涉及多個檔案/API 呼叫的工作流（如發佈文章）
4. 決策分支：工作流中有多個「下一步取決於上一步結果」的地方

Skill 文件結構

每個 Skill 都是一個 markdown 檔案，放在 ~/.claude/skills/ 目錄下。基本結構如下：

---
name: skill-name
description: 一行描述，告訴 Claude 這個 Skill 做什麼
---

# Skill 標題

## 何時使用

- 用戶說 "xxx"
- 用戶想要完成 "xxx" 的工作

## 前置條件

任何所需的設置、環境變數、API 密鑰等

## 工作流程

使用 ASCII 流程圖或步驟列表

## 詳細步驟

每個步驟的具體實施方式、命令、代碼片段等

WordPress 發佈 Skill 完整範例

---
name: wordpress-blog-publisher
description: Publish SEO-optimized WordPress articles with color-coded content blocks
---

# WordPress Blog Publisher Skill

## 何時使用

- 用戶說「發佈到部落格」或「post to blog」
- 想把分析、研究、程式碼轉成部落格文章
- 需要發佈包含代碼、表格、決策樹的內容

## 前置條件

**WordPress 認證資訊：**
- WordPress 網站 URL
- 使用者名稱 + Application Password
  格式：`username` / `xxxx xxxx xxxx xxxx xxxx xxxx`
- 已取得分類 ID 和標籤 ID

**SEO/AEO 要點：**
- 標題 < 60 字符
- 摘要 120-155 字符（= 中繼描述）
- H2 標題 4-8 個，每個含次要關鍵字
- 内容用 Gutenberg Block 格式

## 工作流程

驗證 API 存取 → 查詢分類/標籤 → 格式化內容 → 添加 SEO 中繼 → 創建 FAQ Schema → 生成 Payload → POST 草稿 → 驗證成功

## 詳細步驟

### 步驟 1：驗證 API 存取

```bash
source ~/.claude/projects/-home-tom/wordpress-config.env
curl -s -o /dev/null -w "%{http_code}" -u "${WORDPRESS_USER}:${WORDPRESS_APP_PASSWORD}" \
  "${WORDPRESS_URL}/wp-json/wp/v2/posts?per_page=1"
# 200 = 成功, 401 = 認證失敗
```

### 步驟 2：用 Gutenberg Block 格式化內容

使用顏色編碼框突出重點內容：

**紅色框（安全/必須項）：**
```html


🔴 標題



```

**橙色框（重要警告）：**
```html


🟠 標題



```

### 步驟 3：添加 FAQ JSON-LD 架構

在文章結尾添加：

```html



```

### 步驟 4：生成 REST API Payload（用 Python）

```python
import json

# 讀取 HTML 內容
with open('article.html', 'r', encoding='utf-8') as f:
    content = f.read()

# 創建 POST payload
post = {
    'title': 'SEO-optimized title under 60 chars',
    'content': content,
    'status': 'draft',  # 永遠先存草稿
    'slug': 'keyword-rich-slug',
    'excerpt': 'Meta description 120-155 chars with primary keyword.',
    'categories': [117],  # AI 與自動化
    'tags': [64, 65]
}

# 用 Python 生成 JSON（確保正確編碼）
with open('payload.json', 'w', encoding='utf-8') as f:
    json.dump(post, f, ensure_ascii=False, indent=2)
```

### 步驟 5：POST 到 WordPress

```bash
curl -s -X POST \
  -u "${WORDPRESS_USER}:${WORDPRESS_APP_PASSWORD}" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "${WORDPRESS_URL}/wp-json/wp/v2/posts" | jq '.'
```

回應會包含 `id`（文章 ID）和 `link`（發佈 URL）。

## 測試驗證方法

**驗證清單：**
- [ ] 文章標題 < 60 字符且含主要關鍵字
- [ ] 摘要 120-155 字符
- [ ] H2 標題 4-8 個
- [ ] Gutenberg Block 格式正確（無孤立 HTML 標籤）
- [ ] 彩色框正確呈現（紅/橙/黃等）
- [ ] FAQ Schema 在文章末尾
- [ ] 文件大小 < 50KB（防止 PHP 記憶體耗盡）

**實際驗證：**
```bash
# 檢查發佈結果
curl -s -u "${WORDPRESS_USER}:${WORDPRESS_APP_PASSWORD}" \
  "${WORDPRESS_URL}/wp-json/wp/v2/posts/{POST_ID}" | jq '.title, .link, .categories'

# 訪問瀏覽器檢查呈現效果
open {LINK_URL}
```

## 常見問題

**Q：什麼時候應該發佈為草稿而非直接發佈？**
A：永遠先發佈為 `"status": "draft"`。這樣你可以在瀏覽器檢查排版，確認顏色框正確呈現，再手動發佈。

**Q：我的文章超過 50KB，會不會有問題？**
A：WordPress PHP 限制為 536MB，但 Gutenberg Block Parser 會耗盡記憶體。保持每篇文章 < 30KB 最安全。如果內容很長，分成多篇系列文章。

**Q：我想用不同的顏色框，怎麼改？**
A：修改 `background-color` 和 `border-left` 的十六進位色碼：
- 紅色：#fee2e2 / #dc2626
- 橙色：#fed7aa / #ea580c
- 黃色：#fef3c7 / #eab308
- 綠色：#dcfce7 / #16a34a
- 藍色：#dbeafe / #0284c7
- 紫色：#f3e8ff / #a855f7

實戰案例：WordPress 發佈 Skill 的演進

本文所述的 WordPress 發佈技能本身就是一個 Skill 演進的案例。從原始的「手工執行 8 步」到「/publish 一鍵完成」，經歷了以下階段：

階段 1：手工 curl 和 Python 指令碼（無 Skill）

每次發佈文章時，手動執行：查詢分類 ID → 準備 JSON → curl POST → 檢查結果。重複 100 次後，開始想「有沒有辦法簡化？」

階段 2：創建 Skill 文件（有程序，無自動觸發）

把 8 個步驟寫成 ~/.claude/skills/wordpress-blog-publisher.md。現在發佈文章時直接說「/wordpress-blog-publisher」，Claude 自動執行完整流程。

階段 3：整合色彩編碼系統（Skill 內容品質升級）

Skill 本身沒變，但發佈的文章內容用 6 色系統標示重點，讀者一眼看懂內容層級。這是在 Skill 執行時「加價」的做法——同樣的技術流程，輸出品質更高。

從 CLAUDE.md 提取 Skill 的方法

找出候選工作流

檢視你的 CLAUDE.md，找「重複出現的多步驟序列」。常見候選包括：

• 數據爬蟲 + 清洗 + 存儲 → Collector Skill
• API 請求 + 驗證 + 回應處理 → API Integration Skill
• 代碼提交 + 測試 + 部署 → CI/CD Skill
• 內容撰寫 + SEO 檢查 + 發佈 → Publishing Skill

提取步驟和決策點

寫下完整流程，標記「決策點」（即下一步取決於上一步結果的地方）：

步驟 1：驗證認證 → 如果失敗，停止並報告錯誤
步驟 2：查詢資源 → 如果不存在，建立新資源
步驟 3：轉換數據 → 如果格式錯誤，套用修復規則
步驟 4：執行操作 → 如果超時，重試 3 次
步驟 5：驗證結果 → 如果失敗，回滾並通知

測試 Skill 執行

Skill 寫好後，執行一次完整流程並記錄結果：

1. 用真實數據執行 Skill
2. 檢查每個決策點是否如預期
3. 驗證最終輸出品質
4. 根據結果更新 Skill 文檔

何時停止改進 Skill，開始考慮 Custom Agent？

當你的 Skill 變得太複雜時（超過 500 行文檔、20+ 決策分支），考慮升級到 Custom Agent。Agent 能做的事 Skill 做不了：

• Skill：執行預定工作流，用戶提供參數
• Agent：自行規劃方法、選擇工具、適應新情況

總結

Skill 是 Hook 和 Custom Agent 之間的「黃金中間」。它足夠強大來自動化複雜工作流，又足夠簡單讓你快速編寫和維護。每個 Skill 可以節省你幾十小時的重複勞動，而只需 1-2 小時來編寫文檔。

下一步：檢查你的 CLAUDE.md，找出 5+ 步、每週重複的工作流。寫成 Skill 文件，測試一次，然後享受自動化帶來的自由。

Custom Agent 是 Claude Code 最強大的升級。當你有一個複雜角色需要跨多個任務重複執行，且這個角色需要自行決策、規劃方法時，Custom Agent 比 Skill 更合適。本篇教你如何定義 Agent 角色、撰寫 systemPrompt、配置工具存取權限、建立記憶庫，以及用 4 個真實案例驗證整個過程。

何時升級到 Custom Agent？判斷標準

Custom Agent 適合「需要自主規劃和決策的角色」。以下判斷標準會幫你決定：

1. 跨任務的相同角色：同一個人（代碼審查員、測試工程師、架構師）在 3+ 個不同項目中重複出現
2. 自主決策：Agent 不只執行流程，還要判斷「下一步該怎麼做」
3. 記憶需求：Agent 需要記住過去的決策、學到的東西，應用到新情況
4. 工具組合：Agent 需要整合多個工具（代碼庫、測試框架、API 等）來完成任務

Custom Agent 文件結構

每個 Custom Agent 放在 ~/.claude/agents/{agent-name}/ 目錄下。基本結構：

~/.claude/agents/code-reviewer/
├── AGENT.md           # Agent 定義 + systemPrompt
├── memory.md          # 記憶庫（可選）
└── tools.json         # 工具存取權限配置

AGENT.md：定義角色和 systemPrompt

---
name: code-reviewer
description: Autonomous code review agent for pull requests
type: reviewer
model: opus
---

# Code Reviewer Agent

## 角色定義

你是一個專業的代碼審查員。你的職責是：

1. **檢查代碼品質**
   - 遵循 SOLID 原則
   - 命名清晰、邏輯簡潔
   - 錯誤處理完整

2. **驗證測試覆蓋**
   - 新功能必須有測試
   - 邊界情況涵蓋
   - 整合測試通過

3. **安全審查**
   - 無 SQL injection
   - 無認證繞過
   - 敏感數據妥善處理

4. **性能檢查**
   - 無 N+1 查詢
   - 無無限迴圈
   - 資源洩漏防護

## 決策矩陣

| 問題類型 | 優先級 | 行動 |
|---------|--------|------|
| 安全漏洞 | 🔴 必須 | 要求修正後才能合併 |
| 測試缺失 | 🔴 必須 | 要求添加測試 |
| 性能問題 | 🟠 重要 | 提出改進建議 |
| 風格違規 | 🟡 可選 | 提醒但允許合併 |
| 最佳實踐 | 🟡 可選 | 提供建議供參考 |

## 記憶需求

- 記住本專案的命名習慣、架構模式、測試框架
- 記住「上次我們學到的教訓」（例：某個模式導致的問題）
- 記住團隊的標準和偏好

工具存取權限配置

在 tools.json 中定義 Agent 可以使用哪些工具：

{
  "tool_permissions": [
    {
      "tool": "bash",
      "allow_patterns": [
        "git diff",
        "git log",
        "npm test",
        "npm run lint",
        "pytest --cov"
      ],
      "deny_patterns": [
        "rm -rf",
        "git push",
        "git reset --hard"
      ]
    },
    {
      "tool": "read",
      "allow_patterns": [
        "src/**/*.{js,ts,py}",
        "tests/**/*",
        ".env.example"
      ],
      "deny_patterns": [
        ".env",
        "**/*.key",
        "**/*secret*"
      ]
    },
    {
      "tool": "github_api",
      "allow_patterns": [
        "get /repos/{owner}/{repo}/pulls/{number}",
        "get /repos/{owner}/{repo}/statuses/{sha}",
        "post /repos/{owner}/{repo}/pulls/{number}/reviews"
      ]
    }
  ]
}

記憶庫建立

Agent 可以建立 memory.md 來記住重要信息：

# Code Reviewer Memory

## 專案風格

### 命名習慣
- Classes: PascalCase (UserService, PaymentProcessor)
- Functions: camelCase (getUserById, processPayment)
- Constants: UPPER_SNAKE_CASE (MAX_RETRIES, API_TIMEOUT)
- Private: _prefixWithUnderscore

### 架構模式
- Controllers → Services → Repositories → Models
- 所有對外接口必須有 DTO
- 所有 API 端點必須有速率限制

## 常見問題歷史

### 問題 1：N+1 查詢（2024-Q1）
- **症狀**：查詢 100 個用戶導致 101 次數據庫查詢
- **根本原因**：使用 ORM lazy-loading
- **修復**：改用 join() 或 select_related()
- **檢查清單**：审查所有 ORM 查詢，確認無 lazy-loading

### 問題 2：未驗證的文件上傳（2024-Q2）
- **症狀**：用戶可以上傳任何文件類型，導致 RCE
- **根本原因**：只檢查 MIME type，未檢查內容
- **修復**：改用簽名驗證 + 沙箱掃描
- **檢查清單**：所有上傳必須經過簽名驗證

## 測試框架習慣

- 單元測試：pytest + fixtures
- 整合測試：docker-compose 環境 + pytest
- E2E 測試：Selenium/Cypress
- 覆蓋要求：≥ 80%

Custom Agent 的 4 個真實案例

案例 1：代碼審查 Agent（API 專案）

背景：團隊有 3 個項目（API、Web、Mobile），每個都有不同的 PR 進度。需要一個一致的審查標準。

Agent 定義：

• 🎯 角色：代碼審查員
• 🧠 記憶：每個專案的風格習慣 + 常見錯誤歷史
• 🛠️ 工具：git diff、GitHub API、pytest、代碼分析工具
• 📊 輸出：結構化審查評論 + 安全/測試/性能 3 個評分

結果：每個 PR 審查時間從 30 分鐘降到 5 分鐘，且審查一致性提升 95%。

案例 2：測試工程師 Agent（跨項目自動化測試）

背景：4 個項目的整合測試環境不一致。需要 Agent 自行判斷各項目的測試框架、設置環境、執行測試。

Agent 定義：

• 🎯 角色：自動化測試工程師
• 🧠 記憶：每個專案的測試框架 + 已知的不穩定測試 + 環境配置
• 🛠️ 工具：docker、bash、pytest/jest/mocha、GitHub Actions API
• 📊 輸出：測試覆蓋率報告 + 失敗分析 + 根本原因建議

結果：測試失敗不再是「為什麼失敗」而是「根本原因是什麼」，故障排除時間減少 70%。

案例 3：架構審查 Agent（系統設計諮詢）

背景：新功能設計前需要架構審查，確保不會導致後期的重構。Agent 需要理解當前系統架構，提出可維護的設計。

Agent 定義：

• 🎯 角色：系統架構師
• 🧠 記憶：當前系統架構圖 + 設計決策歷史 + 技術債清單
• 🛠️ 工具：代碼庫讀取、設計圖工具、數據庫架構查詢
• 📊 輸出：設計評估 + 風險分析 + 備選方案 (3 個等級)

結果：早期抓出設計問題，後期重構時間減少 80%。

案例 4：數據管道 Agent（ETL 自動化）

背景：多個數據源的 ETL 流程不一致。Agent 需要自行偵測數據異常、調度管道、驗證結果。

Agent 定義：

• 🎯 角色：數據工程師
• 🧠 記憶：各數據源的架構 + 已知異常情況 + 修復歷史
• 🛠️ 工具：SQL、數據庫連接、bash、監控 API
• 📊 輸出：管道執行日誌 + 數據品質評分 + 異常告警

結果：數據異常檢測從手工變自動，平均 MTTR（故障排除時間）從 4 小時降到 15 分鐘。

systemPrompt 撰寫技巧

好的 systemPrompt 是 Custom Agent 的靈魂。以下技巧會幫你寫出高效的 prompt：

結構 1：身份 + 職責 + 決策矩陣

你是 [角色名稱]。你的職責是：
1. [主要職責 1]
2. [主要職責 2]
3. [主要職責 3]

決策矩陣：
| 情況 | 優先級 | 行動 |
|------|--------|------|
| [情況 A] | 🔴 必須 | [你應該做 X] |
| [情況 B] | 🟠 重要 | [你應該做 Y] |

你的記憶：[Agent 應該記住的東西]
你的工具：[你可以使用的工具列表]

結構 2：決策樹（if-then 邏輯）

當遇到 [情況] 時：
- 如果 [條件 A]，則 [行動 A]
- 如果 [條件 B]，則 [行動 B]
- 否則 [默認行動]

例子：
當審查代碼時：
- 如果 [發現 SQL injection 漏洞]，則 [標記為 🔴 必須修正]
- 如果 [測試覆蓋 < 80%]，則 [標記為 🟠 要求添加測試]
- 如果 [風格不一致但邏輯正確]，則 [提出建議但允許合併]

結構 3：輸出格式定義

你的輸出應該遵循以下格式：

## [任務] 報告

### 摘要
[一句話總結]

### 發現
- 🔴 [必須項 1]
- 🟠 [重要項 2]
- 🟡 [可選項 3]

### 建議
1. [短期改進]
2. [中期改進]
3. [長期改進]

### 審查評分
| 維度 | 評分 | 說明 |
|------|------|------|
| 安全性 | 8/10 | [說明] |
| 測試 | 7/10 | [說明] |
| 性能 | 9/10 | [說明] |

何時停止改進 Agent，考慮 Agent Team？

當你有多個 Agent 需要協作時，考慮 Agent Team：

• 單一 Agent：「代碼審查員」審查所有 PR
• Agent Team：「代碼審查員」+ 「測試工程師」+ 「性能分析師」協作審查 PR

Agent Team 可以並行工作、互相驗證、降低單點失敗風險。但複雜度也提升了。

總結

Custom Agent 是「會思考的角色」。它不只執行流程，還能根據上下文自主決策、應用記憶、整合多個工具。如果你發現自己需要「一個人」來重複執行複雜工作，就該考慮 Custom Agent 了。

下一步：識別你的第一個重複角色。寫出清晰的 systemPrompt，配置工具權限，建立記憶庫。測試一個完整工作流，驗證 Agent 的決策品質。從簡單開始，逐步改進。

Hook 是最簡單的升級方式。只需 5 分鐘，就能強制執行安全規則。本文提供可複製的模板。

什麼是 Hook？

Hook 是在 Claude 工作流程的特定時刻自動觸發的指令。作用類似非同步程式設計的「條件判斷」和「回呼函式」。

3 種 Hook 類型

Hook 類型	何時使用	例子
PreToolUse	工具執行前阻止	阻止讀取 .env
PostToolUse	工具執行後自動化	自動執行 prettier
Stop	完成前驗證並迭代	驗證 JSON 有效性

模板 1：PreToolUse Hook（保護敏感檔案）

用途：阻止 Claude 讀取或修改 .env、secrets、credentials 檔案

// ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets'",
        "action": "block",
        "message": "❌ Cannot read .env files. Use environment variables instead."
      }
    ]
  }
}

模板 2：Stop Hook（驗證 JSON）

用途：在完成前驗證 JSON 有效性，失敗則自動重試

// ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task involves JSON",
        "validator": {
          "command": "jq empty /tmp/output.json",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON invalid. Fixing syntax..."
        }
      }
    ]
  }
}

快速 4 步實施

故障排除

下一步：
Hook 太簡單了？嘗試 Skill（複雜工作流自動化）
→ 文章 3：Skill 操作指南（1 小時深度）

不知道什麼時候該升級？本文提供 5 個判斷升級時機的具體場景，幫助你決定何時使用 Hook、Skill 或 Custom Agent。

場景 1：規則被重複違反 → 升級為 Hook

場景 2：複雜工作流重複執行 → 升級為 Skill

場景 3：跨任務的相同角色 → 升級為 Custom Agent

場景 4：CLAUDE.md 超長 → 整體升級

場景 5：成功率低於 80% → 添加 Stop Hook

決策速查表

場景	升級目標	關鍵指標
🟡 規則違反	Hook	同規則被違反 > 3 次
🟠 工作流重複	Skill	5+ 步，每週 > 1 次
🟣 角色跨任務	Agent	3+ 個相同角色
🔴 配置過長	整體升級	CLAUDE.md > 50 行
🔵 成功率低	Stop Hook	< 80% 且每週 > 1 次

下一步：
決定了你的升級目標？
→ 文章 2：Hook 操作指南（5 分鐘快速實施）