設計原則與產品化

架構背後的判斷

前七章拆了引擎、工具、Agent、安全、生態、上下文，這章往後退一步，看這些設計決策背後的共同邏輯。

程式碼庫不會說話，但設計原則藏在每一個「為什麼這樣而不是那樣」的選擇裡。讀完 4756 個檔案，能讀出七條。

產品化的基礎設施

先看幾個常被忽略但撐起整個系統的部分。

生命週期管理是最不起眼卻最關鍵的一塊：初始化順序、資源清理、SIGINT/SIGTERM 處理、異常退出時的狀態保存。做好了使用者感知不到，做差了才會看到「Ctrl+C 卡死」或退出後工具結果消失。

執行引擎和 UI 之間靠 Bridge 系統解耦——CLI 和 Web 端共用同一套引擎，Bridge 以標準化訊息格式傳遞事件，執行層完全不知道 UI 是什麼形態。State 管理在這之上分層存儲對話歷史和工具狀態：記憶體層放熱資料，磁碟層持久化，同步時機明確（工具執行完成、輪次結束、正常退出）。

UI 本身用 React + Ink 寫，終端介面按普通 React 組件開發，測試邏輯也和測試 React 組件一樣直接。Telemetry 有嚴格的本地過濾，不上傳對話內容或工具輸入，只送聚合的使用模式和錯誤統計。

7 條設計原則

最根本的一條：不信任模型自覺性。模型說「我不會做危險的事」不算數，系統假設它會做任何被允許的事。所以「允許什麼」必須在架構層面硬限制，不能靠 prompt 約束——buildTool() 的 fail-closed 預設值、14 步 Pipeline、Explore Agent 的硬性唯讀，都在執行這條原則。從這條出發，自然推導出第二條：把角色拆開。寫程式碼的 Agent 和驗證的 Agent 物理隔離，因為同一個上下文裡的「自我審查」根本不算審查。

工具層同理——工具呼叫要有治理。治理屬性（確認規則、輸出上限）和業務邏輯必須定義在同一個介面裡，分開管理等於治理隨時可能失效。上下文那層的對應判斷是上下文是預算不是倉庫：密度比總量重要，四道壓縮和按需注入都在解決這一點。安全層的原則更直接——三層防護互不繞過，Speculative Classifier、Hook Policy、Permission Decision 各自獨立，任何一層掛掉其他兩層還在。

生態那條有點反直覺：擴展機制的價值不在於「能接多少工具」，而在於模型能感知自己現在有什麼能力。工具清單和行為說明跟實際可用狀態脫節，模型就會在錯誤前提下做決策，擴展反而成了漏洞。

最後一條最容易被演示文化掩蓋：產品化在於處理第二天。API 413、工具超時、子 Agent 回傳垃圾、Ctrl+C 卡死——不是邊緣案例，是真實使用者每天都踩的地方。Reactive Compact、3 次失敗協議、強制 1500 token 摘要上限，全在解決第二天，不是第一天。

讀這個程式碼庫的收穫

Claude Code 的程式碼庫不是研究論文，是一個在生產環境跑著的工程系統。它的設計決策有取捨，有歷史包袱，也有明顯在解決真實痛點的地方。

最值得帶走的一點：Agent 系統的可靠性不來自模型有多聰明，而來自圍繞模型建的那套治理結構有多嚴實。模型是引擎，架構是底盤。底盤不穩，引擎再好也跑不遠。

---

參考來源： 本文內容參考 Xiao Tan（@tvytlx）的《Claude Code 源碼架構深度解析 V2.0》，基於原報告的分析框架和研究成果整理。