一位專案經理(PM)代理規劃了三項檔案範圍獨立的任務,但沒有撰寫任何程式碼。而一個 PreToolUse 鉤子阻擋了一次我強制在範圍外進行的寫入,這是在我的第一個版本鉤子阻擋了一次合法寫入之後。
agentshipped / agent-starter 是一個公開的演示儲存庫,用於該頻道影片中的示範。agent-starter 是一個最小化的 Claude Code 專案骨架:CLAUDE.md 包含工作規則,加上一個審閱子代理。這是 Agent Shipped 頻道的公開演示儲存庫;複製它並嘗試影片中的提示詞。
CLAUDE.md 專案規則是代理在每次會話中都會讀取的,而 .claude/agents/reviewer.md 是一個唯讀的審閱子代理,.claude/settings.json 則是一個阻擋包含明顯機密的提交的鉤子。
在 Agent Shipped 頻道使用此儲存庫的影片中展示:我的子代理中途停止。缺少路徑是原因之一 #Shorts · E007 · 2026-11-07。我的子代理鉤子讀取了一個空欄位。現在,一份錯誤報告以代碼 2 退出 #Shorts · E004 · 2026-11-14。在 GitHub 上查看。
多代理協作很少因為代理笨而失敗。它失敗的原因是它們發生衝突:兩項任務觸及同一個模組,一個覆蓋了另一個。這次建置嘗試了一種解決方案。一個專案經理代理只撰寫計畫,每項任務都有獨立的檔案範圍,並且一個鉤子在每次寫入時都會讀取計畫。
骨架
起點是 agent-starter,一個裸機的 Claude Code 骨架:CLAUDE.md 中有工作規則,一個審閱子代理,以及一個阻擋包含明顯機密的提交的鉤子。其中沒有任何東西可以阻止兩個代理編輯同一個檔案。
撰寫第一個閘門
我刻意要求 Claude 提供最簡單的閘門:精確比較路徑與範圍條目。提示詞中包含了三個決定:活躍任務 ID 來自環境變數 ACTIVE_TASK,否則來自一個代理無法從範圍內重寫的檔案。鉤子以代碼 2 退出,這會阻擋工具呼叫並將原因回傳給代理。沒有活躍任務時,閘門保持關閉,因此設定工作不會被鎖定。專案經理本身就是計畫中的一項任務,只有一個可寫入檔案:計畫。
第一次失敗
我讓鉤子處理一次在任務 T0 範圍內的寫入,即 docs/a.md,作為絕對路徑,這是 Claude Code 傳送它的方式:jq -n --arg p "$PWD/docs/a.md" '{tool_input:{file_path:$p}}' | ACTIVE_TASK = T0 node .claude/hooks/scope-gate.js ; echo "exit=$?"。
閘門以代碼 2 阻擋了它。範圍說的是 docs/,負載攜帶的是從檔案系統根目錄開始的完整路徑,字串比較永遠不匹配。在實際情況中,這會阻擋每個子代理的每次寫入。我寧願在終端機中用假負載發現這個問題。看看退出代碼:對 docs/ 的合法寫入被第一個閘門阻擋了。· 觀看此步驟。
修復路徑
解決方案只有一個想法:比較前進行正規化。提示詞要求鉤子根據專案目錄(CLAUDE_PROJECT_DIR,如果沒有則使用 process.cwd())解析 tool_input.file_path,使用正斜線使其成為相對路徑,並將任何以 .. 開頭的結果視為超出範圍。
如果沒有最後這條規則,src/../secrets 就會溜過前綴檢查。五個測試確定了行為:絕對和相對輸入一致,超出範圍被阻擋,遍歷被阻擋,以及沒有活躍任務表示閘門關閉。它們寫入一個臨時日誌,因此不會污染最終的計數。
證明閘門有效
同樣的假負載,兩次。對 docs/ 的合法寫入以退出代碼 0 通過。對 src/evil.js 的寫入以退出代碼 2 拒絕,訊息會指出任務、路徑以及允許的內容,因此代理可以報告而不是循環。然後我提交了鉤子及其測試。當閘門出錯時,我修復了閘門而不是將其關閉。兩次運行相同的負載:一次合法路徑的退出代碼,一次 src/evil.js 的退出代碼。· 觀看此步驟。
啟動計時:> .claude/blocked.log ; date +%s > .claude/run-start ; echo PM > .claude/active-task。清空日誌意味著從現在起其中的每一行都是真正的阻擋。活躍任務是從終端機設定的,在代理之外。如果代理可以更改該檔案,它就可以將自己提升到另一個範圍。
專案經理撰寫計畫
提示詞開頭寫道:「你是專案經理。你只撰寫 .claude/plan.json,不撰寫程式碼。」它要求執行三項小任務:T1 簡短網址輔助工具、T2 字數計數器、T3 使用說明文件。專案經理會列印重疊檢查,因此顯示的是獨立性,而不是假設。
審閱計畫
這是人工檢查點。計畫足夠小,可以在五行內讀完。jq -r '.tasks[] | .id + ": " + (.scope | join(", "))' .claude/plan.json ; git add .claude/plan.json ; git commit -m 'PM plan: three disjoint tasks' ; echo T1 > .claude/active-task。
在任何程式碼存在之前提交它,使計畫成為契約。整個分工在幾行內:檢查沒有檔案出現兩次。· 觀看此步驟。
任務 T1
主代理透過 Task 工具將一份獨立的簡報交給子代理:要建置什麼、要執行哪些命令、可以提交哪些檔案。簡報將回傳固定為四行:結果、提交、測試、待辦事項。兩個檔案都在範圍內,因此閘門保持靜默。
切換到 T2
回傳中的雜湊應與 git log --oneline -3 的頂部匹配。文字可以聲稱任何東西;雜湊存在與否是客觀的。然後 echo T2 > .claude/active-task。
強制違規
T2 代理建置字數計數器、其測試和一次提交。然後它被告知也要編輯屬於 T1 的簡短網址檔案。鉤子讀取計畫,看到任務 T2 和超出其範圍的路徑,並以代碼 2 和原因返回。編輯從未發生。代理被告知在待辦事項下報告阻擋,而不是尋找後門。
切換到 T3
cat .claude/blocked.log ; git status --short ; echo T3 > .claude/active-task。兩個訊號應該一致:阻擋日誌顯示時間、任務和路徑,而 git status 顯示沒有任何改變。日誌命名了被阻擋的路徑;git status 是第二個獨立訊號。· 觀看此步驟。
任務 T3
第三個子代理讀取兩個模組並撰寫使用說明文件。範例必須來自真實的 node -e 輸出,而不是模型的記憶體。它提交一個檔案並報告測試。
測量運行
echo "elapsed: $(( $(date +%s) - $(cat .claude/run-start) ))s" ; echo "blocked writes: $(wc -l < .claude/blocked.log)" ; git log --oneline -6 ; node --test test/*.test.js 2 >& 1 | grep -E '^# (tests|pass|fail)'。
結果:三個子代理任務在一次運行中完成,其中一次故意的超出範圍寫入被阻擋。計畫是第一次提交,然後每個任務一次提交。限制:閘門監控 Edit、Write 和 MultiEdit,而不是 Bash,因此 shell 重新導向仍然可以寫入任何地方。測量數據:經過時間、阻擋的寫入、提交、測試通過和失敗。· 觀看此步驟。
要複製的內容
一個計畫檔案,每個代理一個任務,每個任務一個範圍列表,在任何程式碼之前提交。獨立範圍,帶有專案經理必須列印的重疊檢查。一個列印任務、路徑和允許內容的 exit-2 PreToolUse 鉤子。一個任務 ID 位於代理無法觸及的範圍之外,從終端機設定。一個針對 git 檢查的四行回傳(結果、提交、測試、待辦事項)。
不僅限於 JavaScript
用 Python 編寫閘門並用 pytest 測試,而不是 node --test,或者在提交時使用 pre-commit 鉤子而不是 PreToolUse 鉤子來強制執行相同的範圍。完整運行的影片:https://youtu.be/-_t_ZsufwvU。
這些技術來自我的實際專案,在公開演示儲存庫中展示。旁白:AI 語音。會話、程式碼和錯誤都是真實的。不隸屬於 Anthropic 或任何工具供應商。