Claude Code Hooks 完整指南

總覽

什麼是 Hooks？

Hooks 是您定義的 shell 命令，它們會在 Claude Code 生命週期的特定時間點自動執行。您可以把它們想像成是為您的 AI 程式設計夥伴設定的「自動化規則」或「觸發器」。

與其在提示中反覆告訴 Claude 要遵守某些規則，不如將這些規則編碼為 Hooks，使其成為您開發環境中可靠且自動化的一部分。

為什麼要使用 Hooks？

Hooks 讓您能夠對 Claude Code 的行為進行確定性的控制，確保某些動作總是會發生。常見的使用情境包括：

入門教學

本教學將引導您建立三個 Hooks，從簡單到複雜，逐步掌握核心概念。

1您的第一個 Hook - 檔案變更日誌

我們的第一個 Hook 非常簡單：每當 Claude 儲存一個檔案時，我們就在一個日誌檔中記錄下來。這個範例不需要任何外部工具。

1. 在終端機中執行 /hooks 命令，打開 Hooks 設定介面。
2. 從事件列表中選擇 PostToolUse。這個事件會在 Claude 成功執行工具之後觸發。
3. 選擇 + Add new matcher…，輸入 Write|Edit|MultiEdit 來匹配檔案操作工具。
4. 選擇 + Add new hook…，然後輸入以下命令：

echo "Claude edited a file at $(date)" >> ~/.claude/file-edit-log.txt

5. 按 Enter 儲存 Hook。系統會詢問您儲存位置，選擇 User settings（使用者設定），這樣這個 Hook 就會在您所有的專案中生效。
6. 按 Esc 退出設定介面。

cat ~/.claude/file-edit-log.txt

2加入條件 - 使用匹配器

上一個 Hook 會在任何檔案被編輯後觸發。如果我們只想在特定工具被使用時觸發呢？這時就需要使用「匹配器」。

1. 再次執行 /hooks，選擇 PostToolUse 事件。
2. 選擇 + Add new matcher…，輸入 Bash。這樣 Hook 就只會在 Claude 執行 shell 命令後觸發。
3. 新增一個 Hook 命令：

echo "Claude ran a bash command at $(date)" >> ~/.claude/bash-log.txt

3與 Claude 互動 - 記錄執行的命令

現在，我們來挑戰一個更進階的 Hook：記錄 Claude 嘗試執行的所有 shell 命令詳細資訊。這個 Hook 會讀取 Claude 傳遞的資料，並需要 jq 工具來解析 JSON。

1. 執行 /hooks，這次選擇 PreToolUse 事件。這個事件在 Claude 準備執行一個工具（如 bash 命令）之前觸發。
2. 為這個 Hook 新增一個匹配器，輸入 Bash，這樣它就只會監控 shell 命令。
3. 選擇 + Add new hook… 並輸入以下命令：

jq -r '"COMMAND: \(.tool_input.command) | DESCRIPTION: \(.tool_input.description // "None")"' >> ~/.claude/bash-command-log.txt

這個命令會從傳入的 JSON 資料中提取 command 和 description 欄位，並將其格式化後寫入日誌檔。

核心概念

Hook 事件生命週期

Hooks 可以在 Claude Code 生命週期的多個時間點觸發。以下是主要的事件類型：

Hook 的輸入 (stdin)

每個 Hook 在執行時，都會透過標準輸入（stdin）接收一個包含上下文資訊的 JSON 物件。您可以使用 jq 或其他工具來解析它。

通用欄位

{
  "session_id": "string",
  "transcript_path": "string", // 對話記錄檔路徑
  "cwd": "string",             // Hook 被調用時的當前工作目錄
  "hook_event_name": "string"  // 觸發的 Hook 事件名稱
}

PreToolUse 的輸入範例

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../session.jsonl",
  "cwd": "/path/to/project",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "ls -a",
    "description": "List all files, including hidden ones."
  }
}

實用範例庫

這裡有一些可以直接使用的範例，幫助您快速提升效率。

1. 程式碼自動格式化

TypeScript/JavaScript (Prettier)

在 Claude 每次修改完檔案後，自動執行 Prettier 格式化。

設定:

• 事件: PostToolUse
• 匹配器: Edit|MultiEdit|Write
• Hook 命令:

# 檢查是否為 JS/TS 檔案並執行 prettier
file_path=$(jq -r '.tool_input.file_path // ""')
if [[ "$file_path" =~ \.(js|jsx|ts|tsx)$ ]] && [[ -f "$file_path" ]] && [[ -f "package.json" ]]; then
    npx --no-install prettier --write "$file_path"
    echo "✨ 已自動格式化檔案: $file_path"
fi

2. 安全防護範例

防止危險命令執行

阻止 Claude 執行可能危險的命令。

command=$(jq -r '.tool_input.command // ""')

# 檢查危險命令模式
dangerous_patterns=("rm -rf" "sudo rm" "dd if=" "mkfs" "fdisk" "> /dev/")

for pattern in "${dangerous_patterns[@]}"; do
    if [[ "$command" == *"$pattern"* ]]; then
        # 使用退出碼 2 來阻擋操作，並將 stderr 的內容傳遞給 Claude
        echo "🚫 安全警告: 已阻止潛在危險命令: $command" >&2
        echo "💡 建議: 請使用更安全的替代方案或明確指定檔案" >&2
        exit 2
    fi
done

echo "✅ 命令安全檢查通過: $command"

Hook 執行細節

執行環境與限制

• 執行超時: 預設 60 秒執行限制，可針對個別命令設定 timeout 參數
• 並行執行: 所有匹配的 Hooks 會並行執行
• 執行環境: 在當前目錄中執行，使用 Claude Code 的環境變數
• 輸入方式: 透過 stdin 接收 JSON 資料

常見工具匹配器

以下是可以在 PreToolUse 和 PostToolUse 中使用的常見工具名稱：

安全考量

重要安全原則

1. 最小權限原則: 只授予 Hook 完成任務所需的最小權限
2. 輸入驗證: 始終驗證來自 Claude 的輸入資料
3. 避免命令注入: 如果使用來自 Claude 的資料建構命令，請正確轉義
4. 定期審查: 定期檢查您的 Hook 設定和執行日誌
5. 使用絕對路徑: 在腳本中盡量使用絕對路徑指定命令，避免 PATH 被劫持
6. 避開敏感檔案: 設定規則以跳過 .env, .git/, SSH 金鑰等檔案

疑難排解

基本除錯步驟

如果您的 Hooks 無法正常運作，請依序檢查：

1. 檢查配置 - 執行 /hooks 查看您的 Hook 是否已註冊
2. 驗證語法 - 確保 JSON 設定有效
3. 測試命令 - 先手動執行 Hook 命令
4. 檢查權限 - 確保腳本檔案具有執行權限
5. 查看日誌 - 使用 claude --debug 查看詳細的 Hook 執行資訊

啟用詳細日誌

使用 --debug 標誌啟動 Claude Code 以查看詳細的日誌輸出：

claude --debug

最佳實踐總結

✅ 推薦做法

1. 從簡單開始: 先實作基本的日誌記錄，再逐步加入複雜功能
2. 分層設定: 通用規則放在使用者設定，專案特定規則放在專案設定
3. 充分測試: 在安全環境中測試所有 Hook 再部署到生產環境
4. 詳細註釋: 在設定檔中為每個 Hook 添加說明註釋
5. 定期維護: 定期檢查和更新 Hook 設定，移除不需要的規則

❌ 避免事項

1. 過度複雜化: 避免在單一 Hook 中包含過多邏輯
2. 忽略錯誤處理: 確保 Hook 能夠妥善處理異常情況
3. 硬編碼路徑: 使用相對路徑或環境變數而非絕對路徑
4. 忽略效能: 避免在 Hook 中執行耗時操作
5. 盲目信任: 不要無條件信任來自外部的 Hook 設定

結語

Claude Code Hooks 是一個強大的自動化工具，能夠顯著提升您的開發效率和程式碼品質。透過合理的設定和使用，您可以：

記住，Hooks 的真正價值在於讓您專注於創造性的工作，而將重複性的、規則化的任務交給自動化系統處理。

開始您的 Claude Code Hooks 之旅，讓 AI 助手成為您開發團隊中最可靠的成員！

參考資源

• Claude Code 官方文件
• jq 官方教學
• Shell 腳本最佳實踐
• JSON Schema 驗證