看看 Claude Code 怎么做 Harness，這才是 Agent 工程化的真正難點

Claude Code 源代碼泄露的事情在 X 等平臺上引發了極大的關注。

不過，這次更值得關注的不是泄露本身，而是 Claude Code 非常典型的生產級 AI agent harness 設計，向外界完整地展示了一個成熟的 Autonomous Agent 產品應該長什么樣，從底層的工程實現到上層的產品決策邏輯，包含了各種細節。

結合 Substack 以及 Hacker News 上對于源代碼的分析，我們整理了 Claude Code 在 Agent 架構設計上值得開發者關注、學習的一些要點。

??關注 Founder Park，最及時最干貨的創業分享

超 22000 人的「AI 產品市集」社群！不錯過每一款有價值的 AI 應用。

邀請從業者、開發人員和創業者，飛書掃碼加群：

進群后，你有機會得到：

• 最新、最值得關注的 AI 新品資訊；
  

• 不定期贈送熱門新品的邀請碼、會員碼；
  

• 最精準的 AI 產品曝光渠道

01真正的難點，在模型之外的 Harness

Claude Code 的架構核心，是一個「Harness」本地運行時的外殼，更多地是依靠 Harness 的工程化與可靠性。

根據公開鏡像倉庫 nirholas/claude-code，Claude Code 的 TypeScript 源代碼跨越了約 1,900 個文件，超過 512,000 行嚴格類型的 TypeScript，基于 Bun 運行時構建，用 React 和 Ink 驅動終端 UI。

在架構文檔里，描述的 Claude Code 系統相當龐大：一個大型 QueryEngine、集中式工具注冊表、數十個斜杠命令、持久化記憶、IDE 橋接、MCP 集成、遠程會話、插件、技能，以及支持后臺和并行工作的任務層。

更準確的比喻是，Claude Code 更像是一個用于軟件工作的操作系統，圍繞模型堆疊了權限管理、記憶層、后臺任務、IDE 橋接、MCP 管道和多代理編排。

Vikash Rungta 在他的逆向工程分析里把這個東西叫做 Harnes：一個本地運行時外殼，把 LLM（Brain）包裹在工具、記憶和編排邏輯（Body）之中，讓模型能在現實世界里行動。

要想理解 Claude Code，首先要理解 Agent 架構的三個代際演進：

• 第一代是 Chatbot，無狀態問答；

• 第二代是 Workflow，用 n8n、LangChain 這類工具把 LLM 嵌進代碼驅動的 DAG 流里，代碼決定模型下一步做什么；

• 第三代是 Autonomous Agent，模型控制循環，運行時只是執行器。

Claude Code，就是屬于第三代的商業化產品。

Claude Code 的源碼也說明了，真正難的是 Harness，給任何支持工具調用的 LLM 提供文件系統訪問、shell、分層記憶和聲明式擴展能力。所有的這些，都要在一個由可組合權限約束的有界自主循環里運行。

02TAOR Loop 設計：Orchestrator 越笨，架構越穩定

Claude Code 的執行引擎是一個叫 TAOR 的循環：Think-Act-Observe-Repeat。這個設計本身不復雜，但背后的設計哲學，很值得關注。

它的 Orchestrator 本身被設計得極其「愚蠢」，只負責驅動循環、執行工具調用、感知結果。所有的推理、決策、何時停止，全部都交給模型。運行時不知道代碼是什么，不知道文件在哪，它只是跑循環，讓模型決定下一步。

總結來講：運行時越笨，架構越穩定。把智能下沉到模型，把確定性留給框架。

這和早期 LangChain 試圖在框架層做各種「聰明編排」的路線形成了鮮明對比。LangChain 更傾向于把編排邏輯寫進代碼，用復雜的 Orchestrator 控制 LLM 的每一步。Claude Code 的做法是，所有的推理、決策和停止判斷，統統下放給大模型本身。TAOR 循環的核心邏輯大約只有 50 行，但給了模型無限的操作空間。

同樣，在工具層遵循這個「笨」的哲學。Claude Code 沒有給模型配備 100 個專項工具，而是只提供四種能力原語：Read、Write、Execute、Connect。其中 Bash 是通用適配器，允許模型使用任何人類開發者會用的工具——git、npm、docker，全部通過 shell 組合完成。不要構建 100 個工具，給模型一個 shell，讓它自己組合。

隨著模型變得更強，腳手架應該變薄，而不是變厚。硬編碼的腳手架應該隨著模型能力提升而被主動刪除，架構隨時間推移越來越薄。如果你每次模型升級都要往框架里加更多腳手架，說明你在對抗模型，而不是利用模型。

03Context Window 是稀缺資源，不是越大越好

Context 不是越大越好，而是越干凈越好。這是 Claude Code 整個架構里貫穿始終的設計原則。

一般來說，Context Collapse 是 Agent 系統最普遍的失敗模式。隨著對話進行，上下文窗口被填滿，記憶退化，幻覺出現，Agent 開始在自己積累的噪音里迷失方向。但 Claude Code 把 Context Window 看成了一種需要主動管理的稀缺資源，圍繞 Context 構建了一套自動壓縮、子 Agent 隔離和詳盡的緩存經濟學防御體系。

第一層是 Auto-Compaction。當 Context 使用量達到約 50% 時自動觸發，用 LLM 摘要替換原始對話輪次，釋放空間的同時保留關鍵決策。這不是簡單地截斷歷史，而是用摘要壓縮，確保重要信息不丟失。這個機制對應的故障模式叫做 Context Collapse，解決方案是：Auto-compaction at ～50% + sub-agents with isolated context windows。

第二層是 Sub-Agent 隔離。把重型的探索、研究任務卸載給獨立的子 Agent。子 Agent 運行自己獨立的 TAOR 循環，有自己的 Context 預算，任務完成后只把摘要返回給主 Agent。這樣，無論子任務消耗了多少 token，主 Agent 的 Context 都不會被污染。

從代碼結構上看，這個機制的設計非常精細。子 Agent 運行時：有自己的 maxTurns 上限、有自己的 compaction 機制（獨立壓縮，不影響主對話）、有自己的 MEMORY.md。主 Agent 派出子 Agent 之后，只等一個 summary 回來，整個子任務的 token 消耗對主 Context 完全透明隔離。

第三層是 Prompt Cache 經濟學。promptCacheBreakDetection.ts 里追蹤了 14 個 cache-break 向量，也就是 14 種會讓 prompt 緩存失效的情況。代碼里還有一個函數叫 DANGEROUS_uncachedSystemPromptSection()，光是這個命名本身就是一種文檔：這里加東西要小心，會破壞緩存。代碼里還有多個 sticky latches，防止模式切換破壞 prompt 緩存的鎖定機制。

當你為每個 token 付費的時候，緩存失效不再是計算機科學笑話，更多的是一個財務問題。

此外，還有一個細節是：Session Continuity。在 Claude Code 里，會話不是一次性的。它們像 git branch 一樣運作，可以 checkpoint、rollback，或者把某個探索方向 fork 成一條新路徑。這意味著 Context 的管理不只是在單次會話內，而是跨會話的。

04記憶系統的核心是索引，不是存儲

Claude Code 的記憶系統設計，也非常有意思。

大多數人想象「Agent 記憶」就像一個更大的背包，裝得越多越好。但 Claude Code 的記憶系統，更像是一個帶有嚴格圖書管理員的檔案系統。

核心設計原則是：記憶是索引，不是存儲。能從代碼庫中重新推導出的信息，絕不應該被存儲。

從架構上看，Claude Code 的記憶系統分為六層，在每次會話啟動時按層加載：

• Managed Policy（組織級策略）：企業或團隊層面的統一規范

• Project CLAUDE.md（項目配置）：當前項目的特定指令和上下文

• User Preferences（用戶偏好）：個人層面的習慣和偏好設置

• Auto-Memory（自動學習模式）：Agent 從歷史交互中學到的用戶模式

• Session（會話上下文）：當前會話的臨時信息

• Sub-Agent Memory（子 Agent 記憶）：各子 Agent 獨立維護的專項記憶

其中，Auto-Memory 循環甚至允許 Agent 學習用戶的工作模式，并把這些模式寫入 MEMORY.md 供未來會話使用。用戶不需要反復解釋相同的事情，Agent 會從之前的交互里學習并記住重要信息。

同時，Claude Code 的子 Agent 記憶機制也值得一提。在自定義子 Agent 的配置里，可以設置 memory: user，Agent 會把學到的模式寫入 ~/.claude/agent-memory/ /MEMORY.md，下次調用時自動加載前 200 行。這意味著每個子 Agent 都可以有自己獨立的、持續積累的專項記憶。

更關鍵的是，這個系統具有主動自我編輯能力。它不僅會記錄，還會重寫、去重、甚至剪除互相矛盾的信息，過期且無效的記憶在這里被視為「負債」而非資產。

Claude Code 的記憶系統設計，也側面反映了：在產品層面，記憶不只是一個 Feature，它是決定用戶是否繼續使用的核心留存機制，因為用戶真正期待的是一個「會學習」的 Agent。

05權限系統的設計更像是 UX 設計，信任是可組合的

權限與安全問題，是 Agent 走向企業級應用的前提。

Claude Code 的權限系統被設計為一個五檔的信任光譜：

• plan：只讀，完全不能寫入，信任級別最低

• default：編輯和 shell 操作前都需要詢問，標準模式

• acceptEdits：自動批準文件編輯，shell 操作仍需詢問，中等信任

• dontAsk：自動批準白名單內的所有操作，高信任

• bypassPermissions：跳過所有檢查，僅限托管組織使用，最高信任

每個工具調用都經過靜態分析層的多層白名單校驗。bashSecurity.ts 里有 23 項編號的安全檢查，包括：

• 18 個被阻止的 Zsh 內置命令

• 防御 Zsh equals expansion：=curl 這種寫法可以繞過對 curl 的權限檢查

• unicode 零寬字符注入

• IFS null-byte 注入

• 一個在 HackerOne 審查期間發現的惡意 token 繞過

這種可組合的信任光譜，讓 Claude Code 能夠適應完全不同的使用場景：從什么都要確認的高度受限企業環境，到全速運行的個人開發環境。權限設計更像是 UX 設計。對于 Agent 產品來說，這也是從 Demo 進入企業生產環境的「門檻」。

同時，Claude Code 還有一個更底層、巧妙的機制是，API 請求在 JS 層之下做了身份驗證。

在 system.ts 文件里，每個 API 請求都包含一個 cch=00000 占位符。在請求真正離開進程之前，Bun 的原生 HTTP 棧（用 Zig 編寫，運行在 JavaScript 運行時之下）會把這五個零替換成一個計算出的哈希值。服務端會驗證這個哈希，確認請求來自真實的 Claude Code 二進制文件，而不是第三方偽造的客戶端。

之所以用等長的占位符，是為了讓替換不改變 Content-Length 頭部，也不需要緩沖區重新分配，這是一個很細節的工程考量。整個計算過程發生在 JS 層之下，對運行在 JS 里的任何代碼都完全不可見。本質上是在 HTTP 傳輸層實現的 API 調用 DRM。

這也是 Anthropic 此前向 OpenCode 發律師函背后的技術基礎。Anthropic 不只是要求第三方工具不要使用他們的 API，二進制文件本身通過加密證明了自己的身份。OpenCode 社區在收到法律通知后不得不訴諸會話拼接技巧和認證插件，原因就在這里。

06多 Agent 編排，從子 Agent 到 Agent Teams

Claude Code 的多 Agent 編排采用了橫向擴展的方式，分為兩層。

第一層：Sub-Agent

子 Agent 以獨立進程方式運行，有自己的 TAOR 循環、自己的 Context 預算、自己的 maxTurns 上限、自己的記憶。任務完成后，只把摘要返回給主 Agent，主 Agent 的 Context 完全不受影響。

Claude Code 內置了三種預設子 Agent，各有分工：

• Explore：用 Haiku 模型（速度快、成本低），只有只讀工具（Read、Grep、Glob），專門做文件發現和代碼庫探索

• Plan：繼承主 Agent 的模型，只有只讀工具，專門做代碼庫研究和規劃前的信息收集

• General-purpose：繼承主 Agent 的模型，配備全套工具，處理復雜的多步驟操作

自定義子 Agent 通過 .md 文件加 YAML frontmatter 定義，可以指定模型（sonnet/opus/haiku/inherit）、權限模式、maxTurns、可用工具白名單、禁用工具黑名單，甚至可以預加載特定的 Skills。存儲位置有三種：~/.claude/agents/（用戶級）、.claude/agents/（項目級），或通過 --agents CLI 參數指定。

子 Agent 還支持前臺和后臺兩種執行模式。前臺模式會阻塞主對話，權限詢問和問題會透傳給用戶；后臺模式則在用戶繼續工作的同時并發運行，權限在啟動前就預先收集，如果遇到沒有預批準的權限請求，工具調用直接失敗，Agent 繼續運行。按 Ctrl+B 可以把正在運行的前臺 Agent 切換到后臺。

第二層：Agent Teams

這不再是主 Agent 派遣子 Agent 的主從關系，而是完全獨立的 Claude Code 實例通過共享文件系統協調任務。兩者區別：

Agent Teams 的協調機制包括：Shared Task List（所有 Agent 可見任務狀態，完成當前任務后自主認領下一個未分配任務）、單播 Message（發給特定 Teammate）、Broadcast（發給所有 Teammate，注意成本隨團隊規模線性增長）、以及 Automatic Idle Notification（Teammate 完成任務停止時自動通知 Lead）。

同時，還有兩個專門針對團隊的質量門控 Hook：TeammateIdle（Teammate 即將進入空閑時觸發，返回 exit code 2 可以發送反饋讓它繼續工作）和 TaskCompleted（任務即將被標記完成時觸發，返回 exit code 2 可以阻止完成并要求修復）。

但 Agent Teams 目前還是實驗性功能，需要通過 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 環境變量或 settings.json 啟用。

07還沒發布的 KAIROS，一個 Always-On Agent

在這次泄露中，有一個 Claude Code 還未發布的功能 KAIROS，可以在后臺持續運行的 Agent。

根據 main.tsx 里的代碼路徑，KAIROS 是一個功能門控的未發布模式，包含以下特征：

• /dream 技能，用于夜間記憶蒸餾（nightly memory distillation）

• 每日 append-only 日志

• GitHub Webhook 訂閱

• 后臺 Daemon 工作進程

• 每 5 分鐘的 Cron 調度刷新

把這些特征拼在一起，是一個完全不同的產品形態：常駐后臺、持續學習、主動感知代碼庫變化的 Autonomous Agent。不是你召喚它，它來幫你，而是它一直在，主動為你工作。

現有的 Claude Code 是一個召喚式 Agent：你打開終端，它來幫你，你關掉終端，它就停了。但 KAIROS 描繪的是下一代形態：Agent 在后臺持續運行，通過 GitHub Webhook 感知代碼庫的變化，每天晚上做記憶蒸餾，把當天的工作模式和項目狀態壓縮進長期記憶，第二天一早已經「預熱」好了。

雖然不知道 Anthropic 內部對 KAIROS 的開發已經進展到了什么程度。但 KAIROS 的泄露說明了，Claude Code 的產品野心已經遠超「LLM + 命令行包裝」，朝著「終端操作系統級 Agent」方向前進。

08一些彩蛋：Anti-Distillation 機制、Undercover Mode

此外，在這次泄露的源碼里，還有一些非常有爭議性的工程決策，被扒了出來。

Anti-Distillation 機制

claude.ts 第 301-313 行有一個叫 ANTI_DISTILLATION_CC 的標志。當它開啟時，Claude Code 會在 API 請求里攜帶 anti_distillation: ['fake_tools'] 參數，服務端會向系統提示中靜默注入虛假的工具定義。

邏輯很直接：如果有人在錄制 Claude Code 的 API 流量來訓練競品模型，這些假工具會污染訓練數據。這個機制通過 GrowthBook 功能標志 tengu_anti_distill_fake_tool_injection 控制，只對第一方 CLI 會話激活。

還有第二層機制在 betas.ts 第 279-298 行：服務端 connector-text 摘要。啟用時，API 會緩沖 Assistant 在工具調用之間的推理文本，對其摘要后返回帶加密簽名的版本。在后續輪次里，原始文本可以從簽名恢復。錄制 API 流量的人只能拿到摘要，拿不到完整的推理鏈。

Undercover Mode

undercover.ts 文件大約 90 行，實現了一個單向門：當 Claude Code 在非 Anthropic 內部倉庫里使用時，它會指示模型永遠不提及內部代號（比如 Capybara、Tengu）、內部 Slack 頻道、倉庫名稱，甚至不提及 Claude Code 這個名字本身。

第 15 行有一條注釋寫得很清楚：

There is NO force-OFF. This guards against model codename leaks.

你可以用 CLAUDE_CODE_UNDERCOVER=1 強制開啟，但沒有辦法強制關閉。在外部構建里，整個函數會被死代碼消除為平凡返回。這是一個單向門。

這意味著，Anthropic 員工在開源項目里用 Claude Code 生成的 commit 和 PR，將沒有任何 AI 參與的標記。如何在商業防御需求與 AI 透明度倫理之間做權衡，也是值得思考的事情。

轉載原創文章請添加微信：founderparker