Hooks on KnightLi的博客

Claude Code Hooks Mastery：13 個 Hooks 生命週期與自動化控制入門

Fri, 01 May 2026 03:11:27 +0800

claude-code-hooks-mastery 是一個圍繞 Claude Code Hooks 的學習專案。

它不是只給幾個零散腳本，而是把 Claude Code 的 hooks 生命週期、配置方式、腳本寫法和常見自動化場景放在一起講清楚。對想讓 Claude Code 更可控、更像工程化助手的人來說，這類資料很值得看。

Claude Code 預設已經能讀程式碼、改檔案、跑命令。但如果你想讓它在特定時機自動檢查權限、攔截危險操作、注入專案規範、執行測試、提醒團隊規則，單靠聊天指令就不夠穩定。Hooks 的價值就在這裡：把「每次都要提醒 AI 的規則」變成可執行的流程。

Hooks 解決什麼問題

使用 Claude Code 一段時間後，常見痛點大概有這些：

每次新會話都要重複告訴它專案規則
擔心它執行不該執行的命令
希望檔案修改前後自動做檢查
想在提交前自動跑格式化、測試或安全掃描
想把團隊規範寫成固定流程，而不是靠口頭提醒
想在工具呼叫前後拿到上下文，做記錄或攔截
希望複雜任務可以觸發子代理或專門腳本處理

Hooks 就是為這些「固定時機的自動動作」準備的。

你可以把它理解成 Claude Code 工作流裡的事件鉤子：當會話開始、使用者提交提示詞、模型準備呼叫工具、工具呼叫完成、代理即將結束等節點發生時，Claude Code 可以執行你配置的腳本。

13 個 Hooks 生命週期

專案 README 的重點之一，是系統整理了 Claude Code 的 13 個 hook 事件。

這些事件覆蓋了從會話開始到工具呼叫、從使用者輸入到代理結束的多個節點。按用途可以粗略分成幾類：

會話啟動相關：用於初始化環境、注入專案上下文
使用者輸入相關：用於檢查提示詞、補充規則、做稽核
工具呼叫前相關：用於權限判斷、命令攔截、安全檢查
工具呼叫後相關：用於記錄結果、觸發格式化、執行驗證
任務結束相關：用於總結、清理、通知或保存狀態

這種生命週期設計讓你不必把所有規則都寫進一個超長提示詞裡。

比如，權限控制應該發生在工具呼叫前；格式化檢查更適合發生在檔案修改後；專案規範注入適合發生在會話開始或使用者輸入後。把規則放到正確的 hook 節點，通常比把所有內容塞進 system prompt 更可靠。

配置檔案在哪裡

Claude Code 的 hooks 通常透過設定檔配置。

常見位置包括：

使用者級配置：~/.claude/settings.json
專案級配置：.claude/settings.json

使用者級配置適合放個人偏好，比如通用安全規則、命令攔截、日誌路徑。

專案級配置適合放倉庫相關規則，比如這個專案必須跑什麼測試、哪些目錄不能改、生成檔案怎麼處理、提交前要做哪些檢查。

如果你在團隊裡使用 Claude Code，更推薦把專案級配置放進倉庫。這樣每個人打開專案時，拿到的是同一套 AI 協作約束，而不是各自憑記憶提醒。

單檔案腳本為什麼重要

專案裡強調了 UV 單檔案腳本的寫法。

這類腳本的好處是部署簡單。一個 Python 檔案就可以宣告依賴並執行，不必為了一個 hook 單獨維護複雜環境。對 hooks 來說，這很合適，因為很多 hook 只是做一件小事：

檢查命令是否允許執行
判斷檔案路徑是否安全
讀取專案規範並返回給 Claude
掃描輸出中是否包含敏感資訊
在修改後執行格式化或測試
把事件寫入日誌

Hook 腳本越小，越容易維護，也越不容易變成新的複雜系統。

可以做哪些自動化

claude-code-hooks-mastery 展示的方向比較多，實際工作中最常見的是下面幾類。

1. 權限和安全控制

這是 hooks 最直接的用途。

比如在 Claude Code 準備執行命令之前，先檢查命令內容。如果命令包含刪除、重置、清空、覆蓋等高風險動作，就阻止執行或要求人工確認。

類似規則還可以用於檔案路徑：

不允許修改生產配置
不允許寫入金鑰檔案
不允許刪除遷移腳本
不允許觸碰指定目錄
不允許執行未批准的網路命令

這類保護放在工具呼叫前，比寫一句「不要做危險操作」更可靠。

2. 上下文注入

很多專案都有固定背景：

技術棧
編碼規範
測試命令
分支策略
目錄結構
禁止事項
生成檔案處理規則

這些內容每次手動告訴 Claude Code 很麻煩，也容易漏。Hooks 可以在會話開始或使用者提交提示詞後，把必要上下文自動注入進去。

這相當於給 Claude Code 配一個專案級的工作說明書。它不會替代 README 或開發文件，但能讓 AI 在執行任務前更快進入正確狀態。

3. 修改後的驗證

當 Claude Code 修改檔案後，可以透過 hook 自動觸發檢查。

常見動作包括：

執行格式化
執行 lint
執行單元測試
檢查型別錯誤
掃描生成檔案
校驗 Markdown 或 JSON 格式

這對減少低級錯誤很有幫助。尤其是 AI 改動多個檔案時，修改後自動跑一輪輕量驗證，可以更早發現問題。

不過也要注意，hook 裡不適合預設塞太重的任務。每次檔案改動都跑完整測試套件，可能會讓體驗變得很慢。更實用的做法是按檔案類型、目錄和任務風險選擇檢查範圍。

4. 團隊規則驗證

如果團隊已經有明確約定，可以把一部分約定放進 hooks。

比如：

提交訊息格式
程式碼風格規則
禁止直接修改某些生成檔案
文件必須同步更新
API 變更必須改測試
某些目錄只能用指定工具生成

這會讓 Claude Code 更像團隊流程的一部分，而不是一個不受約束的外部助手。

當然，hooks 不應該替代 CI。它更適合做本地快速提醒和前置攔截，真正的最終驗證仍然應該交給 CI、review 和測試系統。

5. 子代理和專門任務

README 裡還提到子代理相關內容。

這類用法適合把複雜任務拆給更專門的流程處理。比如主會話負責理解需求，hook 或配置觸發專門的檢查、稽核、總結、文件整理任務。

對個人使用者來說，最先值得做的不是複雜代理編排，而是把重複、明確、低風險的動作交給 hooks。等規則穩定後，再考慮更複雜的自動化。

Statusline 和輸出樣式

專案還覆蓋了狀態列和輸出樣式。

這部分看起來像體驗細節，但對長期使用 Claude Code 很有意義。狀態列可以展示當前上下文、任務狀態、環境資訊或提示資訊；輸出樣式則可以讓 Claude Code 的回答更符合你的工作習慣。

如果你每天都在同一個終端裡和 AI 協作，這些細節會影響效率。好的狀態提示能減少誤操作，也能讓你更快判斷當前會話是否處在正確專案、正確分支、正確環境裡。

不要把 hooks 寫得過重

Hooks 很強，但不適合什麼都往裡面塞。

比較好的規則是：

高頻動作要快
安全攔截要明確
輸出要短
失敗原因要可讀
腳本盡量單一職責
重型檢查交給顯式命令或 CI

如果一個 hook 每次都執行十幾秒，使用者很快就會想關掉它。如果一個 hook 攔截規則含糊不清，Claude Code 和使用者都會難以理解下一步該怎麼做。

Hooks 最適合處理那些邊界清楚的事情：允許或拒絕、補充上下文、記錄日誌、執行輕量檢查、提示下一步。

適合怎樣的使用者

如果你只是偶爾讓 Claude Code 改一小段程式碼，可能暫時不需要深入 hooks。

但如果你符合下面幾種情況，就很適合研究這個專案：

高頻使用 Claude Code
經常讓 AI 修改真實專案程式碼
擔心 AI 執行危險命令
想把團隊規範自動注入 AI 工作流
希望修改後自動跑檢查
想把重複提醒變成配置
正在搭建更穩定的 AI 編程流程

尤其是多人協作專案，hooks 的意義會更明顯。它可以把一部分團隊經驗沉澱成腳本，而不是靠每個人臨時提醒 AI。

使用時要注意

第一，先從安全類 hook 開始。

相比複雜自動化，命令攔截、路徑保護、敏感檔案檢查更容易落地，也更能立刻降低風險。

第二，專案級規則要謹慎提交。

.claude/settings.json 會影響所有使用這個倉庫的人。把規則提交前，最好確認它不會過度限制正常開發，也不會依賴只有你本機才存在的路徑。

第三，hook 輸出要簡潔。

Claude Code 會消費這些輸出。輸出太長，會污染上下文；輸出太模糊，又起不到指導作用。最好只返回必要判斷和下一步建議。

第四，保持可除錯。

Hooks 一旦變多，問題可能出在配置、腳本、權限、路徑、依賴或 Claude Code 本身。給腳本留下清楚日誌，會讓後續排查輕鬆很多。

參考

disler/claude-code-hooks-mastery

最後一句

Claude Code Hooks 的價值，是把「希望 AI 每次都記住的規矩」變成真正會執行的流程。

如果你已經開始把 Claude Code 用在真實專案裡，hooks 會是從「會聊天的編程助手」走向「可約束的工程協作者」的關鍵一步。

Claude Code 環境配置四件套：CLAUDE.md、Rules、Memory、Hooks 一次講清

Thu, 23 Apr 2026 10:43:40 +0800

如果你用了 Claude Code 一段時間，很快就會發現一件事：模型本身當然重要，但你給它什麼環境、什麼邊界、什麼規則，同樣重要。

很多人一開始會把注意力放在「這次 prompt 要怎麼寫」，但真正把 Claude Code 用成熟之後，你會更在意另一件事：

它知不知道你是誰
它知不知道你怎麼工作
它知不知道哪些規則不能違反
它知不知道哪些事情必須先確認
它能不能長期記住這些邊界

Claude Code 之所以能變成一個成熟工具，不只是因為模型強，而是因為它有一整套機制，幫你把這些工作方式沉澱下來。核心上可以拆成四層：

CLAUDE.md
Rules
Memory
Hooks

這篇文章就把這四個部分一次講清楚。

為什麼環境配置比單次提示詞更重要

你可以把 Claude Code 想成你請來的一位助理。

第一天上工時，你不會只跟他說一句「幫我做事」，而是會給他一份說明書，告訴他：

你的身份是什麼
你的溝通語氣偏好是什麼
哪些操作必須先確認
哪些錯誤以前犯過、之後不能再犯
這個專案最重要的文件放在哪裡

這就是為什麼，長期來看，環境配置往往比單次 prompt 更重要。

因為 prompt 解決的是「這一次要做什麼」，而環境配置解決的是「以後每次都要怎麼做」。

第一層：`CLAUDE.md`

先從最基礎的開始。CLAUDE.md 本質上就是一個文字檔。

你可以在裡面寫給 Claude 的說明，例如：

你是誰
你在做什麼
你的溝通偏好
需要遵守的規則
當前專案的特殊背景
重要文件或目錄的位置

每次 Claude Code 啟動時，這份文件都會自動被送進上下文，所以模型一定會讀到。

我通常把它叫做「默契檔」，因為它本質上就是你和模型之間長期協作的默契。

`CLAUDE.md` 適合寫什麼

最適合寫進 CLAUDE.md 的，大致有這幾類：

身份與工作背景
溝通語氣與輸出偏好
全域性的行為規則
常會用到的重要專案背景
常見錯誤與避免方式

例如：

你的時區
你是否接受模型直接發送郵件或訊息
哪些操作屬於不可逆行為
你處理文件與檔案的習慣
安全規範與敏感資訊邊界

一個很重要的原則：盡量精簡

CLAUDE.md 有一個很重要的原則，就是一定要盡量精簡。

原因很簡單：它每次都會被強制注入上下文。

如果你寫得太長，就會佔掉大量上下文空間，導致真正重要的資訊被稀釋。模型不是不讀，而是注意力會分散，最後更容易漏掉你最在意的規則。

官方建議通常是最好不要超過 400 行。

我自己的習慣會更保守一些，盡量控制在 200 行以內。

`CLAUDE.md` 的常見作用範圍

CLAUDE.md 實際上有不同的放置層級，對應不同的作用範圍。最常用的是兩個：

1. User Level

這是全域層級。

它放在你的電腦環境裡，對你本機操作的所有專案都有效。

這個位置適合放：

你的身份資訊
通用的溝通偏好
你跨專案都適用的做事習慣
全域性的安全規則

例如，如果你的時區不是常見的預設值，而是曼谷時間，那這類資訊就很適合放在 user level，這樣模型之後幫你安排時間時就不容易出錯。

2. Project Level

這是專案層級。

它放在具體專案目錄下面，只對那個專案有效。

這個位置適合放：

專案專屬背景
只在這個專案裡成立的規則
專案目錄結構說明
這個專案的重要文件入口

舉例來說，如果一個專案處理財務，另一個專案處理人事，那兩邊的背景和限制顯然不同，就不應該混在同一個全域說明裡。

怎麼判斷該放哪一層

判斷方式其實很簡單：

你寫進去的東西，如果換到另一個專案裡還成立，那就放 user level。

如果一換專案就不成立，那就放 project level。

怎麼開始寫第一版

最常見的起手方式有兩種：

1. 用 `/init`

你可以直接在終端執行斜線命令 /init，讓 Claude 掃描目前專案，自動幫你生成一份基礎版 CLAUDE.md。

2. 讓 Claude 幫你整理

你也可以直接讓 Claude 去搜尋別人怎麼寫 CLAUDE.md，再結合你的情況問你問題，最後幫你整理成適合你自己的版本。

很多時候，這會比自己從零開始寫輕鬆得多。

一個很實用的習慣

在你和 Claude 長期協作的過程中，只要你發現某件事情屬於「以後一定要記住、不要再犯」的內容，就可以直接讓它寫進 CLAUDE.md。

不過寫之前，還是要先判斷：

這是全域規則
還是目前專案規則

不要把所有東西都塞進同一個檔案裡。

第二層：`Rules`

接下來是 Rules。

它和 CLAUDE.md 最大的差別，不是檔案形式，而是載入方式。

CLAUDE.md 是無論你做什麼，模型都會讀到。

而 Rules 的優勢在於：可以條件載入。

也就是說，只有在某些路徑、某些檔案、某些工具或某些場景下，這條規則才會被讀到。

為什麼條件載入很重要

因為上下文空間永遠是稀缺資源。

如果所有規則都無差別塞進上下文裡，就會發生兩件事：

模型負擔變重
真正關鍵的規則反而被淹沒

按需載入的價值就在這裡：讓模型在剛好的時候讀到剛好的資訊。

什麼時候該把規則從 `CLAUDE.md` 挪到 `Rules`

通常有兩種情況：

1. `CLAUDE.md` 太長了

如果你的 CLAUDE.md 開始超過 200 行，規則越來越多，重要內容被稀釋，那就該考慮把一部分規則拆出去。

2. 某些規則只和特定路徑相關

如果你已經很明確知道某些規則只在某些類型的檔案裡才有意義，例如：

只對 Python 腳本有效
只對某個 hooks 目錄有效
只對某個子專案有效

那這些規則就更適合移到 Rules。

`Rules` 最適合的場景

最典型的就是「特定情境、特定路徑、特定檔案類型」。

例如：

只在處理 hook 檔案時觸發的規範
只在某類腳本中要遵守的編碼規則
只在某個目錄下適用的工作方式

這些內容如果繼續塞在 CLAUDE.md 裡，其實不太划算。

第三層：`Memory`

第三個層面是 Memory。

它和 CLAUDE.md、Rules 一樣，也會進入模型上下文，但它最核心的差別是：

CLAUDE.md 是你主動設定的。

Memory 更像是 Claude 在協作過程中，寫給自己的筆記。

`Memory` 記的是什麼

當 Claude 判斷某件事值得記住，或需要短期保留，它就會把這些內容寫進 Memory。

常見內容包括：

你糾正過它的某種做法
你最近新增的偏好
當前專案的暫時狀態
你今天沒做完、明天還要繼續的事
你最近在跟哪些人合作
某些最近才提到的個人資訊或上下文

換句話說，Memory 更像動態知識，而不是長期制度。

`Memory` 和前兩者的差別

一個簡單的區分方式是：

CLAUDE.md / Rules：偏長期、偏制度、偏明確規則
Memory：偏暫時、偏動態、偏工作過程中的新理解

如果某件事只是在最近幾天有效，或專案狀態持續在變，那它通常更適合放進 Memory，而不是寫成長期規則。

`Memory` 也可以手動寫

雖然 Memory 有自動整理能力，但你也可以主動告訴 Claude：

請記下來我明天要做什麼
請記下來我要追蹤誰的狀態
請記下來這個月某個專案的關鍵節點

它也可以幫你寫進 Memory。

你也可以透過斜線命令 /memory 查看目前有哪些記憶，並手動編輯或刪除。

不過很多時候，我自己不會太頻繁手動維護，因為 Claude 本身也會定期整理這些記憶，把已經過時的部分清掉。

第四層：`Hooks`

最後也是最重要、最進階的一層，就是 Hooks。

前面講到的 CLAUDE.md、Rules、Memory，本質上都還是自然語言說明。

你寫了規則，模型通常會遵守，但它本質上仍然是在「理解之後再執行」。

只要還停留在自然語言，就會存在幾個問題：

模型偶爾會漏掉
規則太多時，注意力會分散
某些情境下，它會自己判斷這條規則不重要

這不是你寫得不夠認真，而是自然語言規則本來就很難做到 100% 強制。

`Hooks` 的本質是什麼

Hooks 不再是自然語言說明，而是一段腳本。

它是事件觸發的、程式層級的強制邏輯。

只要某個事件發生，這段邏輯就一定會執行，不會被模型「自己判斷後略過」。

這就是 Hooks 最關鍵的價值：

把「建議遵守」變成「必須執行」。

什麼時候該上 `Hooks`

當你發現某條規則已經寫進 CLAUDE.md 或 Rules，但 Claude 偶爾還是不執行，而且這件事一旦漏掉，風險又很大，那就應該考慮把它改成 Hooks。

簡單說：

低風險的，用規則
高風險的，用 Hooks

最典型的 `Hooks` 場景

最典型的，就是那些你絕對不希望出錯的動作，例如：

發郵件前必須確認
發 Slack、Outlook、Gmail 訊息前必須確認
刪除危險檔案前必須攔截
偵測到要外發密碼或 API Key 時必須阻止

如果這些要求只是寫成一句自然語言規則，模型有可能哪天真的忙中出錯，就送出去了。

但如果寫成 Hooks，只要事件發生，就會被強制攔截。

這才是程式層面的硬防線。

`Hooks` 常見的觸發時機

Hooks 可以設定在很多不同階段，例如：

對話剛開始時注入提醒
某個工具執行前先做檢查
某個工具執行後做結果校驗

你不一定需要自己知道那些專業術語。

很多時候，只要你能清楚描述需求，再讓 Claude 幫你判斷這條規則適不適合改成 hook，它就能幫你一起設計。

你也可以透過斜線命令 /hook 查看系統目前已經設定了哪些 hooks。

一套更實用的上手順序

如果你想把這四層串起來，我自己更推薦下面這條路徑：

第一步：先用 `/init` 生成基礎版 `CLAUDE.md`

不要一開始就手寫一份特別完整的規則文件。

先讓 Claude 幫你掃描專案，生成一個起點版本，再慢慢迭代。

第二步：邊用邊補

在協作過程中，只要你發現：

這件事以後一定要記得
這個錯誤以後不能再犯
這個偏好以後每次都適用

就讓 Claude 幫你寫進 CLAUDE.md。

第三步：當 `CLAUDE.md` 變長時，拆到 `Rules`

一旦你發現 CLAUDE.md 越來越長，模型開始不一定遵守每一條規則，就該考慮拆分：

哪些是全域規則
哪些只和某些路徑相關

把後者移到 Rules，改成條件載入。

第四步：再把高風險規則升級成 `Hooks`

如果某些規則即使寫了，模型還是偶爾會漏，而且漏掉代價很高，那就不要再停留在自然語言層面，直接升級成 Hooks。

也就是把「提醒」變成「強制」。

第五步：把暫時狀態交給 `Memory`

對於那些會過期、會變化、不是長期制度的內容，不要一股腦全寫進 CLAUDE.md。

更合適的做法是交給 Memory：

當前專案進度
最近合作對象
最近新增偏好
近期計畫和待辦

這樣上下文會更清爽，模型也更容易保持穩定表現。

這四層分別該記什麼

如果你想快速記住，可以直接用下面這個區分：

CLAUDE.md：長期默契、全域說明、專案基礎背景
Rules：按路徑或場景載入的專項規則
Memory：動態知識、暫時狀態、最近學到的東西
Hooks：高風險操作的程式級強制攔截

結語

很多人把 Claude Code 當成「會寫程式的聊天介面」，但真正用深之後，你會發現它更像一個長期協作的智慧工作台。

關鍵不只是你每次怎麼下指令，而是你有沒有給它一套穩定、清楚、能長期累積的環境。

一旦你把這四層搭起來：

CLAUDE.md
Rules
Memory
Hooks

你和模型之間的協作品質，通常會有非常明顯的提升。

因為你終於不是每次都從零開始解釋自己是誰、怎麼工作、哪些事不能做，而是把這些真正沉澱成了環境的一部分。

這才是把一個強模型，真正用成成熟工具的關鍵一步。