用 Claude Code 做過真實項目的朋友應該都有同感在單步聊天模式下你每提一個需求它給你一段修改你再去檢查、再提下一個需求一來一回像擠牙膏。我最早也這么用項目一復雜就發(fā)現(xiàn)了兩個問題一是上下文里堆滿了歷史對話模型越往后越糊涂二是同樣的錯誤反復犯改完 A 文件又把 B 文件搞壞了。后來我把工作方式切換成多 Agent 編排、閉環(huán)自愈加 Routine 腳本化的結(jié)構(gòu)效率提升非常明顯。這篇文章就把這套架構(gòu)拆開講透Claude Code 里的多 Agent 怎么協(xié)作、閉環(huán)自愈self-healing loop到底怎么轉(zhuǎn)、Routine 腳本化如何把高頻動作固化成流程以及落地時環(huán)境該怎么配。適合那些已經(jīng)開始用命令行編程工具、但還停留在單步聊天階段的開發(fā)者也適合想把這套工具真正接入自己工作流的團隊。1. 單步聊天的效率黑洞為什么一問一答撐不住真實項目1.1 從幫我想到幫我做Agent 化的本質(zhì)區(qū)別單步聊天本質(zhì)上就是你出題它做題你把需求寫成一個 prompt模型生成一段代碼或者改幾個文件然后你人肉去 review。這個模式在小需求上沒毛病但真實項目通常橫跨十幾個文件牽扯數(shù)據(jù)庫遷移、依賴升級、測試適配單靠一輪對話根本裝不下。一次給太多需求模型會面面俱到但處處不深改到后面忘了前面的約束。Agent 化之后工具不再被動等你下一條指令而是拿到一個目標后自己拆解、自己執(zhí)行、自己檢查。Claude Code 這類 CLI 工具內(nèi)置了文件讀寫、終端命令執(zhí)行、代碼搜索等能力這就給了模型動手的條件。兩者的區(qū)別就像你雇了一個只會回答問題的顧問和一個能自己跑現(xiàn)場、出方案、落地施工的包工頭。顧問再聰明也得你一條條安排才動一下包工頭你只要告訴他交付目標他自己會安排進度和檢查質(zhì)量。1.2 單步模式的三個致命問題我自己的體會是單步模式在真實項目里至少有三個繞不開的坑上下文漂移context drift對話越長早期的重要約束比如不要動公共接口保持向后兼容越容易被稀釋模型只盯著最近的對話導致反復破壞已經(jīng)約定好的東西。缺少自動驗證單步模式下沒有裁判改完代碼不知道測試是否通過、類型是否報錯只能靠人肉眼檢查效率低而且漏檢率高。重復勞動跑 lint、跑測試、改版本號、寫 changelog這些操作每次都要重新描述一遍prompt 越寫越長浪費 token而且描述不一致時結(jié)果還不穩(wěn)定。這三個問題剛好對應后面要展開的三根支柱多 Agent 編排解決上下文漂移閉環(huán)自愈解決缺少自動驗證Routine 腳本化解決重復勞動。我整理了一張對照表方便理解單步模式的痛點對應解法核心思路上下文漂移多 Agent 編排任務拆細、上下文隔離、主控只保留摘要缺少自動驗證閉環(huán)自愈執(zhí)行后自動跑測試失敗就循環(huán)修復重復勞動Routine 腳本化把固定操作步驟固化成可復用流程2. 多 Agent 編排原理主控分解、子 Agent 執(zhí)行與上下文隔離2.1 主控 Agent 與子 Agent 的分工模型Claude Code 的編排模型通俗講就是一個項目經(jīng)理帶一堆專業(yè)工長。主控 Agentprimary agent負責接收你的目標、做總體規(guī)劃、把大任務拆成小任務、分配資源和檢查結(jié)果。子 Agentsubagent帶著非常窄的職責和獨立的上下文去執(zhí)行某個子任務。這么做最核心的收益是上下文隔離子 Agent 不需要知道整個項目的來龍去脈只需要知道自己的子任務和相關(guān)的幾個文件。模型在窄上下文里的表現(xiàn)會明顯好于在混亂長上下文里的表現(xiàn)這是個被大量實測驗證過的結(jié)論。主控 Agent 反而因為只保留任務清單加階段性結(jié)果摘要而不會超載。我在實際項目里經(jīng)常遇到這種情況一個需求讓單個 Agent 直接做它做到第三個文件就開始犯迷糊同樣的需求拆成三個子 Agent 分頭做每個子 Agent 只盯著自己的文件完成度明顯更高。2.2 任務分解與依賴關(guān)系處理實操中拆任務的原則是按文件邊界拆、按功能垂直切、把有依賴的任務串行、把無依賴的任務并行。比如一個給訂單模塊加導出功能的需求可以拆成接口層、服務層、頁面層、測試四個子任務。接口層和服務層有強依賴必須串行頁面層和測試可以在接口定義好之后并行。我常用的辦法是先讓主控 Agent 輸出一份任務拓撲內(nèi)容包括子任務列表、每個任務的輸入輸出、依賴關(guān)系、驗收條件。這一步看著費時間實際上能避免后期大量返工尤其是跨文件改動多的需求。有一次接了個重構(gòu)需求我偷懶沒做任務拓撲直接讓 Agent 干結(jié)果它改了六個文件三個互相沖突回滾花了比寫代碼更長的時間。從那以后我老老實實先做拓撲。2.3 上下文隔離的工程意義很多人會在單步聊天里遇到越改越亂本質(zhì)就是上下文里塞了太多不相關(guān)的東西。多 Agent 編排把記憶切成小塊每個子 Agent 只拿著一小塊記憶干活干完把結(jié)果壓縮成一個摘要交還給主控。這個模式非常像人類團隊沒人需要記住全公司所有細節(jié)每個人只需要知道自己的事開會時匯報結(jié)論就行。另外一個容易被忽略的點是子 Agent 的職責定義越窄越容易寫出符合預期的代碼。我在配置里給不同類別的任務定義了不同風格的子 Agent比如重構(gòu)型、寫測試型、修 bug 型各自有不同的行為約束。修 bug 型的子 Agent 會被明確要求先讀錯誤信息、再定位根因、最后才動手改重構(gòu)型的則被要求保持行為不變只調(diào)整結(jié)構(gòu)。這個細節(jié)后面講 Routine 的時候還會展開。3. 閉環(huán)自愈機制從報錯到自動修復的驗證回路3.1 自愈閉環(huán)的四步執(zhí)行、檢測、修復、驗證閉環(huán)自愈是這套架構(gòu)里價值最大、也最容易被忽略的一環(huán)。核心思想是Agent 執(zhí)行完修改之后不能直接說完成必須自己運行驗證命令發(fā)現(xiàn)失敗就循環(huán)修復直到通過為止。具體流程分四步執(zhí)行Agent 完成代碼修改。檢測立即運行對應的測試或構(gòu)建命令拿到機器可讀的通過/失敗結(jié)果。修復如果失敗把完整的錯誤信息喂回模型讓它分析根因、再做修改。驗證改完再跑檢測循環(huán)往復。這個循環(huán)的次數(shù)上限要提前設定我一般設 5 輪防止無限轉(zhuǎn)圈。每輪都會消耗模型調(diào)用自愈不是免費的后面講成本控制的時候會細說。3.2 用測試作為裁判自愈閉環(huán)里最關(guān)鍵的是裁判要可靠最可靠的裁判就是測試。所以我在讓 Claude Code 改業(yè)務代碼之前會先讓它把測試寫出來或者確認已有測試覆蓋然后再改實現(xiàn)讓實現(xiàn)去追測試。這其實就是 TDD 的流程只不過執(zhí)行者從人變成了 Agent。沒有測試的項目很難做自愈——Agent 改完代碼你拿什么判斷它對不對靠肉眼 review 不叫閉環(huán)閉環(huán)必須有客觀的驗證信號。所以自愈架構(gòu)的第一個前置條件就是測試覆蓋率哪怕先補冒煙測試也要讓通過/失敗變成一個可被機器讀取的結(jié)果。提示如果項目完全沒有測試我的建議是先別急著開自愈花半天把核心路徑的測試補上。沒有裁判的循環(huán)本質(zhì)上是讓模型自說自話。3.3 自愈失敗的降級策略與人工介入自愈不是銀彈很多時候修了幾輪還是紅。這時候最怕的是 Agent 為了通過而作弊比如把測試刪了、把斷言改弱、繞過失敗分支。我踩過的坑是它把斷言從等于預期值改成不為空測試綠了但功能是壞的。所以要在閉環(huán)里加兩條硬規(guī)則一是禁止修改測試來迎合實現(xiàn)除非經(jīng)過確認這是測試本身寫錯了二是連續(xù)三輪修復失敗后停止自愈把失敗現(xiàn)場、嘗試過的方案、錯誤日志打包輸出交給人來判斷。寧可停下來叫人也不要讓 Agent 硬撐。從成本和結(jié)果兩個維度看硬撐都是最差的選擇。4. Routine 腳本化把高頻操作固化成可復用項目流程4.1 什么是 Routine把提示詞變成流程Routine 腳本化解決的是重復勞動。Claude Code 支持把一整套操作流程固化成可復用腳本你輸入一個簡短的命令它就會按預設的步驟執(zhí)行一系列操作。這有點像是給模型寫工作流程說明書把那些每次都要講一遍的環(huán)節(jié)標準化。典型的應用場景包括新分支開發(fā)前的環(huán)境檢查、發(fā)布前的變更檢查、依賴升級后的回歸測試、代碼風格統(tǒng)一。這些流程步驟固定、判斷標準固定非常適合腳本化。我自己用下來的體感是一段流程只要我手動執(zhí)行過三次以上就值得把它固化成 Routine省下的不只是時間還有每次描述不一致帶來的結(jié)果波動。4.2 CLAUDE.md項目級長期記憶與規(guī)則CLAUDE.md 是 Claude Code 的項目記憶文件相當于給每個項目的 Agent 發(fā)一本員工手冊。里面可以寫項目結(jié)構(gòu)說明、技術(shù)棧約定、禁止事項、常用命令、測試運行方式、代碼風格。Agent 每次啟動都會讀取這個文件相當于入職培訓。我的 CLAUDE.md 里一定會寫這幾件事如何運行測試精確到命令、構(gòu)建產(chǎn)物的位置、不可改動的核心文件列表、提交信息的格式要求。寫清楚這些后續(xù)所有 Agent 的工作質(zhì)量都會明顯提升因為它們是帶著規(guī)則干活不是憑感覺干活。4.3 Hooks 與自定義命令在關(guān)鍵節(jié)點自動觸發(fā)Hooks 是比 CLAUDE.md 更進一步的能力它在特定事件發(fā)生時自動執(zhí)行腳本比如在 Agent 每次修改文件后跑一次 lint在每次對話開始前檢查分支狀態(tài)。這些自動觸發(fā)的動作可以把很多低級錯誤擋在發(fā)生之前不需要你每次手動提醒。自定義命令則把流程打包成菜單項。比如我定義了發(fā)布檢查命令它會依次執(zhí)行跑全量測試、檢查 TODO/FIXME 殘留、核對版本號與 changelog、確認依賴無安全告警。一條命令觸發(fā)一串動作比手動一條條輸入高效太多。這套組合下來日常開發(fā)里真正需要我手動打字的部分其實很少。4.4 腳本化組合實戰(zhàn)一個發(fā)布前檢查的例子拿發(fā)布前檢查舉例我把流程拆成四段寫進 Routine1. 跑全量測試收集輸出失敗則列出失敗用例和錯誤堆棧 2. 掃描代碼中的調(diào)試殘留console.log、debugger、臨時注釋 3. 對比版本號文件與最近提交記錄確認版本是否更新 4. 匯總以上結(jié)果輸出一份檢查報告標注每個環(huán)節(jié)的通過狀態(tài)每段都有明確的成功標準和失敗處理方式Agent 不需要頻繁問我下一步做什么。以前我發(fā)布前要花 20 分鐘做檢查現(xiàn)在一條命令交給 Agent它自己跑完所有步驟并報告結(jié)果省下來的時間足夠我再 review 一輪核心改動。這個例子看起來簡單但實際效果很驚人尤其是發(fā)布節(jié)奏比較快的時候它幾乎是保命級別的工具。5. 落地環(huán)境配置Ubuntu/macOS 安裝、VS Code 集成與模型接入5.1 安裝與初始化Claude Code 以 CLI 工具形式分發(fā)安裝方式取決于平臺。macOS 上通?？梢灾苯佑冒芾砥靼惭bUbuntu 等 Linux 發(fā)行版可以通過官方提供的安裝腳本或 npm 方式安裝。裝完在終端輸入claude即可進入交互式會話首次使用需要登錄賬號完成授權(quán)之后會生成本地的認證配置。裝完之后建議立刻做兩件事第一確認版本并留意升級claude命令自帶在線升級機制定期更新能拿到最新的編排和自愈能力第二在項目根目錄創(chuàng)建 CLAUDE.md把項目規(guī)則寫進去。初始化質(zhì)量直接決定后續(xù) Agent 表現(xiàn)的上限。習慣圖形界面的朋友也可以留意官方桌面版入口本質(zhì)上還是同一套核心只是在交互上有差別。# macOS 示例通過包管理器安裝 brew install claude-code # Ubuntu 示例通過 npm 安裝 npm install -g anthropic-ai/claude-code5.2 VS Code 集成很多開發(fā)者不習慣純終端操作Claude Code 提供 VS Code 插件Claude Code for VS Code裝好后可以在編輯器里直接喚起會話。插件的好處是能看到文件樹和 diff改動了什么一目了然review 成本低很多。VS Code 集成后我的習慣是讓 Agent 負責生成與修改我負責 diff review 和合并。插件配置上需要注意幾點確認工作區(qū)路徑正確、設置好默認終端、根據(jù)項目情況調(diào)整權(quán)限比如是否允許 Agent 自動執(zhí)行終端命令。權(quán)限開得太大有風險開得太小 Agent 又跑不動需要按項目風險平衡。我在個人項目里會放開權(quán)限在公司核心倉庫里則會把命令執(zhí)行改成每次詢問。5.3 第三方模型接入切換 API 供應商Claude Code 默認綁定 Anthropic 官方模型服務但通過環(huán)境變量可以指定其他兼容 API 的模型供應商比如 DeepSeek、通義千問 Qwen、智譜 GLM 這類做法是設置 API 地址和密鑰兩個環(huán)境變量后啟動工具。這樣相當于讓 Claude Code 繼續(xù)承擔編排和執(zhí)行的框架職責而模型的推理決策交給所選供應商。社區(qū)里常見的做法是用 cc-switch 這類開源配置切換工具管理多套 API 配置它會幫你保存不同供應商的地址和密鑰組合切換時一條命令搞定省去反復修改環(huán)境變量的麻煩。手動配置時大致是下面這個形態(tài)export ANTHROPIC_BASE_URL你的供應商API地址 export ANTHROPIC_API_KEY你的API密鑰 claude需要提醒的是不同模型在工具調(diào)用能力、指令遵循能力上有明顯差異。多 Agent 編排和閉環(huán)自愈這套玩法依賴模型按規(guī)則執(zhí)行、不跑偏在較弱的模型上效果會打折扣。接入第三方模型后建議先從簡單任務開始驗證別一上來就跑全量的多 Agent 并行編排。6. 實測避坑清單編排沖突、自愈死循環(huán)與成本失控的應對6.1 主控的甩鍋子 Agent 結(jié)果沖突多 Agent 編排最常見的問題是子 Agent 各自改文件改完合并時互相打架。兩個子 Agent 同時改了同一個公共文件的相鄰區(qū)域主控卻沒發(fā)現(xiàn)合并后直接編譯不過。我的應對辦法是給并行任務劃定嚴格的文件邊界禁止兩個并行子 Agent 寫同一個文件同時讓主控在合并后強制跑一遍編譯或測試用機器信號兜底。6.2 自愈死循環(huán)越修越壞自愈循環(huán)的另一個常見坑是模型在錯誤信息里打轉(zhuǎn)它反復嘗試同一種失敗方案只是換換參數(shù)。原因是它沒有真正理解根因只是在隨機震蕩。我遇到過一個類型錯誤它連續(xù)四輪都在改 import 路徑其實問題是泛型參數(shù)沒傳對。后來我加了規(guī)則修復前必須先輸出一段根因分析把為什么會報這個錯寫清楚再動手。寫不清楚就說明模型自己也沒搞明白這時候要把循環(huán)停下來別讓它繼續(xù)浪費調(diào)用。注意自愈循環(huán)不是越多次越好。我實測大部分問題 2 到 3 輪能解決超過 5 輪再修下去大概率是在浪費時間而且越改越亂的風險會快速上升。6.3 上下文與成本控制多 Agent 加自愈最容易被忽視的副作用是 token 消耗。每一輪自愈都是完整的一輪模型調(diào)用失敗越多次成本越高?？刂瞥杀镜慕?jīng)驗是限制子 Agent 數(shù)量不是越多越好給自愈設置輪次上限把大任務拆成多次會話而不是一次全塞進去。我自己的項目里閉環(huán)自愈的輪次上限設成 5子 Agent 的并行數(shù)量一般不超過 3 個。這個數(shù)字沒有標準答案需要根據(jù)任務復雜度和模型能力來調(diào)但原則是一致的用最小的編排規(guī)模完成任務能用 Routine 固化的就不要再讓模型從頭思考。6.4 一點實踐心得最后分享一個組合使用的順序先用 Routine 把怎么跑測試、怎么檢查、怎么發(fā)布固化下來再用多 Agent 編排把誰做什么分清楚最后才是開自愈。這三者是有依賴關(guān)系的——如果你連驗證命令都沒標準化自愈就沒有裁判如果任務沒拆分Agent 就會陷入單步聊天時的上下文泥潭。我現(xiàn)在的日常開發(fā)流是改需求前先讓主控 Agent 出任務拓撲每個子 Agent 開工前自動跑 Routine 里的環(huán)境檢查改完代碼進入自愈閉環(huán)測試通過后我再做一輪 diff review。這套流程用了快半年最直觀的變化是重復性返工少了發(fā)布前的手工檢查時間砍掉大半。它不復雜難的是把每一步的規(guī)則想清楚寫下來剩下的交給編排和自愈去跑。