15 張圖，拆解最賺錢的 Harness Engineering Agent 產品是如何實現的
整理版優先睇
Claude Code 嘅成功在於系統完整性，唔係單點能力強，而係將交互、上下文、工具、權限、技能、多代理、測試整合成一套可長期運行嘅工作系統。
呢篇文章透過分析 Claude Code 嘅源碼樣本，拆解頂級 Harness Engineering Agent 產品嘅實現方法。作者認為，真正值得學嘅唔係某一句 prompt 或者某一個 tool，而係點樣將任務進入、會話持續、動態 prompt 組裝、工具統一調度、skill 穩定執行、高風險動作約束、subagent 協作、系統持續驗證同演進，整合成一套完整系統。
文章用 15 張圖逐步拆解系統。首先係系統邊界：Claude Code 唔係「模型 + 終端 UI」，而係用戶、模型、本地環境、遠程能力之間嘅控制中樞。功能視角上有 12 個功能域，包括交互界面、會話編排、主循環、系統提示詞等等。實現視角上分 7 層：交互層、會話編排層、Loop Runtime 層、上下文層、能力層、控制層、演進層。
整體結論係：Claude Code 真正厲害嘅地方係完整性，佢唔係將能力堆喺模型身上，而係將模型放入一個成熟嘅工作系統，有入口、主循環、上下文裝配、prompt 生成器、統一工具接口、skill 執行機制、權限控制、subagent 同 team 協作、測試遙測反饋。呢啲加埋先至係頂級 Harness Engineering Agent 嘅真正面貌。
- Claude Code 嘅核心係任務主循環，而唔係模型本身；系統負責將環境、能力同邊界擺好，模型做局部推理。
- System Prompt 係動態生成嘅，分靜態區、動態區同緩存邊界，支援優先級鏈，唔係一段固定文字。
- 工具同擴展先做統一接口，所有能力（內置 tool、MCP、skill、subagent）都收成 Tool 或 Command 兩種形式，確保權限鏈一致。
- 安全控制分三層：trust、permission、sandbox，喺模型見到工具之前先裁剪，執行前再確認，落地時再限制。
- 多代理支援三種協作模式：Subagent（獨立執行）、Coordinator + Worker（拆派任務）、Swarm / Team（並行搶任務），唔係簡單開新對話。
Workclaw - 開源企業桌面智能體
作者開發嘅類似開源產品，基於 Claude Code 嘅設計理念。
系統邊界同功能全景
Claude Code 唔係「模型加終端 UI」，而係一個控制中樞，位於用戶、模型、本地環境同遠程能力之間。用戶俾嘅係任務，唔係問題；返回嘅係改動、計劃、驗證結果等。
控制中樞
功能視角上，系統需要至少 12 個功能域先算完整，包括交互界面、會話編排、主循環、系統提示詞、上下文裝配、記憶壓縮、工具/MCP、Skills、權限審批、狀態持久化、Subagent/Agent Team、觀測測試。呢 12 個域一齊組成一個能長期運轉嘅系統。
- 交互界面負責將人類輸入變成可進入會話系統嘅 turn
- 會話編排持有 transcript、usage、resume 等跨輪狀態
- 主循環 queryLoop() 係心跳，每輪決定繼續、停下、調工具、壓縮定重試
主循環同上下文裝配
主任務循環 src/query.ts 嘅 queryLoop() 有 6 個關鍵動作：準備有效 system prompt 同上下文、發起流式模型調用、接收 tool_use、執行工具並寫回 tool_result、決定繼續/壓縮/重試/結束、將消息/usage/狀態寫回會話。呢條主循環成熟嘅地方係將 streaming、retry、tool result、compaction、state update 接成穩定流程。
穩定流程
上下文裝配好講究，唔係將材料一股腦塞入 prompt，而係明確分三類：System Prompt（身份、規則、能力約束）、System Context（git 狀態、環境態）、User Context（CLAUDE.md、日期）。其中 CLAUDE.md 唔係可有可無，而係倉庫個性化定義嘅上下文，容許用戶透過文檔參與 agent 行為控制。
- 1 提示詞係 string[]，唔係一段字符串，方便分區段
- 2 有明確優先級鏈，不同運行方式拎到不同內容
- 3 動態邊界標記直接影響成本同效能
prompt cache 命中率
能力層：工具統一接口同 Skills
Claude Code 有好多能力來源：內置 tool、shell/file/git、MCP tool、skill、plugin command、agent。但最終都收成兩種固定形式：Tool 同 Command。呢層統一好重要，因為一旦能力來源變多，難嘅唔係接入新能力，而係點樣令新能力仍然進入同一條權限鏈、提示詞鏈同執行鏈。
權限鏈
執行鏈
Skills 唔係預設 prompt 咁簡單，而係一個可發現嘅能力入口、一個工作流模板、一個帶 frontmatter 嘅配置說明、一個可 inline 或 fork 執行嘅系統命令、一個需要系統認真管理嘅對象。完整鏈路係：SKILL.md -> parseFrontmatter -> createSkillCommand -> 注入 System Prompt -> SkillTool.validateInput -> checkPermissions -> call。
- Tool 同 Command 係兩種固定形式，所有能力經呢兩個接口進入系統
- MCP、skill、subagent 唔係三套孤立系統，而係收埋入同一套運行規則
- Skill 唔係錦上添花，而係將工作流變成產品能力嘅關鍵
控制層：權限審批同 Subagent 協作
安全設計係三層控制：trust、permission、sandbox。系統喺模型見到工具之前先裁剪工具池；喺 tool use 前根據規則判斷 allow/deny/ask；喺具體執行時用 sandbox 卡住文件系統同命令邊界。做法係暴露之前先過濾，執行之前再確認，落地時再限制。
三層控制
Subagent 唔係多開會話，而係一條規範嘅任務派發流程：解析 agent 類型或 fork 路徑、組裝獨立工具池、注入獨立 system prompt、必要時創建獨立 worktree、跑獨立主循環、回傳結果。有兩個強設計：fork 同 named agent 係兩條路徑，前者繼承上下文同共享 prompt cache；後者強調獨立角色同能力。subagent 仍然複用主系統嘅工具、權限、狀態同結果格式。
- 1 fork 強調繼承上下文，named agent 強調獨立角色
- 2 Coordinator 自己唔做髒活，只負責拆派任務
- 3 Swarm 用任務搶佔機制，多個 teammate 並行完成任務
任務操作系統
演進層：測試、遙測同 Feature Flags
呢層決定 agent 產品係咪「呢個星期跑得鬱」定係「長期可維護」。Claude Code 有三條持續改進機制：tests 驗證系統行為有無回退；telemetry 睇真實使用發生咩事；feature flags / GrowthBook 讓新能力先小範圍試運行先決定是否放開。唔係先改 code 再祈禱，而係喺真實運行入面持續觀察、試驗、改進。
持續觀察
持續試驗
- tests 驗證回歸，確保改動唔破壞現有行為
- telemetry 收集真實使用數據，發現潛在問題
- feature flags 容許逐步 rollout，降低風險
呢篇文章淨係回答一個問題：
一個頂級嘅 Harness Engineering Agent 產品，究竟係點樣整出嚟嘅。
呢篇文章研究嘅對象，係前幾日洩漏出嚟嘅 Claude Code 源碼樣本。真正值得學嘅，唔係某一句 prompt，亦唔係某一個 tool，而係佢點樣將交互、上下文、工具、權限、技能、多代理、測試同演進，砌成一套可以長期運作嘅系統。
Claude Code 最強嘅地方，係佢將一個 agent 產品真正落地時最難嘅幾層，全部補齊咗：
任務點樣進入系統 會話點樣持續 prompt 點樣動態組裝 工具點樣俾統一調度 skill 點樣穩定執行 高風險動作點樣被約束 subagent 同 agent team 點樣協作 系統點樣持續驗證、持續演進
呢個就係 harness engineering。
圖 1：先睇整體，佢到底係咩產品
呢張圖睇嘅係系統邊界。
Claude Code 唔係「模型 + 終端 UI」。
佢更似一個位於用戶、模型、本地環境、遠程能力之間嘅控制中樞。用戶俾佢嘅係任務，唔係問題；佢返嚟嘅亦唔只係答案，而係改動、計劃、驗證結果、子代理結果。
由呢個邊界出發，後面所有複雜性，本質上都喺度回答同一個問題：
點樣令模型安全、穩定、持續咁喺真實環境入面做嘢。
圖 2：產品功能全景，12 個功能域
呢張圖係功能視角。
佢回答嘅係：Claude Code 作為一個產品，到底要具備啲咩完整能力。
Claude Code 呢種級別嘅系統，淨係講「交互、上下文、工具、安全」係唔夠嘅。真正落到產品層，佢至少要拆成 12 個功能域。
呢 12 個域唔係簡單並列，佢哋一齊組成咗一個可以長期運轉嘅系統：
交互界面：REPL、輸入框、消息展示、工具反饋都喺呢一層。佢負責將人類輸入變成可以進入會話系統嘅 turn。會話編排：QueryEngine.ts持有 transcript、usage、resume、denial 等跨輪狀態。佢唔係 UI 層，而係對話生命週期管理器。主循環：src/query.ts的queryLoop()先係 agent 嘅心跳。每一輪都要決定繼續、停下、調工具、壓縮定係重試。系統提示詞：唔係一段固定文本，而係一套帶優先級、帶緩存邊界、帶動態 section 嘅生成器。上下文裝配：CLAUDE.md、git 狀態、memory、環境信息、MCP 指令，唔係隨手拼接，而係按固定位置同緩存策略插返入去。記憶與壓縮：長會話一定會爆 token。Claude Code 唔係靠「少講嘢」解決，而係靠 compact、memory、invoked skills 保持長期連續性。工具 / MCP：內置工具、本地 shell、文件工具、MCP 遠程工具，都要先整理入同一個工具池，再俾模型睇。Skills：skill 唔係提示詞附件，而係系統入面正式接入嘅一種能力。佢要俾人發現、匹配、執行、追蹤、壓縮之後恢復。權限 / 審批：唔係單點彈窗，而係 trust、permission、tool allow/deny、sandbox 組成嘅一整套控制流程。狀態持久化：session、project state、tasks、worktree、session storage 共同保證系統「下次仲可以繼續做」。Subagent / Agent Team：fork、worker、coordinator、swarm 代表唔同協作方式，唔係一個泛泛嘅「多代理」概念。觀測 / 測試 / Feature Flags：冇 telemetry、tests、GrowthBook 呢層，前面 11 層就只係可以運行，唔算產品。
呢張圖最重要嘅價值，係將「完整性」講出嚟。
Claude Code 唔係某一塊做得勁，而係應該有嘅產品能力幾乎都喺度。
但呢張圖仲未係實現圖。
因為同一個功能域，往往會同時涉及好幾層實現。所以下一張圖要換一個視角，唔再睇「佢識咩」，而睇「呢啲能力喺系統入面分別落到邊幾層實現」。
圖 3：系統實現分層，7 層結構
呢張圖係實現視角。
佢回答嘅係：上面嗰 12 個功能域，喺系統真正運行嘅時候，係按咩層次組織起嚟嘅。
所以圖 2 同圖 3 唔係包含關係，而係同一個系統嘅兩種睇法：
圖 2 橫向睇能力 圖 3 縱向睇佢喺系統入面分成邊幾層
一個功能域可以跨多層，一層入面都可以裝多個功能域。例如：
Skills喺圖 2 係獨立功能域，但喺圖 3 主要放喺能力層，同時又會碰到上下文層和控制層系統提示詞、上下文裝配、記憶 / 壓縮喺圖 2 分成 3 個域，但喺圖 3 會一齊放喺上下文層權限 / 審批喺圖 2 係一個產品能力，但喺圖 3 會被收埋入控制層Subagent / Agent Team喺圖 2 係獨立域，但喺圖 3 主要放喺能力層，同時依賴會話編排層和狀態層
如果將上面嘅 12 個域進一步壓縮，Claude Code 嘅底層結構其實可以歸成 7 層：
交互層 會話編排層 Loop Runtime 層 上下文層 能力層 控制層 演進層
呢張圖要睇兩件事。
第一，佢唔係「模型喺最中間」，而係「任務主循環」喺最中間。說明系統真正嘅核心唔係模型本身，而係圍住模型運轉嗰套執行流程。
第二，上下文層、能力層、控制層 都喺主循環外面俾佢提供材料、工具同邊界。呢個就係 harness engineering 嘅典型結構：模型只負責局部推理，系統負責將環境、能力同邊界擺好。
圖 4：啟動入口同運行方式，點解佢唔係一個單模式 CLI
Claude Code 嘅入口唔只得一條。
從 src/entrypoints/cli.tsx、src/main.tsx、src/init.ts、src/setup.ts 往下睇，佢由一開始就唔係「命令行列隊開個 REPL」咁簡單。
佢至少同時支援幾種運行方式：
交互式終端 headless / SDK 調用 bridge / remote 控制 daemon / worker 異步執行
呢張圖說明咗一個好關鍵嘅產品判斷：
頂級 agent 產品唔會將自己做成單入口玩具，而會將自己做成一個可嵌入、可託管、可異步、可遠程驅動嘅執行系統。
亦正因為佢將唔同運行方式拆開設計，後面先可以實現 subagent、後台任務、remote task 同 team 協作。
圖 5：主任務循環，Claude Code 嘅心跳到底點樣跳
呢張圖對應 src/query.ts 和 src/QueryEngine.ts。
佢回答嘅係最核心嘅問題：
一條任務入咗系統之後，到底點樣一輪一輪咁推進。
呢個主循環入面至少有 6 個關鍵動作：
準備有效 system prompt 同上下文 發起流式模型調用 接收 tool_use執行工具並寫返入去 tool_result決定繼續、壓縮、重試定係結束 將消息、usage、狀態寫返入會話
Claude Code 呢條主循環真正成熟嘅地方，係佢將 streaming、retry、tool result、compaction、state update 都駁成一條穩定流程。即係話，佢解決嘅唔係「能唔能叫工具」，而係「叫完之後系統仲可唔可以穩定咁繼續行落去」。
圖 6：狀態同持久化，點解佢可以連續工作
如果一個 agent 產品只靠內存行，如果出現異常情況，佢就好難恢復。
Claude Code 喺呢塊透過狀態同持久化，解決咗呢個問題。
從 src/bootstrap/state.ts、src/state/AppStateStore.ts、src/utils/sessionStorage.ts、src/utils/tasks.ts 可以見到，佢至少喺管理呢啲狀態：
transcript usage tool permission context session storage tasks worktree 信息 project root / cwd memory 同 invoked skills
呢層嘅意義係：
令系統唔係「每輪重新開始」，而係「帶住上輪狀態繼續工作」。
呢個對於長任務、後台任務、subagent、resume、compact 之後恢復，都係前提。
圖 7：上下文裝配，唔係將材料一嘢塞入 prompt
Claude Code 嘅上下文設計非常講究。
佢唔係將所有材料拼成一段大文本，而係明確分成三類：
System Prompt：系統身份、規則、能力約束System Context：git 狀態、環境態、緩存相關上下文User Context：CLAUDE.md、日期、用戶級補充信息
src/context.ts 和 src/query.ts 好清楚咁將呢三類做咗唔同注入。
呢張圖最值得留意嘅，係 CLAUDE.md 嘅位置。
佢唔係可有可無嘅說明文件，而係倉庫個性化定義信息嘅上下文。即係話，Claude Code 由設計上就接受「用戶可以透過文檔參與 agent 行為嘅控制」。
呢個亦係佢點解比好多「單 prompt agent」更實用。因為真實工程知識，本來就散落喺 repo 入面。
圖 8：System Prompt，唔係一段文本，而係一套生成器
呢個係 Claude Code 最容易被低估嘅一層。
從 src/constants/prompts.ts、src/constants/systemPromptSections.ts、src/utils/systemPrompt.ts 去到 API 發送前嘅 block 化處理，成條鏈路都說明咗一件事：
System Prompt 喺呢度係系統拼出嚟嘅結果，唔係手寫好嘅一整段文本。
佢大致經過三步：
getSystemPrompt()組裝默認 sectionsbuildEffectiveSystemPrompt()決定優先級buildSystemPromptBlocks()按緩存邊界切塊
呢度最重要嘅設計點有三個。
第一，提示詞係 string[]，唔係一整段字符串。咁先可以分靜態區、動態區同緩存邊界。
第二，存在明確嘅優先級鏈：
Override > Coordinator > Agent > Custom > Default
呢個意味住 Claude Code 唔係靠一條 prompt 打天下，而係允許唔同運行方式拎到唔同嘅內容。
第三，SYSTEM_PROMPT_DYNAMIC_BOUNDARY 呢種分界標記非常關鍵。佢將可以全局緩存嘅靜態內容同每輪都變嘅動態內容切開，直接影響 prompt cache 命中率同成本。
呢個就係 harness engineering 同 prompt engineering 嘅分別。
前者研究嘅唔係「點樣寫一句厲害嘅說話」，而係「點樣將提示詞做成一個可緩存、可分層、可替換、可運行嘅系統」。
圖 9：記憶與壓縮，Claude Code 點樣對抗長上下文衰減
agent 產品做長任務，一定會遇到兩個問題：
token 會爆 歷史會丟
Claude Code 喺呢塊嘅答案，唔係簡單截斷，而係將 compact、memory、relevant recall、invoked skills 駁成一套連續機制。
從 src/services/compact/*、src/memdir/*、bootstrap/state 睇，至少有三層設計：
會話太長嘅時候，透過 compact 保留核心結論，唔保留原始細節 重要知識寫入 memory 文件體系，而唔係堆喺當前輪上下文入面 對已經調用過嘅 skill 做顯式追蹤，壓縮之後仲可以繼續知道「之前調過啲咩」
呢張圖說明嘅係：
Claude Code 將「長任務點樣唔中斷」當成核心問題。
所以佢唔係「盡量唔好傾咁多」，而係「容許你傾好多，但系統會主動重排上下文」。呢個就係成熟 agent 嘅差異。
圖 10：工具與擴展，唔係堆能力，而係先做統一接口
Claude Code 入面有好多能力來源：
內置 tools shell / file / git MCP tools skills plugin commands agents
但從 src/Tool.ts、src/tools.ts、src/commands.ts、src/services/mcp/client.ts 往下睇，最終都俾收成兩種固定形式：
ToolCommand
呢層統一非常重要。
因為一旦能力來源開始變多，系統真正難嘅就唔係「接入一個新能力」，而係「點樣令新能力仍然入到同一條權限鏈、同一條提示詞鏈、同一條執行鏈」。
Claude Code 喺呢件事上係清醒嘅。佢冇將 MCP、skill、subagent 分別做成三套孤立系統，而係盡量將佢哋收埋入同一套運行規則入面。
呢個亦係點解佢擴展好多，但系統冇散開。
圖 11：Skills，唔係提示詞菜單，而係工作流封裝層
好多人會將 skill 理解成「預設 prompt」。
呢個只係講啱一半。
喺 Claude Code 入面，skill 至少同時擔當 5 個角色：
一個可發現嘅能力入口 一個可以俾模型匹配嘅工作流模板 一個帶 frontmatter 嘅配置說明 一個可以 inline 或 fork 執行嘅系統命令 一個需要俾系統認真管理嘅對象
從 docs/extensibility/skills.mdx、src/skills/loadSkillsDir.ts、src/tools/SkillTool/SkillTool.ts 往下睇，skill 嘅完整鏈路係：
SKILL.md -> parseFrontmatter -> createSkillCommand -> 注入 System Prompt -> SkillTool.validateInput -> checkPermissions -> call
佢最成熟嘅地方，唔係「skill 可以執行」，而係「skill 點樣穩定、安全咁執行」。
Claude Code 喺呢度做咗幾層保護：
allowedTools只係改變權限上下文，唔會直接繞過工具權限SAFE_SKILL_PROPERTIES係白名單，唔認識嘅新屬性默認要審批MCP skills被視為遠程來源，唔允許本地 shell 內聯替換skill 可以行 inline，亦可以行fork，長任務唔會污染主會話調用過嘅 skill 會被記錄入狀態，compact 之後仲可以恢復連續性
呢個就係點解 skill 喺 Claude Code 入面唔係「錦上添花」，而係將工作流真正做成產品能力嘅關鍵一層。
圖 12：權限、審批、沙箱，真正嘅控制層喺呢度
Claude Code 嘅安全設計，唔可以淨係睇一個 permission 彈窗。
佢實際係一套三層控制流程：
trust：當前環境同當前會話嘅信任前提permission：呢個動作而家允唔允許sandbox：就算允許，都只可以喺咩邊界入面做
從 src/utils/permissions/*、src/utils/sandbox/*、interactiveHelpers.tsx 往下睇，系統真正做嘅係：
喺模型見到工具之前先裁剪工具池 喺 tool use 之前根據規則判斷 allow / deny / ask 喺具體執行時再用 sandbox 卡住文件系統同命令邊界
即係話，Claude Code 嘅做法唔係「先放開，再兜底」，而係「暴露之前先過濾，執行之前再確認，落地時再限制」。
呢個先係產品級控制系統。
圖 13：Subagent，唔係多開會話，而係一條規範嘅任務派發流程
好多產品做多代理，其實只係「開一個新對話」。
Claude Code 唔係。
從 src/tools/AgentTool/AgentTool.tsx、forkSubagent.ts、runAgent.ts 往下睇，subagent 至少被做成一條好規範嘅執行流程：
解析 agent 類型或 fork 路徑 組裝獨立工具池 注入獨立 system prompt / prompt messages 必要時建立獨立 worktree 行一套獨立嘅 agent 主循環 回傳結果、usage 同通知
佢入面有兩個特別強嘅設計。
第一，fork 和 named agent 係兩條唔同路徑。前者強調繼承上下文同共享 prompt cache；後者強調獨立角色同獨立能力。
第二，subagent 唔係單獨喺外面行，佢仍然複用主系統嘅工具、權限、狀態同結果格式。呢個意味住多代理唔係額外拼上去嘅功能，而係系統本身就支援嘅能力。
圖 14：Agent Team / Coordinator / Swarm，唔係一種多代理，而係三種協作方式
Claude Code 喺多代理上做得比好多項目更深。
佢至少有三種組織方式：
Subagent：適合將一件事拆出去單獨做Coordinator + Worker：適合集中決策、分工執行Swarm / Team：適合多個並行任務自主認領
src/coordinator/coordinatorMode.ts 同任務系統代碼說明，Coordinator 模式嘅重點唔係「更強模型」，而係角色約束。
Coordinator 自己唔做骯髒活，佢只負責：
理解任務 拆任務 派任務 接收 <task-notification>綜合結果
佢甚至只保留少量調度工具，故意唔俾自己直接寫代碼。呢個設計好硬核，因為佢強制系統將「理解」同「執行」分開。
Swarm 就係另一套邏輯。佢依賴共享 task list、claimTask、mailbox 同 owner 機制，令多個 teammate 去搶佔同完成任務。呢個更似一個輕量級任務操作系統，而唔係簡單並發。
所以唔好將「agent team」理解成幾個 agent 一齊行。
喺 Claude Code 入面，佢已經開始接近組織設計問題了。
圖 15：測試、遙測、Feature Flags，Claude Code 點解可以一直演進
最後呢一層，往往最容易被忽略。
但恰恰係呢一層，決定一個 agent 產品能唔能夠由「呢個禮拜行到」變成「長期可維護」。
Claude Code 喺呢塊至少有三條持續改進嘅機制：
tests：驗證系統行為有冇倒退telemetry：睇真實使用入面發生咗咩feature flags / GrowthBook：令新能力先細範圍試行，再決定係咪放開
docs/testing-spec.md、docs/internals/feature-flags.mdx、docs/internals/growthbook-ab-testing.mdx 和 src/services/analytics/growthbook.ts 一齊說明，Claude Code 唔係先改代碼再祈禱，而係喺真實運行入面持續觀察、持續試驗、持續改進。
呢個亦係 harness engineering 最容易被忽視，但實際上好重要嘅一層。
因為前面嘅主循環、skills、subagent、sandbox 都會不斷變化。冇咗呢層反饋機制，系統只會越來越脆弱。
最後收一收：Claude Code 真正值得學嘅，係完整性
如果淨係睇某一塊，Claude Code 唔係好神秘。
佢嘅好多單點設計，你都可以喺其他 agent 項目入面見到影子：tool use、memory、subagent、skill、MCP、sandbox、feature flag。
真正令佢拉開差距嘅，係呢啲嘢都俾接入咗一套完整系統入面。
佢唔係將能力向模型身上堆。
佢係將模型放入一個成熟嘅工作系統入面：
有入口 有主循環 有上下文裝配 有 prompt 生成器 有統一嘅工具接口層 有 skill 嘅執行機制 有權限控制系統 有 subagent 同 team 協作 有測試同遙測反饋機制
呢個先係頂級 harness engineering agent 產品真正嘅樣。
佢唔係「更識得傾偈」。
佢係「更似一個可以工作嘅系統」。
我都喺度開發一個類似嘅開源企業桌面智能體產品 workclaw(https://github.com/haojing8312/workclaw)，介紹如下：
https://my.feishu.cn/wiki/O62Pwtb94ikFEJkYHuEcxaWanQb
名詞解釋
Harness Engineering：駕馭工程，唔係研究模型點樣回答，而係研究點樣將模型變成一個可以長期工作嘅產品系統。Runtime：可以理解成「系統真正做嘢嗰一層」。任務會喺入面流轉、執行、重試、結束。REPL：終端入面嗰種你輸入一句、系統答一句、仲可以繼續再輸入嘅交互殼。System Prompt：俾系統設定身份、規則、邊界嘅頂層說明書。喺 Claude Code 入面佢係動態生成嘅，唔係固定一段話。Prompt Cache：提示詞緩存。前面嘅上下文如果唔變，就唔使每次都重新計錢、重新計 token。MCP：俾 agent 駁外部能力嘅一套標準協議。你可以理解成 agent 嘅標準擴展插槽。Skill：將一套工作流經驗封裝成一個可執行能力，唔止係提示詞模板。Sandbox：沙箱。就算系統允許執行，都只可以喺限定邊界入面鬱文件、行命令。Subagent：被主 agent 派出去處理子任務嘅代理，相當於一個可控嘅臨時外包工位。Coordinator：總調度。自己盡量唔落場做嘢，主要負責拆任務、派任務、收結果。Swarm / Agent Team：多代理協作形態。前者更似分佈式搶任務，後者更似有組織嘅項目組。Worktree：Git 嘅獨立工作副本。可以理解成「同一個倉庫臨時開一個隔離工位」，方便子代理安全試改。
本文只回答一個問題：
一個頂級的 Harness Engineering Agent 產品，到底是怎麼被做出來的。
本文研究對象，是前幾天泄露的 Claude Code 源碼樣本。真正值得學的，不是某一句 prompt，也不是某一個 tool，而是它怎麼把交互、上下文、工具、權限、技能、多代理、測試和演進，組裝成一套能長期工作的系統。
Claude Code 最強的地方，是它把一個 agent 產品真正落地時最難的幾層，全都補齊了：
任務怎麼進入系統 會話怎麼持續 prompt 怎麼動態組裝 工具怎麼被統一調度 skill 怎麼穩定執行 高風險動作怎麼被約束 subagent 和 agent team 怎麼協作 系統怎麼持續驗證、持續演進
這就是 harness engineering。
圖 1：先看整體，它到底是什麼產品
這張圖看的是系統邊界。
Claude Code 不是“模型 + 終端 UI”。
它更像一個位於用戶、模型、本地環境、遠程能力之間的控制中樞。用戶給它的是任務，不是問題；它返回的也不只是答案，而是改動、計劃、驗證結果、子代理結果。
從這個邊界出發，後面所有複雜性，本質上都在回答同一個問題：
怎麼讓模型安全、穩定、持續地在真實環境裏做事。
圖 2：產品功能全景，12 個功能域
這張圖是功能視角。
它回答的是：Claude Code 作為一個產品，到底要具備哪些完整能力。
Claude Code 這種級別的系統，光講“交互、上下文、工具、安全”是不夠的。真正落到產品層，它至少要拆成 12 個功能域。
這 12 個域不是簡單並列，它們一起組成了一個能長期運轉的系統：
交互界面：REPL、輸入框、消息展示、工具反饋都在這一層。它負責把人類輸入變成可進入會話系統的 turn。會話編排：QueryEngine.ts持有 transcript、usage、resume、denial 等跨輪狀態。它不是 UI 層，而是對話生命週期管理器。主循環：src/query.ts的queryLoop()才是 agent 的心跳。每一輪都要決定繼續、停下、調工具、壓縮還是重試。系統提示詞：不是一段固定文本，而是一套帶優先級、帶緩存邊界、帶動態 section 的生成器。上下文裝配：CLAUDE.md、git 狀態、memory、環境信息、MCP 指令，不是隨手拼接，而是按固定位置和緩存策略插進去。記憶與壓縮：長會話一定會爆 token。Claude Code 不是靠“少說話”解決，而是靠 compact、memory、invoked skills 保持長期連續性。工具 / MCP：內置工具、本地 shell、文件工具、MCP 遠程工具，都要先整理進同一個工具池，再給模型看。Skills：skill 不是提示詞附件，而是系統里正式接入的一種能力。它要能被發現、被匹配、被執行、被追蹤、被壓縮後恢復。權限 / 審批：不是單點彈窗，而是 trust、permission、tool allow/deny、sandbox 組成的一整套控制流程。狀態持久化：session、project state、tasks、worktree、session storage 共同保證系統“下次還能接着幹”。Subagent / Agent Team：fork、worker、coordinator、swarm 代表不同協作方式，不是一個泛泛的“多代理”概念。觀測 / 測試 / Feature Flags：沒有 telemetry、tests、GrowthBook 這層，前面 11 層就只是能跑，不算產品。
這張圖最重要的價值，是把“完整性”講出來。
Claude Code 不是某一塊做得強，而是該有的產品能力幾乎都在。
但這張圖還不是實現圖。
因為同一個功能域，往往會同時涉及好幾層實現。所以下一張圖要換一個視角，不再看“它會什麼”，而看“這些能力在系統裏分別落到哪幾層實現裏”。
圖 3：系統實現分層，7 層結構
這張圖是實現視角。
它回答的是：上面那 12 個功能域，在系統真正運行時，是按什麼層次被組織起來的。
所以圖 2 和圖 3 不是包含關係，而是同一個系統的兩種看法：
圖 2 橫向看能力 圖 3 縱向看它在系統裏分成哪幾層
一個功能域可以跨多層，一層裏也可以裝下多個功能域。比如：
Skills在圖 2 裏是獨立功能域，但在圖 3 裏主要放在能力層，同時又會碰到上下文層和控制層系統提示詞、上下文裝配、記憶 / 壓縮在圖 2 裏分成 3 個域，但在圖 3 裏會一起放進上下文層權限 / 審批在圖 2 裏是一個產品能力，但在圖 3 裏會被收進控制層Subagent / Agent Team在圖 2 裏是獨立域，但在圖 3 裏主要放在能力層，同時依賴會話編排層和狀態層
如果把上面的 12 個域進一步壓縮，Claude Code 的底層結構其實可以歸成 7 層：
交互層 會話編排層 Loop Runtime 層 上下文層 能力層 控制層 演進層
這張圖要看兩件事。
第一，它不是“模型在最中間”，而是“任務主循環”在最中間。說明系統真正的核心不是模型本身，而是圍繞模型運轉的那套執行流程。
第二，上下文層、能力層、控制層 都在主循環外面給它提供材料、工具和邊界。這正是 harness engineering 的典型結構：模型只負責局部推理，系統負責把環境、能力和邊界擺好。
圖 4：啓動入口和運行方式，為什麼它不是一個單模式 CLI
Claude Code 的入口並不只有一條。
從 src/entrypoints/cli.tsx、src/main.tsx、src/init.ts、src/setup.ts 往下看，它從一開始就不是“命令行啓動一下 REPL”這麼簡單。
它至少同時支持幾種運行方式：
交互式終端 headless / SDK 調用 bridge / remote 控制 daemon / worker 異步執行
這張圖說明了一個很關鍵的產品判斷：
頂級 agent 產品不會把自己做成單入口玩具，而會把自己做成一個可嵌入、可託管、可異步、可遠程驅動的執行系統。
也正因為它把不同運行方式拆開設計，後面才能實現 subagent、後台任務、remote task 和 team 協作。
圖 5：主任務循環，Claude Code 的心跳到底怎麼跳
這張圖對應 src/query.ts 和 src/QueryEngine.ts。
它回答的是最核心的問題：
一條任務進入系統後，到底怎麼被一輪一輪推進。
這個主循環裏至少有 6 個關鍵動作：
準備有效 system prompt 和上下文 發起流式模型調用 接收 tool_use執行工具並寫回 tool_result決定繼續、壓縮、重試還是結束 把消息、usage、狀態寫回會話
Claude Code 這條主循環真正成熟的地方，是它把 streaming、retry、tool result、compaction、state update 都接成了一條穩定流程。也就是說，它解決的不是“能不能調工具”，而是“調完之後系統還能不能穩穩地繼續往下跑”。
圖 6：狀態與持久化，為什麼它能連續工作
如果一個 agent 產品只靠內存跑，如果出現異常情況，它就很難恢復。
Claude Code 在這塊通過狀態和持久化，解決了這個問題。
從 src/bootstrap/state.ts、src/state/AppStateStore.ts、src/utils/sessionStorage.ts、src/utils/tasks.ts 可以看到，它至少在管理這些狀態：
transcript usage tool permission context session storage tasks worktree 信息 project root / cwd memory 與 invoked skills
這層的意義是：
讓系統不是“每輪重新開始”，而是“帶着上輪狀態繼續工作”。
這對長任務、後台任務、subagent、resume、compact 後恢復，都是前提。
圖 7：上下文裝配，不是把材料一股腦塞進 prompt
Claude Code 的上下文設計非常講究。
它不是把所有材料拼成一段大文本，而是明確分成三類：
System Prompt：系統身份、規則、能力約束System Context：git 狀態、環境態、緩存相關上下文User Context：CLAUDE.md、日期、用戶級補充信息
src/context.ts 和 src/query.ts 很清楚地把這三類做了不同注入。
這張圖最值得注意的，是 CLAUDE.md 的位置。
它不是可有可無的說明文件，而是倉庫個性化定義信息的上下文。也就是說，Claude Code 從設計上就接受“用戶可以通過文檔參與 agent 行為的控制”。
這也是它為什麼比很多“單 prompt agent”更實用。因為真實工程知識，本來就散落在 repo 裏。
圖 8：System Prompt，不是一段文本，而是一套生成器
這是 Claude Code 最容易被低估的一層。
從 src/constants/prompts.ts、src/constants/systemPromptSections.ts、src/utils/systemPrompt.ts 到 API 發送前的 block 化處理，整條鏈路都說明了一件事：
System Prompt 在這裏是系統拼出來的結果，不是手寫好的一整段文本。
它大致經過三步：
getSystemPrompt()組裝默認 sectionsbuildEffectiveSystemPrompt()決定優先級buildSystemPromptBlocks()按緩存邊界切塊
這裏最重要的設計點有三個。
第一，提示詞是 string[]，不是一整段字符串。這樣才能分靜態區、動態區和緩存邊界。
第二，存在明確的優先級鏈：
Override > Coordinator > Agent > Custom > Default
這意味着 Claude Code 不是靠一條 prompt 打天下，而是允許不同運行方式拿到不同的內容。
第三，SYSTEM_PROMPT_DYNAMIC_BOUNDARY 這種分界標記非常關鍵。它把可全局緩存的靜態內容和每輪都變的動態內容切開，直接影響 prompt cache 命中率和成本。
這就是 harness engineering 和 prompt engineering 的差別。
前者研究的不是“怎麼寫一句厲害的話”，而是“怎麼把提示詞做成一個可緩存、可分層、可替換、可運行的系統”。
圖 9：記憶與壓縮，Claude Code 怎麼對抗長上下文衰減
agent 產品做長任務，一定會遇到兩個問題：
token 會爆 歷史會丟
Claude Code 在這塊的答案，不是簡單截斷，而是把 compact、memory、relevant recall、invoked skills 接成一套連續機制。
從 src/services/compact/*、src/memdir/*、bootstrap/state 看，至少有三層設計：
會話太長時，通過 compact 保留核心結論，不保留原始細節 重要知識寫入 memory 文件體系，而不是堆在當前輪上下文裏 對已經調用過的 skill 做顯式追蹤，壓縮後還能繼續知道“之前調過什麼”
這張圖說明的是：
Claude Code 把“長任務怎麼不中斷”當成核心問題。
所以它不是“儘量別聊太多”，而是“允許你聊很多，但系統會主動重排上下文”。這就是成熟 agent 的差異。
圖 10：工具與擴展，不是堆能力，而是先做統一接口
Claude Code 裏有很多能力來源：
內置 tools shell / file / git MCP tools skills plugin commands agents
但從 src/Tool.ts、src/tools.ts、src/commands.ts、src/services/mcp/client.ts 往下看，最終都被收成了兩種固定形式：
ToolCommand
這層統一非常重要。
因為一旦能力來源開始變多，系統真正難的就不是“接入一個新能力”，而是“怎麼讓新能力仍然進入同一條權限鏈、同一條提示詞鏈、同一條執行鏈”。
Claude Code 在這件事上是清醒的。它沒有把 MCP、skill、subagent 分別做成三套孤立系統，而是儘量把它們收進同一套運行規則裏。
這也是為什麼它擴展很多，但系統沒有散。
圖 11：Skills，不是提示詞菜單，而是工作流封裝層
很多人會把 skill 理解成“預設 prompt”。
這隻說對了一半。
在 Claude Code 裏，skill 至少同時承擔 5 個角色：
一個可發現的能力入口 一個可被模型匹配的工作流模板 一個帶 frontmatter 的配置說明 一個可 inline 或 fork 執行的系統命令 一個需要被系統認真管理的對象
從 docs/extensibility/skills.mdx、src/skills/loadSkillsDir.ts、src/tools/SkillTool/SkillTool.ts 往下看，skill 的完整鏈路是：
SKILL.md -> parseFrontmatter -> createSkillCommand -> 注入 System Prompt -> SkillTool.validateInput -> checkPermissions -> call
它最成熟的地方，不在“skill 能執行”，而在“skill 怎麼穩定、安全地執行”。
Claude Code 在這裏做了幾層保護：
allowedTools只是改變權限上下文，不直接繞過工具權限SAFE_SKILL_PROPERTIES是白名單，不認識的新屬性默認要求審批MCP skills被視為遠程來源，不允許本地 shell 內聯替換skill 可以走 inline，也可以走fork，長任務不污染主會話調用過的 skill 會被記錄進狀態，compact 後還能恢復連續性
這就是為什麼 skill 在 Claude Code 裏不是“錦上添花”，而是把工作流真正做成產品能力的關鍵一層。
圖 12：權限、審批、沙箱，真正的控制層在這裏
Claude Code 的安全設計，不能只看一個 permission 彈窗。
它實際是一套三層控制流程：
trust：當前環境和當前會話的信任前提permission：這個動作現在允不允許sandbox：就算允許，也只能在什麼邊界裏做
從 src/utils/permissions/*、src/utils/sandbox/*、interactiveHelpers.tsx 往下看，系統真正做的是：
在模型看到工具之前先裁剪工具池 在 tool use 前根據規則判斷 allow / deny / ask 在具體執行時再用 sandbox 卡住文件系統和命令邊界
也就是說，Claude Code 的做法不是“先放開，再兜底”，而是“暴露之前先過濾，執行之前再確認，落地時再限制”。
這才是產品級控制系統。
圖 13：Subagent，不是多開會話，而是一條規範的任務派發流程
很多產品做多代理，其實只是“開一個新對話”。
Claude Code 不是。
從 src/tools/AgentTool/AgentTool.tsx、forkSubagent.ts、runAgent.ts 往下看，subagent 至少被做成了一條很規範的執行流程：
解析 agent 類型或 fork 路徑 組裝獨立工具池 注入獨立 system prompt / prompt messages 必要時創建獨立 worktree 跑一套獨立的 agent 主循環 回傳結果、usage 和通知
它裏面有兩個特別強的設計。
第一，fork 和 named agent 是兩條不同路徑。前者強調繼承上下文和共享 prompt cache；後者強調獨立角色和獨立能力。
第二，subagent 不是單獨在外面跑，它仍然複用主系統的工具、權限、狀態和結果格式。這意味着多代理不是額外拼上去的功能，而是系統本身就支持的能力。
圖 14：Agent Team / Coordinator / Swarm，不是一種多代理，而是三種協作方式
Claude Code 在多代理上做得比很多項目更深。
它至少有三種組織方式：
Subagent：適合把一件事拆出去單獨做Coordinator + Worker：適合集中決策、分工執行Swarm / Team：適合多個並行任務自主認領
src/coordinator/coordinatorMode.ts 和任務系統代碼說明，Coordinator 模式的重點不是“更強模型”，而是角色約束。
Coordinator 自己不做髒活，它只負責：
理解任務 拆任務 派任務 接收 <task-notification>綜合結果
它甚至只保留少量調度工具，故意不讓自己直接寫代碼。這個設計很硬核，因為它強制系統把“理解”和“執行”分開。
Swarm 則是另一套邏輯。它依賴共享 task list、claimTask、mailbox 和 owner 機制，讓多個 teammate 去搶佔和完成任務。這更像一個輕量級任務操作系統，而不是簡單併發。
所以別把“agent team”理解成幾個 agent 一起跑。
在 Claude Code 裏，它已經開始接近組織設計問題了。
圖 15：測試、遙測、Feature Flags，Claude Code 為什麼能一直演進
最後這一層，往往最容易被忽略。
但恰恰是這一層，決定一個 agent 產品能不能從“這周能跑”變成“長期可維護”。
Claude Code 在這塊至少有三條持續改進的機制：
tests：驗證系統行為有沒有回退telemetry：看真實使用裏發生了什麼feature flags / GrowthBook：讓新能力先小範圍試運行，再決定是否放開
docs/testing-spec.md、docs/internals/feature-flags.mdx、docs/internals/growthbook-ab-testing.mdx 和 src/services/analytics/growthbook.ts 一起說明，Claude Code 不是先改代碼再祈禱，而是在真實運行裏持續觀察、持續試驗、持續改進。
這也是 harness engineering 最容易被忽視，但實際上很重要的一層。
因為前面的主循環、skills、subagent、sandbox 都會不斷變化。沒有這層反饋機制，系統只會越來越脆弱。
最後收一下：Claude Code 真正值得學的，是完整性
如果只看某一塊，Claude Code 並不神秘。
它的很多單點設計，你都能在別的 agent 項目裏找到影子：tool use、memory、subagent、skill、MCP、sandbox、feature flag。
真正讓它拉開差距的，是這些東西都被接進了一套完整系統裏。
它不是把能力往模型身上堆。
它是把模型放進一個成熟的工作系統裏：
有入口 有主循環 有上下文裝配 有 prompt 生成器 有統一的工具接口層 有 skill 的執行機制 有權限控制系統 有 subagent 和 team 協作 有測試和遙測反饋機制
這才是頂級 harness engineering agent 產品真正的樣子。
它不是“更會聊天”。
它是“更像一個能工作的系統”。
我也在開發一個類似的開源企業桌面智能體產品workclaw(https://github.com/haojing8312/workclaw)，介紹如下：
https://my.feishu.cn/wiki/O62Pwtb94ikFEJkYHuEcxaWanQb
名詞解釋
Harness Engineering：駕馭工程，不是研究模型怎麼回答，而是研究怎麼把模型變成一個能長期工作的產品系統。Runtime：可以理解成“系統真正幹活的那一層”。任務會在裏面流轉、執行、重試、結束。REPL：終端裏那種你輸一句、系統回一句、還能繼續接着輸的交互殼。System Prompt：給系統設定身份、規則、邊界的頂層說明書。在 Claude Code 裏它是動態生成的，不是固定一段話。Prompt Cache：提示詞緩存。前面的上下文如果不變，就不必每次都重新算錢、重新算 token。MCP：給 agent 接外部能力的一套標準協議。你可以把它理解成 agent 的標準擴展插槽。Skill：把一套工作流經驗封裝成一個可執行能力，不只是提示詞模板。Sandbox：沙箱。就算系統允許執行，也只能在限定邊界內動文件、跑命令。Subagent：被主 agent 派出去處理子任務的代理，相當於一個可控的臨時外包工位。Coordinator：總調度。自己儘量不下場幹活，主要負責拆任務、派任務、收結果。Swarm / Agent Team：多代理協作形態。前者更像分佈式搶任務，後者更像有組織的項目組。Worktree：Git 的獨立工作副本。可以理解成“同一個倉庫臨時開一個隔離工位”，方便子代理安全試改。