【AI 自動化測試】附錄:用 Claude Code 的 Hook 限制 AI 行為
本篇是〈三、三階段流程〉裡「實體鎖」的技術補充。這道鎖是用 Claude Code 的 Hook 機制、搭配一個標記檔實作的;本附錄說明它具體怎麼運作。
關鍵點
我們在 〈三、三階段流程〉 中,禁止 AI 讀程式碼所使用的 `.phase0-lock` 本身不會擋任何東西,它只是一個「開關」標記;真正動手擋的,是一個叫 hook 的機制。兩者要合起來看。
1. 什麼是 hook
這套流程跑在 Claude Code 這個 AI 工具上。它有一個功能叫 hook:可以指定「在 AI 每次要用工具之前,先自動跑一支腳本」,這支腳本會檢查 AI 想做什麼,然後回答「放行」或「擋下」。
其中一種叫 PreToolUse hook:AI 每次要讀檔(Read)、搜尋(Grep/Glob)、或下 shell 指令(Bash/PowerShell)之前,Claude Code 都會先把「AI 打算做的這個動作」交給這支腳本審一遍,腳本說可以才真的做,說不行就直接擋掉,那個動作根本執行不了。
這支審查腳本就是 `phase0_guard.py`,掛在專案的 `.claude/settings.json` 裡,指定 Read/Grep/Glob/Bash/PowerShell 這幾種工具都要先經過它。
2. `.phase0-lock` 的角色
`phase0_guard.py` 每次被呼叫時,判斷邏輯大致如下:
第一步:專案根目錄有沒有 .phase0-lock 這個檔?
├─ 沒有 → 代表已經定案解鎖,全部放行,直接結束。
└─ 有 → 代表還在階段一(鎖定中),進第二步。第二步(鎖定中才做):看 AI 這次想碰的路徑/指令是什麼
├─ 想讀的是「應用程式源碼」(前端 web 資料夾、後端 Java、.vue 檔…) → 擋下。
└─ 想讀的是規格文件、測試專案、工具 這些該讀的 → 放行。所以 `.phase0-lock` 就是一個開關檔:它在,鎖就生效;把它刪掉,鎖就解除。檔案本身是空的,每次跑的時候,`phase0_guard.py` 要確認它是否「存在」。
3. 一次實際的攔截長怎樣
(1) AI 想讀 `frontend/src/components/List.vue`,看某欄怎麼排序,於是發出一個 Read 動作。
Get 石南’s stories in your inbox
Join Medium for free to get updates from this writer.
(2) 在真的讀到之前,Claude Code 先把這個動作 `{工具: Read, 路徑: frontend/…/List.vue}` 丟給 `phase0_guard.py`。
(3) 腳本檢查:`.phase0-lock` 在 → 鎖定中;這路徑是前端源碼 → 回傳「擋下」(技術上是給一個「拒絕」的結果,例如非 0 的 exit code 帶一段訊息)。
(4) Claude Code 收到「擋下」,就不執行這個 Read,並把「動作被擋、原因是階段一鎖定」回饋給 AI。
(5) AI 讀不到那個檔,只好回頭照規格推論。
4. 為什麼連 shell 繞路也擋得住
如果只擋 Read,AI 可能改用 `cat frontend/xxx.vue` 或 `grep` 去翻源碼繞過去。所以這個 hook 不只掛在 Read,也掛在 Grep、Glob、Bash、PowerShell 上,這幾條讀取的路都要先過審,把其他路徑一起堵住。
5. 為什麼這比 AI 自律更有保障
重點在於:這支審查腳本跑在 Claude Code 的框架裡,在 AI 的控制範圍之外。AI 沒辦法叫它不要跑、也沒辦法忽略它的否決。就算 AI「想」讀、或有人下指令叫它讀,框架都會在動作真的發生前把它攔掉。所以擋讀碼這件事不靠純粹下指令,而是靠工具層強制執行。
6. 生命週期
- 階段一開工前:在專案根目錄建一個空的 `.phase0-lock`(hook 早就掛在 settings 裡)。
- 階段一進行中:AI 一切讀源碼的路都被擋,只能讀規格、測試檔、工具;於是預期結果只能從規格+資料庫推論。
- 人類下決定、預期凍結後:把 `.phase0-lock` 刪掉。腳本下次一看檔案不在,就全部放行,進階段二,AI 這才開始讀程式寫腳本。
小結
總結來說,這道鎖由兩個元件構成:狀態標記檔 `.phase0-lock`,以及掛在 PreToolUse 的審查腳本 `phase0_guard.py`。前者的存在與否代表鎖定狀態,後者在每一次工具呼叫執行前檢查狀態,並在鎖定的期間,攔下所有讀取程式碼的動作。
由於這道檢查在 AI 的控制範圍之外,並且由框架強制執行,「預期凍結前不讀程式碼」便從一條靠自律遵守的規定,變成工具層保證的結果。這也給了我們一個啟示,若要有效的限制 AI 的行為,透過系統上不可跨越的硬性限制,或是設定在 AI 能涉及的 Scope 之外,會更具有強制力。










