跳到主要內容

Claude Code Hooks：自動化與安全的最佳實踐

寫在最前頭，這份文章主要寫起來是給自己看，

同時內容是比較適合開發者，工程師們可以做些自動化處理的簡單筆記。

Claude Code hooks

Claude Code hooks 是一種強大的自動化機制，允許用戶在 Claude Code 的不同生命週期階段，自定義執行 shell 指令。這種設計讓開發者能夠將規則和自動化行為嵌入到應用層級，確保每次都能可靠執行，而不必依賴 LLM（大型語言模型）是否會選擇執行某項操作。

Hooks 的核心用途

  • 通知：自訂收到 Claude Code 等待用戶輸入或執行權限時的提醒方式。
  • 自動格式化：如在每次檔案編輯後自動執行 prettier（針對 .ts 檔）、gofmt（針對 .go 檔）等。
  • 日誌記錄：追蹤所有執行過的命令，便於合規或除錯。
  • 自動反饋：當 Claude Code 產生不符合團隊規範的程式碼時，自動給出反饋。
  • 自訂權限：阻擋對生產環境檔案或敏感目錄的修改[^1]。

配置與結構

Hooks 透過設定檔進行配置，分為全域（~/.claude/settings.json）、專案（.claude/settings.json）、本地專案（.claude/settings.local.json）以及企業級策略設定。每個 hook 由「事件名稱」和「匹配器」組成：

"hooks": {
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "jq -r '...'"
        }
      ]
    }
  ]
}
  • matcher：用於匹配工具名稱（支援正則表達式），如 Write、Edit|Write、Notebook.*。
  • hooks：當匹配時要執行的命令陣列。
  • type：目前僅支援 "command"。
  • command：要執行的 bash 指令。
  • timeout：可選，命令執行的最大秒數。

Hook Event 事件

事件類型 觸發時機與用途
PreToolUse 工具呼叫前，可阻擋執行並提供反饋
PostToolUse 工具執行完畢後
Notification Claude Code 發送通知時
Stop 主代理回應結束時
SubagentStop 子代理回應結束時

Hook 輸入與輸出

  • 輸入：所有 hooks 透過 stdin 接收 JSON，包含 sessionid、transcriptpath 及事件相關資料。
  • 輸出：可用 exit code 或 JSON 控制 Claude 行為。
    • exit code 0：成功。
    • exit code 2：阻擋行為，stderr 會回饋給 Claude。
    • 進階可回傳 JSON，細緻控制是否繼續、阻擋原因、是否隱藏輸出等[^1]。

範例

自動格式化程式碼

"hooks": {
  "PostToolUse": [
    {
      "matcher": "Write|Edit|MultiEdit",
      "hooks": [
        {
          "type": "command",
          "command": "/home/user/scripts/format-code.sh"
        }
      ]
    }
  ]
}

自訂通知

"hooks": {
  "Notification": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "python3 ~/my_custom_notifier.py"
        }
      ]
    }
  ]
}

安全性考量

  • 風險警告：Hooks 會以用戶權限自動執行 shell 指令，可能造成資料遺失或系統損壞，Anthropic 不負任何責任。
  • 最佳實踐：
    • 驗證與清理輸入資料。
    • 始終引用變數（"$VAR" 而非 $VAR）。
    • 防止路徑穿越（檢查 ..）。
    • 使用絕對路徑。
    • 避免處理敏感檔案（如 .env、.git/、金鑰等）。

官方範例

Claude Code hooks 官方提供的 bashcommandvalidator_example.py 範例，是一個用於「Bash 指令安全驗證」的 hook 腳本。這個範例展示了如何在 Claude Code 執行 shell 指令前，自動檢查指令內容是否符合安全規範，並攔截潛在的危險操作。其核心原理是：

  • 解析傳入的 Bash 指令，檢查是否包含多重命令串接（如 &&、||、; 等），以防止命令注入攻擊。
  • 根據預設的允許清單判斷指令前綴，僅允許特定安全命令執行，否則要求用戶審核。
  • 若發現可疑結構或注入風險，會直接阻擋執行，並將原因回饋給 Claude Code 進行提示。

這個範例腳本可作為自訂 hooks 的基礎，協助團隊在自動化流程中提升 Bash 指令的安全性。

https://github.com/anthropics/claude-code/blob/main/examples/hooks/bashcommandvalidator_example

除錯與維護

  • 使用 /hooks 檢查設定。
  • 確認設定檔為有效 JSON。
  • 手動測試命令與檢查 exit code。
  • 使用 claude --debug 追蹤 hooks 執行情況。

總結

Claude Code hooks 這樣的更新，至少讓我可以接上完成提醒事件，讓我的小腦袋瓜可以被 notify，當然也可以想到許多不同的應用情境，之前在 slack hook 裡面所採取的模式，似乎都可以動了起來。

這樣的流程提供了極高的自動化與自訂彈性，但同時帶來安全風險。建議在安全環境下充分測試，並遵循最佳實踐，才能發揮其最大效益。（畢竟就還是實實在在可以寫檔案，讀檔案，請閣下自行體驗）

參考連結

社群活動分享

如果你看完這篇文章，也開始對「怎麼用 AI 幫你加速、放大你的想法」感到興趣，那你絕對不能錯過這場活動👇

🎤 🐻 Coding Bear 台北場｜來聊什麼是 Vibe Coding 台北場

我們將深入分享如何結合 AI 與程式、創意、內容製作，

讓你用最自然的方式，讓 AI 成為你的工作室助手。

📅 時間：7/16（三）18:30

👉 報名連結：https://codingbear.kktix.cc/events/ai-vibe-coding-2025-07-taipei

天南地北來亂聊，從設計、內容到自動化，無論你是創作者還是開發者，這場講座也許會有實用又有趣的靈感（吧）。來聊聊 AI 怎麼幫你少做一點雜事、多做一點你真的想做的事吧！

標籤：

留言

張貼留言

這個網誌中的熱門文章

Vibe Coding：為什麼 Junior 更快上手？Senior 要如何追趕？

現象層面（市場觀察） 最近有篇文章討論 junior & senior 開發者在 AI 時代的角色轉變，非常熱門。 身為 Cympack 產品開發團隊 ，我們也一直關注這個議題，在閱讀這篇文章時觀察到一些有趣的現象，對我們來說，這正好反映出 AI 正在改變開發生態，junior 借力 AI 快速成長、senior 則需要在 「架構思維」 與 「多 agent 協作」 中找到新定位，其中有些啟發（insight) 可以跟大家分享。 為什麼 Junior 更容易上手 vibe coding？ 心智負擔低 → Junior 沒有太多傳統 code workflow 的框架包袱 敢於嘗鮮 → Gen Z / 年輕工程師天生習慣用 prompt-based 工具、跟 LLM 互動 少「優雅程式設計」的束縛 → 不太糾結「這樣寫會不會不夠優雅」，反而 embrace 快速迭代、快速出成果 反觀 Senior： 熟悉大型系統設計 有豐富的「工程正統流程」知識（架構設計、測試策略、效能優化、設計模式） 對 AI 生成 code 的品質 / 維護性通常比較保留 部分 10+ 年資深工程師，對 prompt engineering 沒那麼熟練，還在觀望 技能面（未來的關鍵能力） Vibe coding 本質上 = prompt engineering + AI co-pilot 管理能力 能力項目 誰目前比較有優勢？ Prompt 撰寫 / AI 互動 Junior 較強（熟悉 chat-based 流程） 系統設計 / 架構把關 Senior 較強 AI 生成 code 驗證 / Bug 察覺能力 Senior 較強（能看出潛在問題） 快速疊代 / Hackathon 式開發 Junior 較強 長期維護性 / 穩定性 Senior 較強 總結 Junior 確實更快適應 vibe coding，並且更習慣以 「chat-based coding」 的工作流開發。 Senior 擁有驗證 AI 產物與系統設計的深度能力，但若不主動練習 vibe coding，長期會逐漸落後於新一波開發潮流。 就如同在 GAI 技術年會分享，希望帶給各位的感受， 『與 AI 協...
張貼留言
繼續閱讀>>

Vibe Coding 協作到自建 Dev Agent？從 Claude / Codex 到 OpenHands

過去一年，越來越多工程師開始 把 AI 真正帶進工作流程 。從一開始用 ChatGPT、Claude 來問語法問題，到後來很多人愛上 Cursor，直接在編輯器裡讓 AI 幫忙改 code、補 test case、甚至自動整理 PR。這樣的開發體驗，已經大大改變了我們寫程式的方式。 更現實的是，在很多企業內部、政府單位、或涉及機密資料的專案裡， 其實根本不能直接用 Cursor 或雲端 LLM 工具。   畢竟這些服務通常會把資料傳到雲端模型做處理，萬一專案裡有未公開的技術、敏感客戶資料，或是受限於法規 （像金融、醫療、政府標案） ，直接用雲端 AI 工具就會踩 紅線 。  因此，許多團隊反而更希望 「自己架一套 Dev Agent」 ，可以在內網執行，資料完全掌握在自己手上，該整合的內部工具、該讀的私有 repo、該串的 CI/CD pipeline，全部客製化、安全可控。 這時候，像 OpenHands 這樣的開源 Dev Agent 框架就特別有價值。它的出發點不是單純的 AI 助手，而是讓你能夠打造出一個真的可以跑在自己環境裡、可以理解整個開發流程的 AI 工程師。從建置到部署，從 CLI 操作到瀏覽器查詢， 從多檔案編輯到自動測試，全部都能自己完成，甚至還能針對不同專案調整專屬的工作流。 對很多開始探索 AI 協作開發的團隊來說，這是一條 從 「AI 幫你寫一段程式」，走向「AI 幫你解決一整個任務」 的進化路徑。而且，還是在可控、可自定義、安全的環境裡完成的。 🧩 主要概述 OpenHands 是由 All‑Hands AI 開發的開源「軟體開發代理人平台」，能模仿人類工程師從建立程式、修改程式碼、執行指令，到瀏覽網頁、呼叫 API……等一整套開發流程 它提供雲端（OpenHands Cloud）與本地 Docker 運行版本，用戶能配置 LLM（如 Claude、OpenAI、Gemini…) 📚 核心特性與怎麼使用 代理人的工具能力 支援代碼編輯、命令行、執行環境、網頁瀏覽、API 呼叫—接近人類開發者完整技能。其中 OpenHands Cloud 版本提供 $50 試用額度讓大家方便使用，又或者如果自己本機有 docker 的話，可以自己Local 版本透過 Docker 自架環境。 ...
張貼留言
繼續閱讀>>

RAG 和 Prompt 原理超簡單解說！想知道 AI 怎麼找答案看這篇

這篇文章是給對於你已經開始使用所謂的 ChatGPT / Claude / Gemini 之類的 AI 服務，甚至是 Siri (嘿丟，他也是一種 AI 應用服務喔） 簡單來說是非 技術人員， PM，小白，想要趕快惡補的人 ，直接花十分鐘可以看完的一篇科普業配文章。 或者是概念僅止於，AI 這東西會幻想，會有誤差，會對於生活有些幫助但沒有幫助的人們，做個簡單又不是太簡單的介紹，希望用一個非常入門的方式讓你們有個了解。 當然，這篇文章目的很簡單， 就是引流 ，如果你身邊有已經對於 Web 技術開發的人員，歡迎報名分享給他，年末出國不如學一技在身，參加今年我們舉辦最後一場 RAG 實作工作坊，報名連結 ， https://exma.kktix.cc/events/ai-for-dev-course-rag-2 注意： 接下來每個大段落結束都會有一段工商導入，但文章絕對精彩，請注意！ 為了讓各位容易想像，我們將整個世界的資訊，先濃縮到這本『西遊記』的世界觀當中，我們整個世界都在這個 『西遊記』 ，而 大型語言模型 我們用 『書精靈』 來描述。 PS. 我們先預設各位，應該都有聽過，西遊記！如果沒有聽過西遊記的，請右轉出去，謝謝！ 先來談談向量 在《西遊記》的世界裡，我們可以把 向量想像成一種「內容座標」 ，讓系統知道每個角色、場景、法術等的 「位置」和「距離」 。向量幫助語言模型知道不同內容之間的關聯程度。 向量就像內容的「距離」和「位置」 比方說，唐三藏的 「位置」（向量）會接近「佛經」和「取經」 的概念，因為他一路上都是為了取經而前進。孫悟空的 向量位置則會更靠近「金箍棒」和「七十二變」 這些概念，因為這些是他的特徵。 相似內容靠得更近：像「佛經」和「取經」會靠近唐三藏的向量，因為它們彼此有很強的關聯。 相差較大內容會離得較遠：像「取經」和「妖怪」「妖怪的寶藏」就距離比較遠，因為妖怪的寶藏和取經的目標關聯性不大。 是誰決定的這些位置？ 簡單來說，這些位置和關係是模型自己學出來的。語言模型會閱讀大量的資料和這世界觀的資訊，觀察哪些詞語經常一起出現，根據「共同出現的頻率」來決定它們的關係，並且自動生成向量。例如： 如果模型看到 「唐三藏」 總是和 「取經」 一起出現，它就會讓「唐三藏」的向量靠近「取經」。 ...
2 則留言
繼續閱讀>>