https://www.knightli.com/zh-tw/tags/%E8%87%AA%E5%8B%95%E5%8C%96/ Recent content in 自動化 on KnightLi的博客 Hugo -- gohugo.io zh-tw Fri, 01 May 2026 03:11:27 +0800 https://www.knightli.com/zh-tw/2026/05/01/claude-code-hooks-mastery-guide/ Fri, 01 May 2026 03:11:27 +0800 https://www.knightli.com/zh-tw/2026/05/01/claude-code-hooks-mastery-guide/ <p><code>claude-code-hooks-mastery</code> 是一個圍繞 <code>Claude Code Hooks</code> 的學習專案。</p> <p>它不是只給幾個零散腳本，而是把 Claude Code 的 hooks 生命週期、配置方式、腳本寫法和常見自動化場景放在一起講清楚。對想讓 Claude Code 更可控、更像工程化助手的人來說，這類資料很值得看。</p> <p>Claude Code 預設已經能讀程式碼、改檔案、跑命令。但如果你想讓它在特定時機自動檢查權限、攔截危險操作、注入專案規範、執行測試、提醒團隊規則，單靠聊天指令就不夠穩定。Hooks 的價值就在這裡：把「每次都要提醒 AI 的規則」變成可執行的流程。</p> <h2 id="hooks-解決什麼問題">Hooks 解決什麼問題 </h2><p>使用 Claude Code 一段時間後，常見痛點大概有這些：</p> <ul> <li>每次新會話都要重複告訴它專案規則</li> <li>擔心它執行不該執行的命令</li> <li>希望檔案修改前後自動做檢查</li> <li>想在提交前自動跑格式化、測試或安全掃描</li> <li>想把團隊規範寫成固定流程，而不是靠口頭提醒</li> <li>想在工具呼叫前後拿到上下文，做記錄或攔截</li> <li>希望複雜任務可以觸發子代理或專門腳本處理</li> </ul> <p>Hooks 就是為這些「固定時機的自動動作」準備的。</p> <p>你可以把它理解成 Claude Code 工作流裡的事件鉤子：當會話開始、使用者提交提示詞、模型準備呼叫工具、工具呼叫完成、代理即將結束等節點發生時，Claude Code 可以執行你配置的腳本。</p> <h2 id="13-個-hooks-生命週期">13 個 Hooks 生命週期 </h2><p>專案 README 的重點之一，是系統整理了 Claude Code 的 13 個 hook 事件。</p> <p>這些事件覆蓋了從會話開始到工具呼叫、從使用者輸入到代理結束的多個節點。按用途可以粗略分成幾類：</p> <ul> <li>會話啟動相關：用於初始化環境、注入專案上下文</li> <li>使用者輸入相關：用於檢查提示詞、補充規則、做稽核</li> <li>工具呼叫前相關：用於權限判斷、命令攔截、安全檢查</li> <li>工具呼叫後相關：用於記錄結果、觸發格式化、執行驗證</li> <li>任務結束相關：用於總結、清理、通知或保存狀態</li> </ul> <p>這種生命週期設計讓你不必把所有規則都寫進一個超長提示詞裡。</p> <p>比如，權限控制應該發生在工具呼叫前；格式化檢查更適合發生在檔案修改後；專案規範注入適合發生在會話開始或使用者輸入後。把規則放到正確的 hook 節點，通常比把所有內容塞進 system prompt 更可靠。</p> <h2 id="配置檔案在哪裡">配置檔案在哪裡 </h2><p>Claude Code 的 hooks 通常透過設定檔配置。</p> <p>常見位置包括：</p> <ul> <li>使用者級配置：<code>~/.claude/settings.json</code></li> <li>專案級配置：<code>.claude/settings.json</code></li> </ul> <p>使用者級配置適合放個人偏好，比如通用安全規則、命令攔截、日誌路徑。</p> <p>專案級配置適合放倉庫相關規則，比如這個專案必須跑什麼測試、哪些目錄不能改、生成檔案怎麼處理、提交前要做哪些檢查。</p> <p>如果你在團隊裡使用 Claude Code，更推薦把專案級配置放進倉庫。這樣每個人打開專案時，拿到的是同一套 AI 協作約束，而不是各自憑記憶提醒。</p> <h2 id="單檔案腳本為什麼重要">單檔案腳本為什麼重要 </h2><p>專案裡強調了 <code>UV</code> 單檔案腳本的寫法。</p> <p>這類腳本的好處是部署簡單。一個 Python 檔案就可以宣告依賴並執行，不必為了一個 hook 單獨維護複雜環境。對 hooks 來說，這很合適，因為很多 hook 只是做一件小事：</p> <ul> <li>檢查命令是否允許執行</li> <li>判斷檔案路徑是否安全</li> <li>讀取專案規範並返回給 Claude</li> <li>掃描輸出中是否包含敏感資訊</li> <li>在修改後執行格式化或測試</li> <li>把事件寫入日誌</li> </ul> <p>Hook 腳本越小，越容易維護，也越不容易變成新的複雜系統。</p> <h2 id="可以做哪些自動化">可以做哪些自動化 </h2><p><code>claude-code-hooks-mastery</code> 展示的方向比較多，實際工作中最常見的是下面幾類。</p> <h3 id="1-權限和安全控制">1. 權限和安全控制 </h3><p>這是 hooks 最直接的用途。</p> <p>比如在 Claude Code 準備執行命令之前，先檢查命令內容。如果命令包含刪除、重置、清空、覆蓋等高風險動作，就阻止執行或要求人工確認。</p> <p>類似規則還可以用於檔案路徑：</p> <ul> <li>不允許修改生產配置</li> <li>不允許寫入金鑰檔案</li> <li>不允許刪除遷移腳本</li> <li>不允許觸碰指定目錄</li> <li>不允許執行未批准的網路命令</li> </ul> <p>這類保護放在工具呼叫前，比寫一句「不要做危險操作」更可靠。</p> <h3 id="2-上下文注入">2. 上下文注入 </h3><p>很多專案都有固定背景：</p> <ul> <li>技術棧</li> <li>編碼規範</li> <li>測試命令</li> <li>分支策略</li> <li>目錄結構</li> <li>禁止事項</li> <li>生成檔案處理規則</li> </ul> <p>這些內容每次手動告訴 Claude Code 很麻煩，也容易漏。Hooks 可以在會話開始或使用者提交提示詞後，把必要上下文自動注入進去。</p> <p>這相當於給 Claude Code 配一個專案級的工作說明書。它不會替代 README 或開發文件，但能讓 AI 在執行任務前更快進入正確狀態。</p> <h3 id="3-修改後的驗證">3. 修改後的驗證 </h3><p>當 Claude Code 修改檔案後，可以透過 hook 自動觸發檢查。</p> <p>常見動作包括：</p> <ul> <li>執行格式化</li> <li>執行 lint</li> <li>執行單元測試</li> <li>檢查型別錯誤</li> <li>掃描生成檔案</li> <li>校驗 Markdown 或 JSON 格式</li> </ul> <p>這對減少低級錯誤很有幫助。尤其是 AI 改動多個檔案時，修改後自動跑一輪輕量驗證，可以更早發現問題。</p> <p>不過也要注意，hook 裡不適合預設塞太重的任務。每次檔案改動都跑完整測試套件，可能會讓體驗變得很慢。更實用的做法是按檔案類型、目錄和任務風險選擇檢查範圍。</p> <h3 id="4-團隊規則驗證">4. 團隊規則驗證 </h3><p>如果團隊已經有明確約定，可以把一部分約定放進 hooks。</p> <p>比如：</p> <ul> <li>提交訊息格式</li> <li>程式碼風格規則</li> <li>禁止直接修改某些生成檔案</li> <li>文件必須同步更新</li> <li>API 變更必須改測試</li> <li>某些目錄只能用指定工具生成</li> </ul> <p>這會讓 Claude Code 更像團隊流程的一部分，而不是一個不受約束的外部助手。</p> <p>當然，hooks 不應該替代 CI。它更適合做本地快速提醒和前置攔截，真正的最終驗證仍然應該交給 CI、review 和測試系統。</p> <h3 id="5-子代理和專門任務">5. 子代理和專門任務 </h3><p>README 裡還提到子代理相關內容。</p> <p>這類用法適合把複雜任務拆給更專門的流程處理。比如主會話負責理解需求，hook 或配置觸發專門的檢查、稽核、總結、文件整理任務。</p> <p>對個人使用者來說，最先值得做的不是複雜代理編排，而是把重複、明確、低風險的動作交給 hooks。等規則穩定後，再考慮更複雜的自動化。</p> <h2 id="statusline-和輸出樣式">Statusline 和輸出樣式 </h2><p>專案還覆蓋了狀態列和輸出樣式。</p> <p>這部分看起來像體驗細節，但對長期使用 Claude Code 很有意義。狀態列可以展示當前上下文、任務狀態、環境資訊或提示資訊；輸出樣式則可以讓 Claude Code 的回答更符合你的工作習慣。</p> <p>如果你每天都在同一個終端裡和 AI 協作，這些細節會影響效率。好的狀態提示能減少誤操作，也能讓你更快判斷當前會話是否處在正確專案、正確分支、正確環境裡。</p> <h2 id="不要把-hooks-寫得過重">不要把 hooks 寫得過重 </h2><p>Hooks 很強，但不適合什麼都往裡面塞。</p> <p>比較好的規則是：</p> <ul> <li>高頻動作要快</li> <li>安全攔截要明確</li> <li>輸出要短</li> <li>失敗原因要可讀</li> <li>腳本盡量單一職責</li> <li>重型檢查交給顯式命令或 CI</li> </ul> <p>如果一個 hook 每次都執行十幾秒，使用者很快就會想關掉它。如果一個 hook 攔截規則含糊不清，Claude Code 和使用者都會難以理解下一步該怎麼做。</p> <p>Hooks 最適合處理那些邊界清楚的事情：允許或拒絕、補充上下文、記錄日誌、執行輕量檢查、提示下一步。</p> <h2 id="適合怎樣的使用者">適合怎樣的使用者 </h2><p>如果你只是偶爾讓 Claude Code 改一小段程式碼，可能暫時不需要深入 hooks。</p> <p>但如果你符合下面幾種情況，就很適合研究這個專案：</p> <ul> <li>高頻使用 Claude Code</li> <li>經常讓 AI 修改真實專案程式碼</li> <li>擔心 AI 執行危險命令</li> <li>想把團隊規範自動注入 AI 工作流</li> <li>希望修改後自動跑檢查</li> <li>想把重複提醒變成配置</li> <li>正在搭建更穩定的 AI 編程流程</li> </ul> <p>尤其是多人協作專案，hooks 的意義會更明顯。它可以把一部分團隊經驗沉澱成腳本，而不是靠每個人臨時提醒 AI。</p> <h2 id="使用時要注意">使用時要注意 </h2><p>第一，先從安全類 hook 開始。</p> <p>相比複雜自動化，命令攔截、路徑保護、敏感檔案檢查更容易落地，也更能立刻降低風險。</p> <p>第二，專案級規則要謹慎提交。</p> <p><code>.claude/settings.json</code> 會影響所有使用這個倉庫的人。把規則提交前，最好確認它不會過度限制正常開發，也不會依賴只有你本機才存在的路徑。</p> <p>第三，hook 輸出要簡潔。</p> <p>Claude Code 會消費這些輸出。輸出太長，會污染上下文；輸出太模糊，又起不到指導作用。最好只返回必要判斷和下一步建議。</p> <p>第四，保持可除錯。</p> <p>Hooks 一旦變多，問題可能出在配置、腳本、權限、路徑、依賴或 Claude Code 本身。給腳本留下清楚日誌，會讓後續排查輕鬆很多。</p> <h2 id="參考">參考 </h2><ul> <li><a class="link" href="https://github.com/disler/claude-code-hooks-mastery" target="_blank" rel="noopener" >disler/claude-code-hooks-mastery</a></li> </ul> <h2 id="最後一句">最後一句 </h2><p><code>Claude Code Hooks</code> 的價值，是把「希望 AI 每次都記住的規矩」變成真正會執行的流程。</p> <p>如果你已經開始把 Claude Code 用在真實專案裡，hooks 會是從「會聊天的編程助手」走向「可約束的工程協作者」的關鍵一步。</p>