從 Claude Code 洩漏源碼學到的:如何打造生產級 AI Coding Agent
研究日期
2026-04-04
簡介
2026 年 3 月 31 日,Anthropic 因 .npmignore 配置失誤意外公開了 Claude Code 的完整源碼——512,000 行 TypeScript、1,906 個檔案、44 個隱藏 feature flag。這不是一個聊天介面包裝器,而是一個 $2.5B ARR 的生產級 agentic harness。
本文從工程師的角度,將洩漏源碼中驗證過的架構模式提煉成一套可複製的 agent 開發藍圖。不談理論,只談「Claude Code 做了什麼、為什麼這樣做、你可以怎麼複製」。
核心認知:Agent Harness ≠ Chat Wrapper
大多數人對 AI coding agent 的理解停留在「LLM + 工具呼叫 + REPL」。Claude Code 的源碼揭示了一個更複雜的現實:
flowchart TB
subgraph "Agent Harness 的真實複雜度"
A[Tool System<br>40+ 工具,每個獨立權限模型] --> B[Query Engine<br>46,000 行,LLM 編排核心]
B --> C[Context Management<br>4 層壓縮體系]
B --> D[Security Layer<br>23 項 bash 驗證 + 8 步權限級聯]
B --> E[Memory System<br>三層架構 + AI 驅動召回]
B --> F[Subagent System<br>Fork / Teammate / Worktree]
C --> G[Prompt Cache<br>14 個 break vectors + 全域快取]
E --> H[AutoDream<br>Forked subagent 記憶整合]
F --> I[KAIROS<br>自主 daemon(未發佈)]
A --> J[MCP Layer<br>所有工具統一介面]
D --> K[Hook System<br>25+ 事件攔截點]
B --> L[Telemetry<br>640 事件 + 40 指紋維度]
G --> M[Remote Kill Switches<br>GrowthBook feature flags]
end
Claude Code 中,LLM 推理只佔工程複雜度的 ~30%。 剩下的 70% 是 context 管理、安全防禦、工具編排、記憶持久化和效能優化。
核心迴圈的簡潔性
getaibook.com 的分析指出了一個被廣泛引用的發現——Claude Code 的核心就是一個 while(tool_call) 迴圈:
|
|
沒有意圖分類器、沒有任務路由器、沒有 RAG 管線、沒有 DAG 編排器、沒有 planner/executor 分離。模型自己決定呼叫哪些工具、以什麼順序、何時停止。
512,000 行程式碼的全部複雜性——記憶、安全、權限、context 管理、多 agent 協調——都是圍繞這個簡單迴圈建構的防禦性和增強性基礎設施。
對建構者的啟示:不要一開始就建 DAG 編排器或 planner/executor 分離。先讓簡單迴圈跑起來,再根據實際痛點逐步加基礎設施。Claude Code 的複雜性不是設計出來的,是被真實攻擊和使用場景逼出來的。
第一課:架構設計
模組化工具系統
每個能力都是獨立的、有權限控制的模組:
|
|
Claude Code 的實作:
- 40+ 工具,base tool definition 29,000 行
- 併發安全分類:
FileRead(始終安全)、BashTool(輸入依賴)、FileEdit(預設不安全) - 併發控制:
canExecuteTool()— 沒有執行中 → 可執行;自身安全 + 所有執行中也安全 → 可執行
MCP-first 工具架構
洩漏中最具架構意義的發現之一:Claude Code 不是「在 MCP 之上構建」——它的工具架構本身就是 MCP。
|
|
Computer Use(桌面自動化)不是特殊處理的模型層功能,而是一個使用與所有其他工具完全相同 MCP 介面的 Server——tools/list 發現、tools/call 呼叫、結構化結果返回。
可複製的設計模式:
flowchart LR
A[Agent Loop] --> B[MCP Client]
B --> C[tools/list]
B --> D[tools/call]
B --> E[resources/read]
B --> F[prompts/get]
C --> G[本地 MCP Server]
C --> H[遠端 MCP Server<br>stdio/SSE/HTTP/WS]
C --> I[託管 MCP Server<br>mcp-proxy 路由]
G --> J[Bash / Read / Edit / Grep]
H --> K[第三方整合<br>GitHub / Jira / Slack]
I --> L[claude.ai-managed<br>Slack / Gmail / Drive]
claude.ai-managed MCP 代理路徑:
- 6 個整合(Slack、Gmail、Google Drive、Google Calendar、PubMed、BigQuery)透過
mcp-proxy.anthropic.com路由 - 使用者透過 claude.ai OAuth 連接,而非本地 MCP 配置
- 與用戶本地 MCP 是平行共存的混合模式
Collapse Allowlist:489 個 MCP 工具有 collapse 分類(40 個標籤分組),決定哪些工具輸出可以在 context 壓縮時被清理。89 個 WebFetch 預審主機無需 URL 即可抓取。
對建構者的啟示:採用 MCP 作為統一工具介面,可以獲得生態系整合(任何 MCP Server 即插即用)、標準化發現機制、和一致的權限模型。不要為特殊功能建構專屬管線——把所有能力都變成 MCP Server。
Query Engine 作為「大腦」
Query Engine 不只是把 prompt 送給 API,它負責:
flowchart LR
A[使用者訊息] --> B[Context 載入<br>CLAUDE.md + 記憶 + git status]
B --> C[Prompt 組裝<br>全域快取 + session-specific]
C --> D[API 呼叫 + 串流]
D --> E[Tool 執行<br>流式重疊]
E --> F[Context 管理<br>微壓縮 / 自動壓縮]
F --> G{繼續?}
G -->|Yes| C
G -->|No| H[最終回應]
關鍵設計:
- 流式工具執行:工具在模型還在生成 token 時就開始執行,不等待完整回應
- Progressive context management:每輪都做微壓縮,不等到緊急才處理
- Prompt cache boundary:system prompt 在固定位置分割,全域部分跨組織共享快取
第二課:安全系統
深度防禦的權限系統
flowchart TB
A[使用者/Agent 想執行 Bash 命令] --> B{Tree-sitter AST 解析}
B -->|simple| C{沙盒放行?}
B -->|too-complex| D{LLM 分類器}
B -->|parse-unavailable| E[Legacy parser]
C -->|Yes| F[✅ 允許]
C -->|No| G{精確匹配}
D -->|高置信度| H[自動批准/拒絕]
D -->|低置信度| G
E --> G
G --> I{操作符拆分}
I --> J[遞迴檢查每個子命令]
J --> K{8 步子級聯}
K --> F
K --> L[❌ 拒絕]
K --> M[❓ 詢問使用者]
可複製的設計模式:
| 模式 | 做法 | 為什麼重要 |
|---|---|---|
| AST-first 驗證 | 用 tree-sitter 建構命令 AST,不依賴正則 | 正則有 parser differential 漏洞 |
| 多層級聯 | deny > ask > allow,每層獨立檢查 | 防止單層被繞過 |
| 不對稱環境變數處理 | deny 用激進剝離,allow 用保守白名單 | 防止 FOO=bar denied_cmd 繞過 |
| Shadow mode | 新舊 parser 並行運行,記錄分歧 | 安全迭代不中斷服務 |
| 預設 fail-closed | 不確定 → 拒絕;未知工具 → 不安全 | 安全優先 |
命令注入防禦清單
從 Claude Code 的 23 個驗證器提煉的必做清單:
- Zsh
=cmdexpansion:=curl展開為完整路徑,繞過 blocklist - Heredoc injection:
$(cat <<'EOF' ... EOF)在命令位置 - ANSI-C quoting:
$'\x63\x61\x74'=cat - IFS injection:
IFS=/ ls /etc改變 tokenization - Unicode zero-width spaces:不可見字元繞過字串比對
- Process substitution:
<(cmd)和>(cmd) - /proc environ:封鎖
/proc/self/environ(防 API key 外洩) - Carriage return:
\r在 shell-quote 和 bash 之間的解析差異 - Compound command 防護:
cd /path && evil.py不被cd:*放行
FileEditTool 的 TOCTOU 防禦
|
|
Hook 系統:可擴展的事件攔截
utils/hooks.ts(~160KB,5,023 行),25+ hook 事件類型:
| Hook Event | 觸發時機 | 典型用途 |
|---|---|---|
| SessionStart | Session 開始或恢復 | 載入 context、設定 env vars |
| SessionEnd | Session 終止 | 清理、保存狀態 |
| UserPromptSubmit | 使用者提交訊息 | 注入 git diff 作為 context |
| PreToolUse | Tool 執行前 | 阻擋危險命令、auto-lint |
| PostToolUse | Tool 成功後 | 自動 git stage、跑 formatter |
| PostToolUseFailure | Tool 失敗後 | 錯誤處理、重試邏輯 |
| SubagentStop | Subagent 完成時 | 結果收集 |
可複製的設計模式:
- Hook 可以是 shell 命令或 HTTP endpoint
- Hook 回傳 JSON
{"decision": "allow"}或{"decision": "deny", "reason": "..."} - 超時保護:每個 hook 有獨立超時設定
⚠️ 已知風險:
- Fork bomb:一位開發者寫了 SessionStart hook 啟動 2 個 Claude Code instance,每個又觸發 hook → 指數增長 1→2→4→8→2^N。SessionStart hook 必須冪等。
- 權限繞過:HTTP hook 回傳
{"decision": "allow"}可以繞過所有權限檢查。SDK/non-interactive 模式下不會彈出 workspace trust 對話框。 - 安全建議:SDK 模式下須加
--trust-projectflag 進行顯式信任設定
Auto Mode:獨立 LLM 分類器 + Circuit Breaker
Auto mode 不是 prompt 指令——是一個獨立的模型呼叫:
|
|
成本影響:每個 tool call 額外增加一次 Sonnet 4.6 inference——這是自主工作流中必須納入成本模型的開銷。
Circuit Breaker(Hard Limit):
- 3 consecutive blocks → 暫停 auto mode,切換手動確認
- 20 total blocks → 同上
可複製的設計:如果你要建 auto mode,不要用 prompt 指令控制權限——用獨立的(最好是更便宜的)模型做分類器,加上硬性限制防止失控。
CVE 教訓:Claude Code 安全的實際缺陷
洩漏後的安全審計揭示了 Claude Code 安全系統的實際缺陷:
| CVE | CVSS | 漏洞 | 教訓 |
|---|---|---|---|
| CVE-2025-59536 | 8.7 🔴 | 惡意專案設定檔 → RCE | 專案配置檔(.claude/、CLAUDE.md)是 attack surface |
| CVE-2025-59537 | 5.3 🟠 | 環境變數操作 → API key 外洩 | 環境變數處理是持久攻擊向量 |
| CVE-2026-25725 | — | 沙盒繞過 → 未授權檔案存取 | 沙盒邊界比想像中容易繞過 |
最關鍵的教訓:
-
Tree-sitter parser 已存在但未啟用:Claude Code 內部已經有正確的 AST parser,但公開版仍在使用有 CR 注入漏洞的舊版
splitCommand_DEPRECATED。僅一行修改——將 fallback 從「ask」改為「deny」——就能修補。安全修補不僅僅是寫程式碼,更是部署正確的程式碼。 -
SDK 模式權限削弱:non-interactive / SDK 模式下不會彈出 workspace trust 對話框,hook 可繞過權限。自動化環境的安全模型必須獨立設計,不能只是互動模式的子集。
-
npm 供應鏈風險:洩漏同日出現惡意 axios 版本(含 RAT 木馬)。依賴鏈本身就是攻擊面——考慮 native installer 或獨立二進位發佈。
第三課:Context 管理
4 層壓縮體系
flowchart LR
A[每輪查詢] --> B["第 1 層:微壓縮<br>規則操作,<1ms"]
B --> C["第 2 層:自動壓縮<br>上下文接近上限時"]
C --> D{優先嘗試}
D --> E["第 4 層:Session Memory<br>已有摘要,<10ms"]
D -->|失敗| F["第 3 層:傳統壓縮<br>Fork Agent,5-30s"]
| 層級 | 成本 | 觸發條件 | 做法 |
|---|---|---|---|
| 微壓縮 | 零 API 呼叫 | 每輪 | 替換舊工具輸出為 [cleared];或用 cache_edits API 保持 prompt cache |
| Session Memory 壓縮 | 零 API 呼叫 | 自動壓縮觸發時優先 | 直接使用已積累的 Session Memory(10 個固定章節) |
| 傳統壓縮 | 一次 Fork Agent inference | Session Memory 不可用 | Fork Agent 生成結構化摘要(共享 prompt cache) |
| 手動 /compact | 一次 inference | 使用者觸發 | 同上,使用者控制時機 |
核心原則:盡可能用廉價規則操作延遲昂貴的 LLM 呼叫。
Prompt Cache 設計
flowchart TB
subgraph "System Prompt"
A["--- SYSTEM_PROMPT_DYNAMIC_BOUNDARY ---<br>(全域快取區)<br>工具定義、核心指令<br>跨所有組織共享"] --- B["(Session-specific)<br>CLAUDE.md、git status、日期<br>每個 session 獨立"]
end
可複製的設計:
- 固定分割點讓全域部分快取命中最大化
- 追蹤 cache break vectors(14 種),但不嘗試恢復已打破的 cache(sticky latch)
- 壓縮後保留最近存取的檔案(每檔 ≤ 5K tokens),重新注入 context
壓縮的注意事項
⚠️ 摘要不區分指令來源:從檔案讀取的指令和用戶直接輸入的指令在摘要中無法區分。攻擊者可通過 CLAUDE.md 植入指令,經壓縮後永久存活。
防禦:壓縮 prompt 中要求列出「所有非工具結果的使用者訊息」,但仍無法區分指令來源。這是所有基於摘要的 context 管理的固有缺陷。
第四課:記憶體系統
三層記憶架構
flowchart TB
subgraph "記憶體層級"
L1["Layer 1:MEMORY.md 索引<br>(永遠載入 context)<br>每行 ≤ 150 字元,≤ 200 行"]
L2["Layer 2:Topic Files<br>(按需載入)<br>帶 YAML frontmatter<br>4 種類型"]
L3["Layer 3:原始 Transcript<br>(永不完整載入)<br>僅 grep 特定識別碼"]
end
L1 <-->|索引指向| L2
L1 -.->|grep 查詢| L3
記憶提取:Fork Agent + 嚴格工具限制
|
|
6 類不保存的內容(即使使用者要求):
- 可從程式碼推導的資訊(架構、檔案路徑)
- Git 歷史(
git log是權威來源) - 除錯步驟(修復在程式碼中)
- CLAUDE.md 中已有的內容
- 臨時任務細節
- 無意外之處的摘要
AI 驅動召回
|
|
關鍵原則:Skeptical Memory
- MEMORY.md 條目是「提示而非事實」
- 使用前必須對照實際程式碼驗證
- 「記憶說 X 存在」≠「X 現在存在」
秘密掃描
30 種秘密模式檢測,涵蓋 AWS/GCP/Azure/Anthropic/OpenAI/GitHub/Slack/Stripe 等 API 金鑰。匹配到的值永遠不被記錄或返回——只返回規則 ID 和人類可讀標籤。
第五課:多 Agent 編排
三種 Subagent 模式
| 模式 | 用途 | 隔離方式 | 適用場景 |
|---|---|---|---|
| Fork | Context 壓縮、並行任務 | 共享 prompt cache 的獨立 context | 短生命週期、需要快取命中 |
| Teammate | 持久協作 | InProcess / Tmux / iTerm2 | 長期並行工作 |
| Worktree | Git 隔離 | 獨立 git worktree | 需要獨立程式碼修改 |
Swarm 架構
flowchart TB
L[Leader Agent] -->|spawn| W1[Worker A<br>Tmux pane]
L -->|spawn| W2[Worker B<br>InProcess]
L -->|spawn| W3[Worker C<br>iTerm2]
W1 <-->|檔案 mailbox| W2
W2 <-->|檔案 mailbox| W3
W1 -->|權限請求| L
W2 -->|權限請求| L
可複製的設計:
- 檔案 mailbox 通信:JSON 檔案 + proper-lockfile(10 次重試,5-100ms 退避)
- 權限委託:Worker 的權限請求路由到 Leader 的 UI
- Coordinator 模式:Research → Synthesis → Implementation → Verification 四階段
- Worker prompt 必須自包含:看不到協調者對話,每個 prompt 需要完整上下文
Fork Agent 的 Cache 共享
|
|
第六課:效能優化
終端渲染
| 技術 | 效果 | 可複製性 |
|---|---|---|
| Int32Array 雙緩衝 | 每 cell 8 bytes,位打包樣式 | ✅ 任何 TUI 框架 |
| charCache(16K 上限) | 跨幀快取 grapheme 聚類 | ✅ |
| DECSTBM 硬體滾動 | 用終端原生滾動取代全區域重寫 | ✅ 支援的終端 |
| Blit 優化 | 乾淨節點直接 TypedArray.set() 複製 |
✅ |
| Peephole 優化 | 合併 cursor moves、取消 hide/show 對 | ✅ |
啟動優化
|
|
純 TypeScript 原生移植
Claude Code 將所有 C++/Rust 依賴移植為 TypeScript:
| 原始依賴 | 移植 | 效果 |
|---|---|---|
| Yoga(C++) | TypeScript Flexbox 引擎 | 4 槽環形快取:76K → 4K layoutNode 呼叫 |
| nucleo/fzf(Rust) | TypeScript 模糊搜索 | 字元位圖 O(1) 拒絕 + gap-bound 剪枝 |
| syntect/bat(Rust) | TypeScript 語法高亮 | highlight.js 延遲載入省 200ms 啟動 |
啟示:消除 native binary 依賴可大幅簡化部署和跨平台支援。
第七課:反蒸餾與認證
反蒸餾(如果需要)
| 方法 | 做法 | 效果 |
|---|---|---|
| 假工具注入 | API 請求中注入 decoy tool 定義 | 汙染訓練資料 |
| 推理壓縮 | 伺服器端摘要 + 密碼學簽名 | 隱藏完整 CoT |
現實:技術上可被 MITM proxy 或環境變數繞過。真正的防禦是法律和運營層面。
客戶端認證
|
|
啟示:將認證邏輯放在 JavaScript runtime 之下(Zig 層),防止 runtime patch 繞過。
第九課:遙測與可觀測性
遙測設計模式
Claude Code 的遙測系統不是事後加的——是從第一天就整合進去的基礎設施:
規模:640 遙測事件、40 裝置指紋維度、每 5 秒一次 API 查詢追蹤。
PII 隱私分層:
flowchart LR
A[遙測事件] --> B{PII 標記?}
B -->|是| C[_PROTO_ 前綴 key]
C --> D[First-Party Exporter<br>→ 受保護 BigQuery]
B -->|否| E[一般後端<br>→ Datadog / GrowthBook]
A --> F[離線] --> G[~/.claude/telemetry/<br>本地暫存]
PII 標記的值使用 _PROTO_ 前綴的 payload key,在傳送到 Datadog 等一般存取後端前被剝離,僅由 first-party exporter 路由到受保護的 BigQuery 欄位。
Statsig → GrowthBook 遷移教訓:Anthropic 原本使用 Statsig,直到 OpenAI 收購了 Statsig(2025/9),必須緊急遷移到開源的 GrowthBook。不要依賴可能被競爭對手收購的分析平台。
可複製的設計
|
|
關鍵差異:傳統 IDE 遙測記錄使用者如何操作介面。Agent 遙測記錄 agent 為使用者做了什麼——讀取了哪些檔案、執行了哪些命令。這是全新的可觀測性類別。
第十課:遠端控制與 Feature Flags
6 個遠端殺開關
Claude Code 有至少 6 個遠端殺開關,透過 GrowthBook feature flags 管理:
|
|
所有 flag 以 tengu_ 為前綴:tengu_auto_mode_config、tengu_harbor、tengu_amber_quartz_disabled 等。
55+ 編譯時特性開關
更強大的控制是編譯時 feature flags:外部 build 中為 false 的分支會被死代碼消除徹底刪除。涵蓋 KAIROS(6 個子開關)、CHICAGO_MCP、PROACTIVE、VOICE_MODE、ULTRAPLAN、COORDINATOR_MODE、SPECULATION 等。
|
|
可複製的設計:
- Runtime flags:用於 A/B 測試、緊急關閉功能、分階段推廣
- Compile-time flags:用於內部/外部 build 差異化,確保內部功能不會外洩到公開版本
- 兩者結合:compile-time 確保代碼不存在,runtime 確保可以遠端控制行為
對建構者的啟示:如果你要建商用 agent,feature flags 不是可選的——它們是發布管理、緊急響應和內部/外部版本差異化的基礎設施。
第八課:從零到一的實作路線圖
Phase 1:MVP(2-4 週)
|
|
Phase 2:安全加固(2-4 週)
|
|
Phase 3:智慧 Context(2-4 週)
|
|
Phase 4:多 Agent(4-6 週)
|
|
Phase 5:進階功能(持續)
|
|
工程原則總結
做什麼
| 原則 | 做法 |
|---|---|
| AST-first 安全 | 用 tree-sitter 解析命令,不依賴正則 |
| Fail-closed | 不確定 → 拒絕;未知 → 不安全 |
| Cache-aware | 每個設計決策考慮對 prompt cache 的影響 |
| Bandwidth-aware | Context window 是稀缺資源,記憶用索引 + 按需載入 |
| Skeptical memory | 記憶是提示不是事實,使用前驗證 |
| Fork for isolation | 記憶整合、壓縮摘要用 forked subagent 隔離 |
| Progressive compression | 每輪微壓縮,不等到緊急 |
| Shadow mode for iteration | 新舊安全檢查並行運行,記錄分歧 |
不做什麼
| 反模式 | 為什麼 |
|---|---|
| ❌ 單層安全檢查 | 任何一層都可被繞過 |
| ❌ 信任工具輸出 | Tool result 是 hostile input,需要 prompt-injection 掃描 |
| ❌ 全量載入記憶 | 索引 + 按需載入才有效率 |
| ❌ 一個壓縮策略 | 4 層遞進,用廉價操作延遲昂貴操作 |
| ❌ 正則做安全驗證 | Parser differential 會導致安全漏洞 |
| ❌ 不設 circuit breaker | Claude Code 因無限重試每天浪費 250K API 呼叫 |
重點整理
- Agent Harness ≠ Chat Wrapper:LLM 推理只佔 ~30%,剩下是 context 管理、安全、工具編排、記憶、效能
- 核心就是
while(tool_call):沒有意圖分類器、沒有 DAG 編排器——512K 行複雜性圍繞簡單迴圈建構 - MCP-first 工具架構:所有工具(包括 Computer Use)都是 MCP Server,統一介面、即插即用
- 安全是深度防禦:23 項 bash 驗證 + 8 步權限級聯 + TOCTOU 防禦 + 秘密掃描 + Hook 系統,每一層獨立運作
- Auto Mode 用獨立分類器:不是 prompt 指令,是額外 LLM inference + circuit breaker 硬限制
- CVE 教訓:安全修補不僅是寫程式碼,更是部署正確的程式碼;SDK 模式需要獨立安全模型
- Context 管理是核心競爭力:4 層壓縮 + prompt cache boundary + sticky latch,直接影響使用者體驗和 API 成本
- 記憶用 Skeptical 模式:索引指向 + 按需載入 + AI 評分召回 + 使用前驗證
- 多 Agent 用檔案 mailbox:簡單、可靠、易除錯,不需要 WebSocket 或 gRPC
- 效能優化從啟動開始:並行預取、延遲載入、消除 native 依賴
- 遙測是新類別的可觀測性:不只記錄使用者操作介面,更記錄 agent 為使用者做了什麼;PII 用前綴分流
- Feature flags 是基礎設施:runtime flags 控制行為 + compile-time flags 控制代碼存在
- 實作路線:MVP → 安全加固 → 智慧 Context → 多 Agent → 進階功能,每階段 2-6 週
參考資料
- Claude Code 源碼洩漏深度技術拆解(本文基礎)
- win4r/cc-notebook — Claude Code 源碼級中文深度分析
- Sabrina.dev — Comprehensive Analysis of Claude Code Source Leak
- Blake Crosley — What the Claude Code Source Leak Reveals
- Cordum — Claude Code Leak Analysis: Agent Control Plane Lessons
- Anthropic Engineering — Claude Code Auto Mode
- getaibook.com — Claude Code Source Code Deep Dive
- TEXXR — Claude Code Leak Exposes Security Threats
- The Register — Claude Code Leaked Source Code with Hidden AI Agent Controls
- The Register — Anthropic Claude Code Telemetry Sends Project Data Home
- Amplifying.ai — Claude Code Source Code Leak Analysis
- Atlas Peak Research — Claude Code Leak Technical Analysis
- DecodeTheFuture — Claude Code Telemetry Deep Dive
- Anthropic Official Response — Claude Code Source Code Exposure