Claude Code Hooks 完全指南 — 讓 AI 自動化你的開發流程

如果你已經在用 Claude Code 開發專案，你可能會想：能不能讓 AI 在執行特定動作時自動做些事情？比如寫完程式碼就自動格式化，或者執行危險指令前先攔截？

答案是：Hooks。

Hooks 是 Claude Code 藏在 .claude/settings.json 裡的強大功能，讓你在 AI 的關鍵行為節點（執行工具前、執行工具後、對話結束前）插入自訂腳本，實現自動化品質閘門、安全檢查、甚至學習回顧。

這篇文會用繁體中文帶你從零理解 Hooks，包含設定方式與三個實際可用的範例。

Hooks 是什麼？

Claude Code 的 Hooks 分為三種：

1. PreToolUse — 工具執行前觸發

在 Claude Code 呼叫任何工具（Read、Bash、Write、Edit 等）之前執行。

常見用途：

  • 危險指令攔截（rm -rf、破壞性 git 操作）
  • 權限檢查
  • 必要檔案驗證

2. PostToolUse — 工具執行後觸發

在工具執行完成後執行。這時候可以看到工具的輸出結果。

常見用途：

  • 程式碼格式化（black、prettier）
  • 語法檢查
  • 自動化測試
  • 部署後健康檢查

3. Stop — 對話結束前觸發

當使用者輸入 exit 或 Claude Code 決定結束對話時觸發。

常見用途：

  • Session 結束前的學習摘要
  • 成本追蹤統計
  • 未完成決策提醒

為什麼需要 Hooks？

以下是我認為 Hooks 最有價值的三個場景：

品質閘門（Quality Gate）

「每次 Commit 前自動檢查程式碼品質」——過去需要 CI/CD pipeline，現在一個 Hook 就能做到。

安全檢查

Claude Code 很強，但難免會執行危險指令。PreToolUse Hook 可以在 rm -rf 執行前跳出確認，或者對 DROP TABLE 直接說不。

自動化紀錄與學習

每次 Session 結束自動跑成本統計、學習摘要，把 AI 協作變成一個有記憶的系統。

設定方式

在專案或全域的 .claude/settings.json 中加入 hooks 欄位：

1
2
3
4
5
6
7

{
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "Stop": [...]
  }
}

每個 Hook 由以下元素組成：

欄位說明
matcher符合哪個工具才觸發，如 Bash、`Edit
hooks[].type目前只支援 command
hooks[].command要執行的指令，可帶環境變數如 $TOOL_INPUT
hooks[].statusMessage執行時顯示在 Claude Code 的提示文字（可選）
hooks[].timeout逾時秒數（可選，預設 30s）

實際範例

範例一：PostToolUse — 寫完 Python 自動跑 Black 格式化

當你用 Edit 或 Write 修改 .py 檔案後，自動執行 black 格式化：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

"PostToolUse": [
  {
    "matcher": "Edit|Write",
    "hooks": [
      {
        "type": "command",
        "command": "bash /path/to/hooks/auto-format.sh \"$TOOL_INPUT\"",
        "statusMessage": "Black 格式化中..."
      }
    ]
  }
]

1
2
3
4
5
6

#!/bin/bash
# auto-format.sh
FILE="$1"
if [[ "$FILE" == *.py ]]; then
    black "$FILE" 2>/dev/null && echo "✓ Black 格式化完成: $FILE"
fi

範例二：PreToolUse — Bash 指令安全攔截

在執行任何 Bash 指令前，先檢查是否為危險操作：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

"PreToolUse": [
  {
    "matcher": "Bash",
    "hooks": [
      {
        "type": "command",
        "command": "bash /path/to/hooks/pre-bash-guard.sh \"$TOOL_INPUT\"",
        "statusMessage": "安全檢查中..."
      }
    ]
  }
]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

#!/bin/bash
# pre-bash-guard.sh
# 注意：此為範例腳本，實際使用前請根據需求調整
CMD="$1"
DANGEROUS_PATTERNS=(
    "rm -rf /"
    "DROP TABLE"
    "git reset --hard"
    "mkfs"
    "dd if=/dev/zero"
)

# 使用 case 進行子字串匹配（推薦寫法）
blocked=0
for pattern in "${DANGEROUS_PATTERNS[@]}"; do
    case "$CMD" in
        *"$pattern"*)
            blocked=1
            break
            ;;
    esac
done

if [[ $blocked -eq 1 ]]; then
    echo "⚠️  危險指令已被攔截: $CMD"
    echo "若確認安全，請手動執行或修改 settings.json 中的 Hooks。"
    exit 1
fi

範例三：Stop — Session 結束前自動學習

每次對話結束前，自動生成這次 Session 的學習摘要與成本統計：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

"Stop": [
  {
    "matcher": "*",
    "hooks": [
      {
        "type": "command",
        "command": "node /path/to/hooks/session-summary.js",
        "statusMessage": "生成 Session 摘要..."
      }
    ]
  }
]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

// session-summary.js
const fs = require("fs");
const date = new Date().toISOString().slice(0, 10);

const summary = `
=== Session 回顧 (${date}) ===

這次 Session 完成了什麼？
- [在此處由 Claude 自動填入]

下次可以改進的地方：
- [同上]

花費時間：請查看 Agent Cost Guardian 的預算記錄
`;

console.log(summary);

進階用法

1. Matcher 萬用字元

Matcher說明
*所有工具
Bash僅 Bash
`EditWrite`
`ReadGlob

2. statusMessage — 友善提示

1

"statusMessage": "Python 語法檢查中..."

執行時 Claude Code 會在介面顯示這段文字，讓你知道正在發生什麼。

3. timeout — 避免卡死

1

"timeout": 30

預設 30 秒。對格式化工具或網路操作建議設 timeout，避免無限等待。

4. 多個 Hook 串聯

可以對同一個觸發點掛多個 Hook：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

"PostToolUse": [
  {
    "matcher": "Edit|Write",
    "hooks": [
      { "type": "command", "command": "black \"$TOOL_INPUT\"" },
      { "type": "command", "command": "pylint \"$TOOL_INPUT\"" },
      { "type": "command", "command": "pytest -q \"$TOOL_INPUT\"" }
    ]
  }
]

結語

Hooks 是 Claude Code 最被低估的功能之一。它把 AI 從一個「被動回答問題的工具」變成「主動參與開發流程的自動化夥伴」。

從簡單的程式碼格式化，到複雜的安全閘門與學習系統，Hooks 的可能性取決於你的開發流程需要什麼。

下一篇預告： 我們會討論如何在 Claude Code 中結合 MCP（Model Context Protocol）打造更強大的 AI 工作流。敬請期待。

參考資料

AI 指揮官手冊 — 零程式背景的 OpenClaw AI 團隊建置實戰指南
$14.90 · 8 章完整內容 + 6 份模板
了解更多 →