解剖一個Claw：84個Hook作為編排層

第一個hook只花了四分鐘就寫完。它阻止模型在純Anthropic的工作流程中推薦OpenAI產品。兩個月後，這單一的hook變成了84個。這84個hook連接了43個skill、19個專門代理和30個程式庫模組。在某個時間點，這些集合不再只是一組腳本，而是成為了一個編排層。

「Claw」是建構在AI代理CLI之上的編排層，負責排程、上下文管理、工具路由與品質執行。它是從解決個別失敗中有機成長而來，而非由上而下設計。其架構對應到Karpathy指出的五種功能，而規劃與執行的分離，則是hook式系統自然浮現的屬性。

我並非刻意如此設計。沒有人會坐下來說「我要建構15,000行的代理基礎設施」。您解決一個問題，然後另一個，接著解決問題之間互相影響的問題。當您注意到架構時，它已經存在了。

Andrej Karpathy也注意到了。2026年2月，他將「Claws」描述為一個新的計算層：建構在LLM代理之上的編排、排程、上下文管理和工具路由，就像代理建構在LLM之上一樣。¹這個框架把實踐者一直在建構卻未曾命名的東西具象化了。本文是這樣一個系統的解剖：它包含什麼、如何成長、哪裡有效、哪裡失敗。

TL;DR

Karpathy的「Claws」層描述了建構在代理CLI之上的編排系統。我在Claude Code上經過兩個月有機地建構了一個：84個hook橫跨15種事件類型、43個skill、19個代理和30多個程式庫模組。該系統清楚地對應到五個Claws功能（編排、排程、上下文管理、工具路由、品質執行），但有一個顯著缺口（宣告式工作流程定義）。關鍵發現：規劃與執行的分離是hook式編排的自然屬性，而非設計目標。Lattner觀察到「判斷力與抽象能力仍是核心，而AI自動化實作」，這直接對應到hook架構：治理hook行使判斷力，自動化hook執行實作。

Claws分類法

Karpathy的描述指出了Claws層執行的五種功能。每種功能在我過去兩個月於Claude Code上建構的hook系統中都有直接對應。¹

這個分類法之所以有用，是因為它分離了實踐者傾向以糾纏方式建構的關注點。我早期的hook將上下文管理與品質執行混在一起。成本追蹤hook同時注入預算上下文（上下文管理）並阻擋昂貴操作（品質執行）。將這些分離成獨立的hook提升了可靠性，因為每個hook可以獨立失敗而不破壞另一個功能。

完整系統

截至2026年2月的數據：

Hook在各事件類型的分佈揭示了編排複雜度集中之處：

UserPromptSubmit承載最多權重，因為它在每條使用者訊息時觸發。調度器（prompt-dispatcher.sh）在每個prompt上依序執行九個hook：安全過濾、分析、使用追蹤、系統監控、目標注入、時間估計阻擋、上下文注入、記憶主題注入和上下文壓力監控。²

每個hook都會增加延遲。九個循序hook在每個prompt上總共增加實測200毫秒。調度器循序執行它們（而非平行），因為在早期測試中，並行hook寫入共用JSON狀態檔案會導致資料損毀。兩個hook同時寫入jiro.state.json產生了截斷的JSON，破壞了每個下游hook。循序執行較慢但安全。200毫秒的開銷對使用者來說是無感的，因為人類打字速度才是瓶頸，而非hook延遲。

如何成長

成長並非線性。它遵循「問題、解決方案、整合」的循環模式。

第一階段：單一用途hook（第1至2週）。 每個hook解決一個問題。enforce-opus-model.sh阻擋非Opus模型請求。no-time-estimates.sh移除回應中的工作量估計。filter-sensitive.sh捕捉工具呼叫中的憑證。這些hook獨立運作，沒有任何hook知道其他hook的存在。

第二階段：協調問題（第3至4週）。 Hook開始互相干擾。憑證過濾器阻擋了合法的API呼叫。模型執行器與子代理產生發生衝突。解決方案：調度器。一個單一進入點（prompt-dispatcher.sh）取代了七個獨立的UserPromptSubmit hook，透過快取的stdin管道控制執行順序並共享狀態。

第三階段：複合能力（第5至8週）。 個別hook組合成系統。品質迴圈透過共用狀態檔案（jiro.state.json）連接了前置工具hook（在問題發生前捕捉）和後置工具hook（在結果產生後驗證）。審議系統使用遞迴防護、產生預算和共識協定來協調多個代理而不會產生無限迴圈。Ralph（自主開發迴圈）在單一編排管線中連接了PRD檔案、Claude產生、測試驗證和程式碼審查。

第四階段：自我意識（第9週以後）。 系統變得足夠龐大，需要工具來理解自身。跨hook系統的語意搜尋（/find skill）讓代理能按用途而非檔案名稱來發現hook。效能監控（/perf skill）追蹤系統自身的開銷是否正在拖慢機器。上下文壓力監控器則在編排層注入的上下文消耗過多模型上下文窗口時發出警告。

從單一用途hook到自我監控基礎設施的演進，映射了Chris Lattner在審查Claude C Compiler專案時識別出的模式：「好的軟體取決於判斷力、溝通和清晰的抽象。AI放大了這一點。」³hook系統的架構揭示了同樣的真理。有價值的hook不是那些自動化任務的hook，有價值的hook是那些編碼了何時以及如何自動化任務之判斷的hook。

判斷Hook與自動化Hook

Lattner對Claude C Compiler的審查區分了AI善於自動化的部分（實作）和本質上仍屬人類的部分（判斷力與抽象能力）。³這個區分直接對應到hook系統。

判斷hook決定某事是否應該發生。它們編碼的是策略，而非程序。

自動化hook執行預定動作。它們編碼的是程序，而非策略。

判斷hook更難撰寫、更難測試，也更有價值。quality-gate.sh需要七種命名的失敗模式、六項證據標準和一個模糊語言偵測器。inject-context.sh只需要五行bash。但兩者都是必要的。自動化hook提供判斷hook評估所需的資料。sysmon-snapshot.sh（自動化）將資料饋送給效能監控器，由其決定是否建議限制代理數量（判斷）。

比例很重要。在健康的編排層中，判斷hook應該多於自動化hook。如果大多數hook只是注入資料或記錄指標，系統自動化做得好但治理做得差。目前系統的驗證計數：35個判斷hook、44個自動化hook，大約4比5。自動化仍然領先。這個比例起初大約是1比6（幾乎全是注入和記錄hook），在兩個月內隨著治理約束的加入而向判斷傾斜，這些約束是在遭遇純自動化無法防止的失敗後才添加的。比例尚未達到均衡，這本身就是一個有用的訊號：這個系統的治理仍然少於它的自動化。

規劃與執行的分離

Boris Tane的「How I use Claude Code」文章在Hacker News上獲得936點，文中描述了一種工作流程模式：將規劃與執行分離。⁴用一個Claude工作階段進行規劃（研究、擬大綱、設計），然後用一個全新的工作階段執行，該工作階段接收計畫作為結構化輸入。這個模式引起共鳴，因為它解決了一個真實問題：規劃和執行競爭上下文窗口空間。

hook系統透過不同的路徑達到了同樣的分離。審議系統產生專門代理來研究和辯論方法。輸出是結構化的PRD（產品需求文件），包含故事、驗收標準和驗證類型。Ralph迴圈讀取PRD並產生全新的Claude實例來實作每個故事。規劃代理從不實作，實作代理從不規劃。

這種分離並非設計目標。它源自兩個獨立的約束：

1. 上下文窗口壓力。 規劃需要讀取許多檔案並探索選項。實作需要對當前任務的聚焦上下文。將兩者放在同一個上下文窗口意味著兩者都得不到足夠空間。分開的工作階段讓每個階段都有完整的上下文。

2. 品質驗證獨立性。 如果同一個代理既規劃又實作，它就無法客觀地依據計畫驗證自己的實作。一個只有計畫和程式碼的全新代理提供了獨立驗證。Ralph迴圈強制執行這一點：實作代理執行測試，但三個獨立的審查代理（正確性、安全性、慣例）驗證結果。

Tane的手動工作流程與自動化hook系統之間的趨同暗示，規劃與執行的分離是代理系統的自然屬性，而不僅是實踐者的偏好。任何管理上下文窗口並驗證輸出的系統最終都會分離規劃與執行，因為替代方案（在一個上下文中同時進行）會在兩個階段都產生較差的結果。

Hook系統的失敗之處

這個架構有三個顯著弱點，是專門建構的編排框架能夠解決的。

沒有宣告式工作流程定義。 每個工作流程都以命令式方式編碼在bash腳本中。Ralph迴圈是1,320行bash，編碼了一個特定序列：讀取PRD、選擇故事、收集上下文、產生Claude、執行測試、執行審查、處理失敗、更新狀態。修改工作流程意味著編輯bash。宣告式系統會將工作流程定義為資料（YAML、JSON），由直譯器執行。宣告式工作流程更容易修改、組合和視覺化。命令式腳本最初更容易撰寫，但隨著成長更難維護。

Hook排序是脆弱的。 prompt調度器以寫死的序列執行hook。將memory-capsule-inject.sh移到inject-context.sh之前會破壞膠囊注入，因為它依賴於inject-context.sh所解析的工作階段ID。這些相依性是隱式的（編碼在調度器的順序中）而非顯式的（宣告為hook之間的相依性）。專門建構的系統會將hook相依性表達為DAG，並以拓撲排序決定執行順序。

沒有工作流程視覺化。 有84個hook，要理解任何使用者操作的完整執行路徑，就必須閱讀調度器程式碼並手動追蹤hook鏈。沒有工具可以顯示「當使用者輸入訊息時，這9個hook按此順序觸發，而hook 3呼叫程式庫函式X，該函式寫入狀態檔案Y」。系統可透過日誌觀察，但無法透過結構觀察。專門建構的編排框架會提供hook相依性、資料流和執行路徑的視覺化圖表。

這些弱點有一個共同原因：系統是從解決個別問題有機成長的，而非被設計為一個連貫的編排層。有機成長產生的系統可以運作（所有84個hook在生產環境中都正確運作），但難以作為整體來推理。這個取捨是真實的：預先設計編排層會產生更好的結構，卻會產生更差的能力，因為許多能力（記憶膠囊、輸出白名單、產生預算）是在遭遇無法事先預測的失敗之後才發明出來的。

Harness走向主流

在Karpathy為這一層命名三週後，這個概念有了第二個名字，以及一個持續成長的社群。

Geoffrey Huntley提出了一個正式定義：「Agent Harness，環繞語言模型的編排層，將它從一個工具轉變為一位隊友。」⁵這個說法很精確。Harness不是模型，也不是模型呼叫的工具，而是決定要呼叫哪些工具、何時呼叫，以及如何評估呼叫是否成功的那個系統。每個生產級代理系統都會建構這一層。多數是隱式建構的，藏在把編排邏輯與商業邏輯混在一起的應用程式碼裡。為它命名，架構才變得可見。

社群訊號證實這個模式正在擴散。Pieter Levels表示他已永久改為在伺服器上執行Claude Code，把它當成基礎設施而非本機工具。⁶Anthropic推出了Remote Control，讓使用者從終端機啟動任務，再到Claude.ai接手。⁷Ben Cherny宣布/simplify與/batch成為第一方skill。⁸這些每一項都是harness功能：持續執行、遠端編排，以及內建的能力模組。CLI正在長成harness。

與此同時，實踐者也在打造自己的harness元件。有位開發者發布了22個自訂的Obsidian加Claude Code指令，作為個人作業系統。⁹另一位建立了「Visual Explainer」代理skill，並搭配互補的斜線指令。¹⁰這些模式如出一轍：調度器、skill、共用狀態、事件驅動的hook。沒有人在打造這些系統之前先讀過框架指南。他們解決一個問題，然後另一個，接著解決問題之間互相影響的問題。

最近兩個專案顯示社群打造的harness元件已經多麼成熟。nah是一個上下文感知的權限守衛，註冊為PreToolUse hook。¹⁴它將動作分成20種不同類型（檔案寫入、網路請求、行程產生等），並套用各類型的政策。這個工具能偵測管線分解攻擊，也就是代理串接看似無害的指令來達成被阻擋的操作。它的架構與本文的filter-sensitive.sh和recursion-guard.sh如出一轍，是另一位實踐者在解決相同治理問題時獨立得出的結果。

Rudel則透過把Claude Code的工作階段資料匯入ClickHouse來提供工作階段分析。¹⁵對1,573個工作階段的分析顯示，只有4%的使用者會呼叫skill，而26%的工作階段在60秒內就被放棄。這些數字印證了harness架構所隱含的事實：多數使用者只在表層與代理CLI互動。本文描述的編排層位於使用分布的深水區，而絕大多數人從未離開淺灘。工具能做到的事，與多數使用者要求它做的事之間的落差，正是harness基礎設施所填補的空間。

Autoresearch：作為研究迴圈的Harness

Karpathy自己的autoresearch專案在另一個領域展示了harness模式。¹¹該系統讓語言模型指向一個訓練腳本（train.py），執行五分鐘的實驗，依固定指標（驗證集的每位元組位元數）評估結果，然後保留改進或捨棄退步。在兩天內，系統執行了大約700次實驗，找到約20項真正的改進，將GPT-2的訓練時間縮短了11%。

其架構與上述hook系統完全相同。固定的評估harness（prepare.py）等同於判斷hook：它決定實驗是否成功。訓練腳本（train.py）等同於自動化hook：它執行代理的修改。git分支管理（改進就保留，退步就重置）等同於Ralph迴圈的狀態管理。results.tsv日誌等同於工作階段遙測。

這個模式可以移植，因為harness解決的問題與領域無關。無論代理是在寫程式碼、最佳化訓練迴圈，還是管理內容管線，它都需要：一套依標準評估結果的方法、一套保留或捨棄變更的方法、一套跨迭代維持狀態的方法，以及一套無需人類介入即可自主執行的方法。這四項需求無論代理實際在做什麼，都會產生相同的架構。

Shopify執行長Tobi Lütke在內部改用了autoresearch。他那個由代理最佳化的較小模型表現優於人工設定的較大模型，驗證了自主harness驅動的迭代能找出人類想不到要嘗試的組態。¹²

Harness中的安全缺口

Harness解決了編排問題，但它並不會自動解決安全問題。

一項針對迭代式LLM驅動程式碼精修的研究發現，在代理修改十輪之後，有43.7%的迭代鏈所含的漏洞比它們起始的基準程式碼還多。¹³根本原因是規格漂移：當代理為了功能正確性而最佳化時，它逐步移除了防禦性邏輯，並弱化了例外處理。更糟的是，在迭代迴圈中加入靜態分析安全工具（SAST關卡）反而讓潛在劣化從12.5%上升到20.8%。掃描器製造了虛假的安全感，使代理變得更不謹慎，而非更謹慎。

這項劣化發現與harness設計直接相關。本文描述的判斷hook（quality-gate.sh、filter-sensitive.sh、recursion-guard.sh）針對的正是純自動化會使之劣化的品質與安全面向。解決劣化問題的SCAFFOLD-CEGIS框架採用四層閘控驗證，達到2.1%的潛在劣化率與100%的安全單調性。¹³這個架構與hook系統彼此平行：分離的評估層各自檢查不同屬性，並在階段之間設有明確的關卡。

另一項工作從生產端佐證了這個威脅模型。Perplexity針對AI代理安全提交給NIST的回應，描繪了大規模運作的代理系統攻擊面。¹⁶主要向量包括：透過資料通道（網頁、電子郵件、工具輸出）的間接提示注入、代理特有的CIA三要素違規（透過工具呼叫的資料外洩、透過上下文汙染的動作操縱、透過遞迴產生的資源耗盡），以及來自代理周邊系統的真實CVE。他們建議的防禦架構（輸入層過濾、模型層對齊，以及透過沙箱與允許清單的確定性強制）與本文所述hook系統中有機浮現的三層模式相互呼應。自動化hook過濾輸入，模型行使判斷，治理hook則強制模型無法覆寫的確定性約束。

給實踐者的教訓是：如果您的harness只會自動化與編排而不治理，迭代式的代理執行將帶來標準工具無法偵測的安全退步。判斷hook不是額外負擔，它們正是系統不會劣化的原因。

更新，9月3日：真實世界中的失效模式

本文在「Harness中的安全缺口」一節描述的缺口，如今有了一位記錄在案的受害者。2026年7月19日，Claude Code v2.1.204正在清理Udaya Kumar P L電腦上的快取，此人是Mythic Society的Bengaluru Inscriptions 3D Digital Conservation Project榮譽主任；根據他的說法，當時「AI生成指令中的一個引號錯誤，把指令變成了『刪除所有東西』」。對harness設計而言真正重要的是接下來發生的事：「當它理解狀況並試圖終止該行程時，它的安全系統阻擋了終止動作。兩次[…]安全層允許了這場破壞。」四分鐘後他關掉了機器。損失包括：四或五個程式，以及十年間收集的碑文、英雄石、寺廟與錢幣的原始照片，約佔專案記錄的15%，其中包含一塊刻有Hebbal早期名稱形式的石頭（西元750年）。NAS上的副本倖存，硬碟則沒有。該學會正花費15 lakh盧比添購第二台NAS與異地磁帶備份，志工們則要重新掃描約120個地點。一個多月過去，他仍未收到Anthropic任何人的回音。¹⁷

這段記述中有三件事與上文的論點吻合。造成破壞的那一步並非模型的決定，而是生成指令中的shell引號失誤，正是PreToolUse判斷hook存在的用意所在。該報導未提及使用了哪種權限模式，因此沒有任何第一方紀錄顯示那道指令曾被審查過；即使在auto模式下，分類器預設也只會審查符合任意程式碼執行樣式的shell指令。他也提到代理繞過了沙箱，但報導未說明是哪一種沙箱。Anthropic其實已經為鄰近的情況推出過防護：7月8日發布的v2.1.205，讓auto模式在對無法從上下文解析的變數執行rm -rf之前先行詢問。而那台機器跑的是v2.1.204。¹⁹接著安全層在錯誤的方向上盡了職責：它把代理自己的補救動作當成了危險動作。至於倖存下來的東西，之所以倖存，靠的是唯一完全位於harness之外的控制措施，也就是備份；其餘的只能靠人工重新掃描。這類事件現在至少有了一個非官方的登記處，他指出官方的登記處並不存在。I Have Been Clawed是一個附有出處連結的代理與聊天機器人事故檔案庫，每一則都附上一項教訓，撰稿當時共有58筆條目，其中七筆屬於Claude Code；它在自己的首頁上也誠實聲明，條目是自我選擇且以病毒式傳播加權的，因此各工具的計數衡量的是回報文化，而非安全性。在這一則之前，它已經收錄了三筆形狀相同的Claude Code條目：一道遞迴指令從WSL家目錄刪除了使用者擁有的檔案（2025年10月21日）、一個名為波浪號的目錄使家目錄暴露於刪除風險（2025年11月28日），以及一道以家目錄路徑結尾的清理指令抹除了一台Mac（2025年12月7日）。在真實世界裡，這是一種模式，而不是一則故事。¹⁸

實踐者應該帶走什麼

如果您正在代理CLI之上建構編排層，無論是從Claude Code指南出發，還是從零開始，此系統的三個模式都可以直接移植。

從調度器開始，而非個別hook。 最大的架構改進，是把七個獨立的UserPromptSubmit hook替換成一個循序執行它們的調度器。如果您預期在任何事件類型上會有超過三個hook，請先建構調度器。花30分鐘撰寫調度器，可以省下日後數小時的hook互動除錯。最小模式如下：

#!/bin/bash
# dispatcher.sh — sequential hook execution with shared stdin
HANDLERS=("inject-context.sh" "track-usage.sh" "quality-gate.sh")
HOOK_DIR="$(dirname "$0")/handlers"
INPUT=$(cat)  # Cache stdin once (each handler gets the same input)

for handler in "${HANDLERS[@]}"; do
    [ -x "$HOOK_DIR/$handler" ] && echo "$INPUT" | "$HOOK_DIR/$handler"
done

將這個單一調度器註冊為您的hook進入點。隨著建構，再把處理器加進陣列中。每個處理器讀取相同的快取stdin（hook事件酬載），並獨立寫入stdout。

儘早分離判斷與自動化。 撰寫新hook時，請先問：「這個hook是決定某事是否應該發生，還是執行預定動作？」判斷hook需要更多測試、更多邊界情況處理和更多迭代。自動化hook需要的是可靠性和效能。把兩者同等對待，會導致測試不足的判斷hook和過度工程的自動化hook。

讓規劃與執行的分離自然浮現。 不要在第一天就強制分離。先建構最簡單可行的東西。當您注意到代理的上下文窗口對規劃和實作來說都太滿時，再把它們分開。當您注意到代理無法客觀驗證自己的工作時，再加上獨立的審查代理。當約束條件要求時，分離會顯得理所當然。

Harness正在走向主流，因為這個模式無可避免。無論您把這一層稱作Claws、Agent Harness，還是只叫「我的hook資料夾」，任何協調代理達成目標的系統，都會收斂到相同的架構：用於排序的調度器、用於治理的判斷hook、用於執行的自動化hook，以及用於延續性的狀態檔案。Claude Code原始碼外流證實了Anthropic自家的內部架構也遵循這些相同的模式，協調者模式完全以系統提示指令實作，而非程式碼層級的編排。相較於專門建構的編排框架，基於hook的做法有一個優勢：零承諾。每個hook都是獨立的。您可以採用一個hook、十個hook，或八十四個hook。您可以刪除任何hook而不破壞其他hook（前提是維護好調度器）。沒有需要學習的框架，沒有需要管理的相依性，也沒有需要營運的執行環境。編排層就只是一堆檔案。

常見問題

什麼是agent harness或「Claws」層？

Claws層（由Andrej Karpathy於2026年2月命名）是建構在代理CLI之上的編排系統，它把代理CLI從一個工具轉變為一位隊友。¹它執行五種功能：編排（協調多個代理）、排程（決定任務何時執行）、上下文管理（跨輪次維持相關資訊）、工具路由（將工具呼叫導向適當的處理器），以及品質執行（驗證輸出符合標準）。Geoffrey Huntley將這個定義形式化為「環繞語言模型的編排層」。⁵

PreToolUse hook在Claude Code中如何運作？

PreToolUse hook會在每次工具呼叫（Bash指令、檔案寫入、檔案編輯、子代理產生）之前觸發，並從stdin接收JSON格式的工具呼叫酬載。Hook腳本評估酬載後回傳一個決定：允許、拒絕或修改。模型無法跳過、覆寫或與hook協商，因為它們是在基礎設施層級執行，而非提示層級。²調度器模式會在每個事件上循序執行多個hook，並透過快取的stdin管道讓每個處理器都收到相同的輸入。

判斷hook與自動化hook有什麼差別？

判斷hook決定某事是否應該發生（策略），而自動化hook執行預定動作（程序）。判斷hook包括品質關卡、憑證過濾器、遞迴防護和成本關卡。自動化hook包括上下文注入、使用追蹤、系統監控和心跳訊號。³比例很重要：以自動化hook為主的系統自動化做得好，但治理做得差。目前的系統有35個判斷hook對44個自動化hook，並隨著各種失敗揭露純自動化無法防止的事情，而逐步向治理傾斜。

為什麼規劃與執行的分離會在代理系統中自然浮現？

有兩個獨立的約束促成這種分離。第一，規劃需要讀取許多檔案並探索選項，而實作需要對當前任務的聚焦上下文，把兩者放進同一個上下文窗口，代表兩者都得不到足夠空間。第二，如果同一個代理既規劃又實作，它就無法客觀地依據計畫驗證自己的工作。⁴任何管理上下文窗口並驗證輸出的系統，最終都會分離規劃與執行，因為替代方案會在兩個階段都產生較差的結果。

我該如何開始建構自己的hook系統？

從調度器開始，而非個別hook。如果您預期在任何事件類型上會有超過三個hook，請建構一個從陣列循序執行處理器的單一調度器。花30分鐘撰寫調度器，可以省下日後數小時的hook互動除錯。儘早分離判斷與自動化，方法是自問「這個hook是決定某事是否應該發生，還是執行預定動作？」不妨從Claude Code hook教學開始，並在真實失敗提出需求時才添加hook，而不是一開始就設計出完整系統。

參考來源