Quartz 4

Claude Code Analysis — Claude Code 分析：代理架構反向工程

24 min read

Abstract

本論文由 VILA Lab 透過 reverse-engineering Claude Code 的 TypeScript 源代碼進行全面架構分析，發現核心是一個簡單的 while-true 迴圈但 98.4% 代碼為操作基礎設施。論文提出五大人類價值觀與十三條設計原則，並揭示 Claude Code 與 OpenClaw 在安全架構（分層策略 vs. 周邊級別存取控制）上的根本差異。

Claude Code Analysis

Claude Code Analysis 是由 VILA Lab（MBZUAI + UCL）發表的論文（arXiv:2604.14228），透過 reverse-engineering Claude Code 的 TypeScript 源代碼，對其架構進行全面分析，並與開源系統 openhands 和 skill-claw 等進行架構比較。這篇論文是理解當代 AI Agent 系統設計選擇的重要參考文獻，填補了 Anthropic 官方只發布用戶文檔而非詳細架構描述的空白。^[raw/papers/claude-code-analysis.md]

Overview

Claude Code 是 Anthropic 發布的 agentic 程式碼工具，能夠代表用戶運行 shell 命令、編輯檔案和呼叫外部服務。與過往的 autocomplete 工具（如 GitHub Copilot）或 IDE 整合助手（如 Cursor）不同，Claude Code 代表了一個根本性的轉變：從建議轉向自主行動。這個轉變引入了新的架構需求——安全、上下文管理、擴展性和 delegation——這些在純完成的工具中沒有對應項目。這種從建議到自主行動的範式轉變，是理解 Claude Code 架構設計選擇的關鍵背景。雖然 Anthropic 發布了用戶文檔，但並未公開詳細的架構描述，因此本論文填補了這一重要空白，透過源碼分析揭示了系統內部的設計邏輯。^[raw/papers/claude-code-analysis.md]

論文的核心發現是：Claude Code 的核心是一個簡單的 while-true 迴圈，呼叫模型、運行工具、重複執行。絕大多數代碼其實生活在這個迴圈周圍的系統中：包含七種模式的許可系統與 ML 分類器、上下文管理的五層緊縮管道、四種擴展機制（MCP、plugins、skills、hooks）、子代理 delegation 和 orchestration 機制，以及 append-oriented 的 session 儲存。社區分析估計只有約 1.6% 的程式碼構成 AI 決策邏輯，其餘 98.4% 為操作基礎設施。這意味著系統的核心價值不在於模型本身的決策邏輯，而在於圍繞模型的龐大操作框架，這與 Devin 等使用明確 planning 和 task-tracking 結構的系統形成鮮明對比。^[raw/papers/claude-code-analysis.md]

Anthropic 對 132 名工程師和研究人員的內部調查顯示，約 27% 的 Claude Code 輔助任務是”如果沒有這個工具就不會嘗試的工作”，這表明該架構能夠實現質化上新穎的工作流程，而不僅僅是加速現有流程。這個數據支持了能力放大（Capability Amplification）作為核心設計價值的正當性。^[raw/papers/claude-code-analysis.md]

Core Contributions

論文做出了以下核心貢獻：^[raw/papers/claude-code-analysis.md]

  1. 五大人類價值觀與十三條設計原則：識別出驅動 Claude Code 架構的五個核心價值——人類決策權威（Human Decision Authority）、安全與隱私（Safety and Security）、可靠執行（Reliable Execution）、能力放大（Capability Amplification）和情境適應性（Contextual Adaptability）——並將它們追溯到十三條具體設計原則。這些原則包括：否決優先與人工升級（deny-first with human escalation）、漸進信任譜系（graduated trust spectrum）、深度防禦與分層機制（defense in depth with layered mechanisms）、外部化可編程策略（externalized programmable policy）、上下文作為稀缺資源（context as scarce resource）、Append-only 持久化狀態（append-only durable state）、最小化鷹架最大化操作環境（minimal scaffolding, maximal operational harness）、價值觀優先於規則（values over rules）、可組合多機制擴展性（composable multi-mechanism extensibility）、可逆性權重風險評估（reversibility-weighted risk assessment）、透明基於文件的配置與記憶（transparent file-based configuration and memory）、隔離子代理邊界（isolated subagent boundaries）、以及優雅恢復與彈性（graceful recovery and resilience）

  2. 七元件高層結構與五層子系統架構：將系統分解為七個功能元件——用戶（提交提示、批准許可、審查輸出）、介面（互動式 CLI、headless CLI、Agent SDK、IDE/Desktop/Browser）、Agent 迴圈（迭代的模型呼叫、工具分發、結果收集）、許可系統（否決優先規則評估與 ML 分類器）、工具（最多 54 個內置工具）、狀態與持久化（mostly append-only JSONL session transcripts）、執行環境（Shell 執行與可選沙箱）——並以五層子系統架構進一步細分為表面層（entry points 和 rendering）、核心層（agent loop、compaction pipeline）、安全/行動層（permission、hooks、extensibility、tools、sandbox、subagents）、狀態層（context assembly、runtime state、session persistence、CLAUDE.md + memory、sidechain transcripts）和後端層（execution backends、external resources）

  3. 與 OpenClaw 的架構對比：比較了 Claude Code 與 OpenClaw（開源多通道個人助理 gateway）在六個設計維度上的差異。六個維度分別是：系統範圍與部署模型（ephemeral CLI process vs. persistent WS gateway daemon）、信任模型與安全架構（per-action rule evaluation vs. perimeter-level access control）、Agent 運行時與工具編排（iterative async generator vs. embedded Pi-agent core）、擴展架構（MCP/plugins/skills/hooks 四機制 vs. manifest-first plugin system with 12 capability types）、記憶與上下文管理（CLAUDE.md 4-level hierarchy vs. workspace bootstrap files）、以及多代理架構與路由（task-delegating subagents vs. multi-agent routing with isolated agents）。這些對比揭示了相同設計問題在不同部署上下文下如何產生不同的架構答案

  4. 六個未來開放設計方向：基於最近的經驗性、架構性和政策性文獻，確定了未來 Agent 系統的六個開放設計方向：靜默失敗與可觀測性-評估差距、跨 session 持久化（記憶與縱向同事關係）、Harness 邊界演化（Agent 行動的地點、時間、對象、與誰協調）、Horizon Scaling（從 session 到科學程式）、規模化治理與監督、以及長期人類能力的評估鏡頭

Architecture / Approach

Agentic Query Loop

Claude Code 的核心是一個 queryLoop() async generator，實現了 ReAct 模式（Yao et al., 2022）：模型生成推理和工具調用，harness 執行操作，結果反饋到下一次迭代。這個迴圈是系統的中心，所有介面（互動式 CLI、headless CLI、Agent SDK、IDE 整合）都餵入同一個迴圈。這種統一的設計不同於其他系統使用模式特定引擎的做法，例如 IDE 整合可能遵循與 CLI 工具不同的代碼路徑。^[raw/papers/claude-code-analysis.md]

查詢管道遵循九步序列：

  1. 設定解析：queryLoop() 函數解構不可變參數，包括 system prompt、user context、permission callback 和 model configuration
  2. 可變狀態初始化：單個 State 對象存儲所有跨迭代的可變狀態，包括 messages、tool context、compaction tracking 和 recovery counters
  3. 上下文組裝：getMessagesAfterCompactBoundary() 從最後一個 compact boundary 檢索消息
  4. 預模型上下文整形器：五個 shapers 按順序執行
  5. 模型呼叫：for await 迴圈流式傳輸模型的響應
  6. 工具調用分發：如果響應包含 tool_use 塊，則流向工具編排層
  7. 許可閘門：每個工具請求都通過許可系統
  8. 工具執行與結果收集：工具結果作為 tool_result 消息添加到對話中
  9. 停止條件：如果響應不包含 tool_use 塊（純文本），則 turn 完成

Tool Dispatch 與 Streaming Execution

當模型響應包含 tool_use 塊時，系統在兩個執行路徑之間選擇。主要路徑使用 StreamingToolExecutor，開始執行流式傳入的工具，減少多工具響應的延遲。備用路徑使用 runTools()。StreamingToolExecutor 使用兩個協調機制：兄弟中止控制器（當任何 Bash 工具錯誤時立即終止其他進行中的子進程）和 progress-available 信號（在有新輸出時喚醒消費者）。^[raw/papers/claude-code-analysis.md]

五層緊縮管道（Compaction Pipeline）

上下文窗口（200K 或 1M tokens）是主要的綁定資源約束。五種不同的上下文 reduction 策略在每次模型呼叫前執行：^[raw/papers/claude-code-analysis.md]

  1. Budget Reduction（始終活動）：對工具結果實施每條消息大小限制，將超大型輸出替換為內容引用
  2. Snip（HISTORY_SNIP）：輕量級的歷史修剪，移除較舊的歷史段
  3. Microcompact（CACHED_MICROCOMPACT）：細粒度壓縮，具有快取感知路徑
  4. Context Collapse（CONTEXT_COLLAPSE）：對話歷史的讀時投影，不會實際修改存儲的歷史
  5. Auto-compact（用戶可配置）：由模型生成的完整摘要，作為最後手段

這種 graduated 設計體現了”lazy degradation”原則：先應用最低侵入性的壓縮，僅在更便宜的策略不足時才升級。與許多 agent 框架使用的單次截斷或單次摘要方法形成對比。

許可系統與安全架構

Claude Code 採用 deny-first with human escalation 的默認安全姿勢。這個設計受到一個重要數據推動：Anthropic 的內部分析發現用戶批准約 93% 的許可提示，這意味著批准疲勞使互動確認在行為上不可靠。因為用戶習慣性地批准而不仔細審查，系統必須獨立於人類警覺性來維持安全。這促使架構採用否決優先評估、 blanket-deny 預過濾和沙箱化作為獨立層。^[raw/papers/claude-code-analysis.md]

七種獨立的安全層相結合，任何單一層都可以阻止操作：

  1. 工具預過濾（tools.ts）：在工具池組裝時從模型視圖中移除 blanket-denied 工具，防止模型嘗試調用它們
  2. 否決優先規則評估（permissions.ts）：否決規則始終優先於允許規則，即使允許規則更具體
  3. 許可模式約束（types/permissions.ts）：活動模式決定匹配無明確規則的請求的基線處理
  4. Auto-mode ML 分類器（yoloClassifier.ts）：當 TRANSCRIPT_CLASSIFIER 啟用時，評估工具安全性
  5. Shell 沙箱（shouldUseSandbox.ts）：批準的 shell 命令可能在限制文件系統和網絡訪問的沙箱中執行
  6. Resume 時不恢復許可（conversationRecovery.ts）：Session-scoped 許可不在恢復或 fork 上恢復
  7. 基於 Hook 的攔截（types/hooks.ts）：PreToolUse hooks 可以修改許可決策

七種許可模式覆蓋從 plan（用戶批准所有計劃）到 bypassPermissions（最小提示）的連續體：plan → default → acceptEdits → auto → dontAsk → bypassPermissions，加上內部使用的 bubble 模式。這個漸進信任譜系反映了安全性與自主性之間的結構性緊張關係：隨著自主性增加，系統必須從互動批准轉變為自動化安全檢查。^[raw/papers/claude-code-analysis.md]

四種擴展機制

Claude Code 使用四種不同的擴展機制，按上下文成本分層，每種機制都有其獨特價值：^[raw/papers/claude-code-analysis.md]

機制上下文成本獨特能力
MCP Servers高（工具 schema）外部服務整合（多傳輸：stdio、SSE、HTTP、WebSocket、SDK）
Plugins中（變化）多組件封裝 + 分發，可同時擴展多個組件類型
Skills低（僅描述）領域特定指令 + meta-tool 調用，影響 agent 思維方式
Hooks零（默認）生命週期攔截 + 事件驅動自動化

這種 graduated 成本排序意味著便宜的擴展可以廣泛擴展而不耗盡上下文窗口，而昂貴的擴展則保留給真正需要新工具表面的情況。這種設計選擇是基於這樣的洞察：不同類型的擴展性對上下文窗口的消耗差異很大，因此需要不同的機制來平衡表達能力與資源約束。^[raw/papers/claude-code-analysis.md]

子代理 Delegation

Claude Code 的子代理架構實現了隔離子代理邊界原則，與 openhands 這類使用 Docker 隔離的系統形成對比。Agent Tool（AgentTool.tsx）支持六種內置子代理類型：Explore（主要讀/搜索導向）、Plan（創建結構化計劃）、General-purpose（廣泛能力）、Claude Code Guide（入職和文檔協助）、Verification（運行驗證檢查）和 Statusline-setup（終端狀態行配置）。^[raw/papers/claude-code-analysis.md]

關鍵設計選擇包括：

  • Worktree 隔離：創建臨時 git worktree，賦予子代理自己的倉庫副本進行修改，而不影響父代理的工作樹
  • Sidechain Transcript：每個子代理將對話寫入單獨的 .jsonl 文件，只有最終回應文本返回父代理 |- Summary-only Return：避免子代理歷史膨脹父代理的上下文窗口。這種設計體現了”上下文作為稀缺資源”的原則^[raw/papers/claude-code-analysis.md]

Session 持久化與恢復

Claude Code 的持久化設計採用 append-only 原則。Session transcripts 存儲為 mostly-append-only JSONL 文件，實現了三個持久化通道：session transcripts（項目特定路徑）、global prompt history（history.jsonl）和 subagent sidechains（單獨的 .jsonl + .meta.json 文件）。Append-only 的設計選擇是為了支持審計追蹤（auditability）和簡單性，而不是查詢能力（query power）。每個事件都是人類可讀的、版本可控的，無需專門工具即可重建。^[raw/papers/claude-code-analysis.md]

重要的安全設計：Resume 和 Fork 不會恢復 session-scoped 許可。這是一個有意義的安全保守設計選擇：session 被視為隔離的 trust domains。在恢復時重新授予許可而不是隱式持久化，接受用戶摩擦作為維持安全不變量的代價。這種設計意味着每次恢復對話時，用戶都需要重新建立信任決策，這增加了安全性但犧牲了便利性。^[raw/papers/claude-code-analysis.md]

Key Results

論文的關鍵發現包括：^[raw/papers/claude-code-analysis.md]

  • 架構哲學驗證：Claude Code 的 agentic loop 遵循 ReAct 模式，與 LangGraph 等明確的 graph-based 路由（將控制流定義為具有類型化邊的狀態機）形成對比。Reactive 設計犧牲了搜索完整性換取簡單性和延遲性：每輪提交一個操作序列而不進行 backtracking
  • 代碼比例失衡：只有約 1.6% 的程式碼構成 AI 決策邏輯，其餘 98.4% 為操作基礎設施。這一比例驗證了”最小化鷹架最大化操作環境”的設計原則：複雜性存在於為模型創造良好執行條件的基礎設施中，而非約束模型選擇的框架中
  • 許可疲勞現象：許可系統的七層設計受到用戶批准率數據推動：約 93% 的許可提示被批准。這意味著批准疲勞使互動確認在行為上不可靠。安全不能依賴人類警覺性，必須通過分類器和沙箱作為獨立層來維持
  • 信任軌跡演化：縱向數據顯示 auto-approve 比率從少於 50 sessions 的約 20% 增加到 750 sessions 的超過 40%，且 session 持續時間大幅增加。這表明人類-代理關係是”co-constructed by the model, the user, and the product”，系統為信任軌跡而非固定信任狀態而設計
  • 架構對比的深層意義：與 skill-claw 和 OpenClaw 的對比分析顯示：Claude Code 在每動作安全評估上投資，而 OpenClaw 在周邊級別的訪問控制上投資；Claude Code 將 agent loop 作為架構中心，而 OpenClaw 將 gateway control plane 作為中心；Claude Code 的擴展修改單個上下文窗口，而 OpenClaw 的 plugins 擴展共享 gateway 能力表面
  • 沙箱效能：沙箱化將許可提示頻率估計降低 84%，重新定義了問題：從人為決策問題轉變為減少人類必須做的決定數量
  • 經驗預測：基於有界上下文窗口的架構屬性，論文預測 agent 生成的代碼將表現出更高的模式重複和約定違反率。對 807 個 repos 的 Cursor 採用進行因果分析發現代碼複雜性增加 40.7%，初始速度峰值在第三個月消散到基線，這表明收益是自我取消的
  • 長期能力衰減疑慮：獨立研究發現 AI 輔助條件下的開發者在理解測驗中得分低 17%，AI 用戶表現出減弱的神經連接且在 AI 移除後仍持續。對 16 名經驗豐富開發者的 246 項任務的 RCT 發現 AI 工具使開發者慢 19%，尽管有 20% 的感知改善

Limitations

論文承認以下分析限制：^[raw/papers/claude-code-analysis.md]

  1. Memoization 效應：getSystemContext() 和 getUserContext() 都使用 lodash memoize，git status 和 CLAUDE.md 內容被緩存而不是每輪重新計算。對話期間的動態變化可能不會立即反映，儘管 compaction 可以清除緩存且 lazy-loaded 路徑範圍規則提供了部分對應機制

  2. Feature Flag 變異性：不同構建目標可能產生功能不同的應用。當 TRANSCRIPT_CLASSIFIER 為 false 時，整個 auto-mode 分類器被消除。Feature-gated 模塊使用動態 require() 而非靜態導入，因為 feature() 只能在 if/ternary 條件中工作

  3. 長期人類能力 Preserve 的缺乏：論文發現 Claude Code 的架構”有限機制明確支持長期人類改進、更深入的理解和持續的代碼庫一致性”，這是一個被忽視的設計維度。獨立研究發現 AI 輔助條件下的開發者在理解測驗中得分低 17%，AI 用戶表現出減弱的神經連接且在 AI 移除後仍持續。對 16 名經驗豐富開發者的 246 項任務的 RCT 發現 AI 工具使開發者慢 19%，尽管有 20% 的感知改善

  4. 防禦深度與性能緊張：研究文獻記錄了命令超過 50 個子命令時會退回到單個通用批准提示，因為每子命令解析導致 UI 凍結。這表明當安全層共享常見性能約束時，深度防禦可能會降級。這種緊張是結構性的：任何使用模型進行安全評估的 LLM Agent 系統都面臨這個問題

  5. Pre-trust 初始化排序問題：CVE-2025-59536 和 CVE-2026-21852 揭示了在項目初始化期間（hooks、MCP 服務器連接、設置文件解析）代碼在信任對話呈現給用戶之前執行，存在一個”pre-trust execution window”，Fall outside the deny-first evaluation pipeline。許可管道描述了安全檢查的空間排序，但不捕獲時間維度：特別是每個機制在 session 初始化期間何時激活

  6. 上下文效率與透明度的緊張：五層緊縮管道實現了有效的上下文管理，但壓縮在很大程度上對用戶是不可見的。當預算 reduction 將長工具輸出替換為引用、當 context collapse 替換消息為摘要、或當 snip 修剪較舊歷史時，用戶沒有簡單的方法來檢查丟失了什麼

  • openhands — 開源 AI Agent 系統，使用 Docker 隔離而非分層策略執行，專注於軟體工程任務。與 Claude Code 的對比揭示了安全架構的兩種哲學：容器隔離與分層策略執行
  • skill-claw — Claude 相關的開源實現或技能系統，與 Claude Code 的技能系統（SKILL.md）架構進行比較

See Also

Graph View

Backlinks