戰(zhàn)：從聊天框到多Agent編排與自愈流水線)
Claude Code 發(fā)布之后很多人的第一反應(yīng)是把它當(dāng)成終端里的 ChatGPT貼一段報(bào)錯(cuò)問一句“怎么改”復(fù)制答案再貼下一段。我見過的最常見用法就是這樣一問一答單步推進(jìn)。這種用法不能說完全沒用但它恰好浪費(fèi)了 Claude Code 最值錢的部分——它不是一個(gè)聊天框而是一個(gè)跑在終端里的 Agent 運(yùn)行時(shí)。它真正的價(jià)值在于能自己規(guī)劃任務(wù)、自己調(diào)用工具、自己驗(yàn)證結(jié)果甚至在自己出錯(cuò)之后自己爬起來修好自己。這一篇我準(zhǔn)備分四條線把 Claude Code 講透多 Agent 編排怎么把單線程對話變成多角色并行作戰(zhàn)閉環(huán)自愈怎么讓 Agent 在測試失敗時(shí)自動(dòng)修復(fù)直到全綠Routine 腳本化怎么把重復(fù)勞動(dòng)固化成一碰就能跑的流水線最后結(jié)合很多人都關(guān)心的安裝、IDE 接入和第三方模型接入DeepSeek、Qwen、GLM 這類講一下落地細(xì)節(jié)。目標(biāo)只有一個(gè)把它從“高級(jí)問答工具”升級(jí)成真正能交付結(jié)果的“自動(dòng)化工程師”。1. 單步聊天的瓶頸為什么Claude Code不該被當(dāng)成聊天框用1.1 聊天框工作流的三個(gè)死穴先把話說透單步聊天模式在簡單小問題上確實(shí)有效但一旦進(jìn)入真實(shí)工程立刻會(huì)暴露三個(gè)致命問題。第一個(gè)是上下文斷裂。你問完一個(gè)問題得到一段代碼復(fù)制進(jìn)編輯器跑一下報(bào)錯(cuò)再把新報(bào)錯(cuò)貼回去。每一輪都意味著大量的上下文重傳項(xiàng)目的重要背景、之前的結(jié)論、已經(jīng)改過的文件統(tǒng)統(tǒng)需要重復(fù)描述。任務(wù)稍微復(fù)雜一點(diǎn)人和 Agent 都會(huì)迷失在“剛才說到哪了”的混亂里。第二個(gè)是反饋回路缺失。聊天框只能輸出建議不能真的動(dòng)手。它說“把這兩個(gè)函數(shù)抽出來”你改完發(fā)現(xiàn)單測掛了再貼給它看它再給建議你再去改。這個(gè)循環(huán)里真正干活的是人Agent 只是在旁邊當(dāng)參謀。而 Claude Code 不是這樣——它能自己運(yùn)行測試、自己讀報(bào)錯(cuò)、自己改代碼形成完整的行動(dòng)-反饋-修正閉環(huán)。第三個(gè)是經(jīng)驗(yàn)無法沉淀。聊天記錄關(guān)掉就沒了同一個(gè)項(xiàng)目的“提交前檢查流程”下次還得從頭再聊一遍。你從一次問答里得到的只有一段代碼不是一個(gè)可以復(fù)用的工作流程。長此以往工具使用效率始終停留在第一周的水平。1.2 Claude Code的真實(shí)身份終端里的Agent運(yùn)行時(shí)我們得先糾正一個(gè)認(rèn)知Claude Code 和網(wǎng)頁聊天最大的區(qū)別不在于界面而在于“它擁有執(zhí)行權(quán)限”。Claude Code 底層是圍繞工具調(diào)用Tool Use設(shè)計(jì)的 Agent。它手里有一整套工具讀文件、寫文件、執(zhí)行 Shell 命令、運(yùn)行測試、搜索代碼、編輯代碼片段。當(dāng)它接到一個(gè)任務(wù)時(shí)它會(huì)自己做規(guī)劃然后反復(fù)調(diào)用這些工具去驗(yàn)證自己的想法。這意味著它能直接在你的倉庫里動(dòng)代碼、跑出真實(shí)的測試結(jié)果再根據(jù)結(jié)果調(diào)整策略。這看起來只是一個(gè)工程細(xì)節(jié)實(shí)際影響卻是革命性的。網(wǎng)頁聊天里的代碼永遠(yuǎn)只是“建議”你需要手動(dòng)搬運(yùn)Claude Code 里的代碼是“實(shí)施”它會(huì)自己改完自己跑測試。這個(gè)差異決定了它能接手的任務(wù)復(fù)雜度上限完全不同。我還想強(qiáng)調(diào)一個(gè)容易被忽略的點(diǎn)Claude Code 有主 Agent 和子 AgentSubagent的層級(jí)設(shè)計(jì)主 Agent 負(fù)責(zé)拆解目標(biāo)和匯總結(jié)果子 Agent 負(fù)責(zé)具體執(zhí)行。加上 hooks鉤子機(jī)制可以在工具調(diào)用的生命周期里注入你自己的邏輯它天生就是為“可編排、可自愈、可固化”設(shè)計(jì)的。如果你只用它來一問一答等于開著一輛賽車在小區(qū)里遛彎。2. 多Agent編排從一問一答到多角色并行作戰(zhàn)2.1 主Agent與SubagentClaude Code天然就是多Agent架構(gòu)很多人不知道Claude Code 內(nèi)部本身就是一個(gè)多 Agent 架構(gòu)而不是單個(gè)模型死磕到底。主 AgentPrimary Agent負(fù)責(zé)理解你的目標(biāo)、拆解任務(wù)、決定調(diào)用哪些工具、以及把子任務(wù)的產(chǎn)出合并成最終答案。當(dāng)它遇到可以并行或需要專門處理的子問題時(shí)會(huì)通過 Task 工具派發(fā)一個(gè) Subagent。每個(gè) Subagent 都有自己的角色定義、自己的上下文窗口、自己的任務(wù)說明。子 Agent 跑完回來后把結(jié)論交給主 Agent 匯總。這種設(shè)計(jì)最直接的好處是上下文隔離。假設(shè)一個(gè)重構(gòu)任務(wù)涉及前端組件、后端接口、測試用例三塊如果只有一個(gè) Agent 處理它會(huì)帶著全部上下文來回切換很快就把注意力耗散在不同的代碼區(qū)域里。拆成三個(gè) Subagent 后每個(gè)子 Agent 只需要加載自己負(fù)責(zé)的那部分內(nèi)容精力集中出錯(cuò)率低還可以并行推進(jìn)。在項(xiàng)目里你可以通過.claude/agents/目錄來定義自己的專屬 Subagent。比如我想讓一個(gè)專門做代碼審查的 Agent 幫我挑毛病我就寫一個(gè)reviewer.md# 文件名.claude/agents/reviewer.md 你是資深代碼審查員具有 10 年工程實(shí)踐經(jīng)驗(yàn)。你的工作原則 - 只審查不修改發(fā)現(xiàn)問題必須清楚指出代碼位置和修改建議 - 重點(diǎn)防范安全漏洞、性能隱患、可維護(hù)性三類問題 - 輸出時(shí)按嚴(yán)重程度排序先列 P0 阻斷性問題再列優(yōu)化建議 - 不空談理論每一條意見都要能落地主 Agent 需要審查時(shí)會(huì)把這個(gè) Subagent 拉進(jìn)子任務(wù)里讓 review 專注于挑刺而主 Agent 自己專注在“怎么改”的決策上。這就是多 Agent 編排的價(jià)值不同角色負(fù)責(zé)不同職責(zé)而不是一個(gè) Agent 又想寫代碼又想批評(píng)自己——自己審自己的代碼審出來的問題通常都很淺。2.2 三種編排模式串行流水線、扇出聚合與多角色會(huì)商實(shí)際用下來我把多 Agent 編排總結(jié)為三種模式它們對應(yīng)不同場景大家可以按需選用。第一種是串行流水線。上游 Agent 的產(chǎn)出是下游 Agent 的輸入適合有明確依賴關(guān)系的鏈路。比如代碼生成 Agent 先產(chǎn)出新模塊測試 Agent 再對模塊補(bǔ)測試文檔 Agent 最后同步更新文檔。每一環(huán)節(jié)的上下文都限定在本環(huán)節(jié)內(nèi)邏輯清晰好排查。第二種是扇出聚合。主 Agent 把一個(gè)任務(wù)拆成 N 個(gè)獨(dú)立的子任務(wù)同時(shí)派出多個(gè) Subagent 并行執(zhí)行最后把結(jié)果收回來合并。適合大量獨(dú)立文件的批量處理比如多文件重構(gòu)、多目錄掃描。我記得有一次處理一個(gè)倉庫的大規(guī)模命名規(guī)范調(diào)整拆成 6 個(gè) Subagent 并行跑總共用了不到三分鐘換成單 Agent 串行至少得翻三倍時(shí)間。第三種是多角色會(huì)商。開發(fā) Agent 產(chǎn)出代碼審查 Agent 輸出問題清單主 Agent 再綜合兩邊意見做決策。這特別適合“既要快又要穩(wěn)”的場景相當(dāng)于在團(tuán)隊(duì)里強(qiáng)行塞進(jìn)了一個(gè)獨(dú)立評(píng)審角色。我簡單放一個(gè)對比表方便大家在方案設(shè)計(jì)時(shí)快速做選擇編排模式適用場景優(yōu)勢主要風(fēng)險(xiǎn)串行流水線有明確上下游依賴的流程職責(zé)清晰結(jié)果可控單環(huán)節(jié)失敗會(huì)阻塞整條鏈路扇出聚合批量獨(dú)立任務(wù)并發(fā)提速明顯結(jié)果合并需要主 Agent 做歸納多角色會(huì)商寫碼加審查的組合質(zhì)量兜底強(qiáng)消耗 token 更多決策鏈路變長2.3 編排粒度與上下文管理的權(quán)衡關(guān)于多 Agent 編排我必須提醒一句不是拆得越細(xì)越好。Subagent 雖然能隔離上下文但隔離也意味著信息壁壘。子 Agent 之間不能直接對話所有跨子任務(wù)的信息都必須經(jīng)過主 Agent 中轉(zhuǎn)。如果你把一個(gè)本來很簡單的任務(wù)拆成七八個(gè)子任務(wù)主 Agent 會(huì)花大量精力在“傳遞上下文”和“合并結(jié)論”上反而得不償失。我自己的經(jīng)驗(yàn)是一個(gè)子任務(wù)拆分的邊界應(yīng)該是“它能否獨(dú)立完成驗(yàn)證”。如果這個(gè)子任務(wù)跑完能自己給出確定性的結(jié)果——比如“Lint 通過”“測試全綠”“文件已生成”那它就值得拆出去。如果它必須依賴另一個(gè)子任務(wù)的結(jié)果才能繼續(xù)那它更適合作為串行鏈路中的一環(huán)而不是獨(dú)立 Subagent。還有一點(diǎn)Subagent 的上下文通常比主 Agent 更小。越是復(fù)雜的上下文越應(yīng)該留在主 Agent 里把具體的、局部的、機(jī)械性的操作推給 Subagent。這就像搞工程項(xiàng)目經(jīng)理應(yīng)該掌握全局而水電工只需要管好自己那面墻。3. 閉環(huán)自愈讓Agent在報(bào)錯(cuò)之后自己爬起來3.1 hook機(jī)制把自動(dòng)反饋裝進(jìn)工具調(diào)用生命周期閉環(huán)自愈核心就一句話Agent 錯(cuò)了能自己知道然后自己修復(fù)、自己驗(yàn)證直到滿意。Claude Code 實(shí)現(xiàn)這一步的關(guān)鍵是 hooks 機(jī)制。hooks 可以理解成一組“監(jiān)聽器”。Claude Code 在工具調(diào)用的各個(gè)階段都會(huì)觸發(fā)特定事件你可以在這些事件上掛自己的腳本注入額外的邏輯。常見的有幾類PreToolUse工具執(zhí)行前觸發(fā)、PostToolUse工具執(zhí)行后觸發(fā)、NotificationClaude Code 需要發(fā)送通知時(shí)觸發(fā)、UserPromptSubmit用戶提交 prompt 時(shí)觸發(fā)、StopAgent 完成一輪回答后觸發(fā)。真正構(gòu)成自愈閉環(huán)的是PostToolUse和Notification的組合。舉個(gè)例子我想讓 Claude Code 在跑測試失敗后自動(dòng)進(jìn)入修復(fù)模式可以在項(xiàng)目根目錄的.claude/settings.json里配一個(gè) hook{ hooks: { PostToolUse: [ { matcher: Bash, hooks: [ { type: command, command: python3 .claude/scripts/auto_repair.py } ] } ] } }這段配置的意思是每次 Claude Code 執(zhí)行完 Bash 工具后自動(dòng)運(yùn)行auto_repair.py。腳本會(huì)讀取 hook 傳入的 JSON里面包含剛執(zhí)行的命令、返回碼、輸出摘要如果發(fā)現(xiàn)命令是測試命令且返回碼非零就把“測試失敗”作為一條明確指令追加到當(dāng)前會(huì)話的上下文里讓 Agent 知道需要修復(fù)并重新運(yùn)行。3.2 一個(gè)測試失敗自動(dòng)修復(fù)的自愈循環(huán)實(shí)例這里我寫一個(gè)簡化版的自動(dòng)修復(fù)腳本邏輯方便理解整套閉環(huán)是怎么轉(zhuǎn)起來的# .claude/scripts/auto_repair.py import json, sys data json.load(sys.stdin) tool_name data.get(tool_name, ) command data.get(tool_input, {}).get(command, ) exit_code data.get(tool_response, {}).get(exit_code, 0) stderr data.get(tool_response, {}).get(stderr, )[-2000:] # 只對測試類命令生效 if tool_name ! Bash or pytest not in command and npm test not in command: sys.exit(0) if exit_code ! 0: # 通過標(biāo)準(zhǔn)輸出向 Claude Code 注入修復(fù)指令 print( 測試命令返回了非零退出碼。請立即分析上述錯(cuò)誤定位失敗的用例 修復(fù)對應(yīng)源碼后重新運(yùn)行相同的測試命令直到測試全部通過。 f最近錯(cuò)誤{stderr} )這個(gè)腳本的邏輯很直接監(jiān)聽到測試失敗就把失敗信息和修復(fù)指令打包成一段 prompt 塞回對話流。Claude Code 收到這段指令后會(huì)自己去查代碼、改代碼、重新跑測試。如果又失敗hook 再次觸發(fā)再次注入修復(fù)指令。循環(huán)往復(fù)直到通過或者達(dá)到某個(gè)終止條件。這樣構(gòu)建出來的閉環(huán)本質(zhì)上是把“人肉搬運(yùn)報(bào)錯(cuò)信息”這個(gè)環(huán)節(jié)省掉了。效果很明顯——以前測試掛了你要復(fù)制報(bào)錯(cuò)、貼給 Agent、等答案、復(fù)制修改、再跑測試。現(xiàn)在測試掛了Agent 自己就能跳起來處理。3.3 自愈的邊界什么時(shí)候要人為介入閉環(huán)自愈不是萬能的它有非常明確的適用邊界。我在實(shí)際項(xiàng)目中給自愈循環(huán)設(shè)了嚴(yán)格的“護(hù)欄”否則它會(huì)變成一個(gè)吞 token 的無底洞。第一個(gè)護(hù)欄是輪數(shù)限制。我會(huì)在 prompt 里明確告訴 Agent“如果連續(xù)修復(fù) 3 輪測試仍未通過停止并報(bào)告等待人工決策?！睕]有這個(gè)限制有些棘手的連環(huán) bug 能讓 Agent 跑幾十輪消耗驚人而且大概率是白費(fèi)。第二個(gè)護(hù)欄是權(quán)限白名單。自愈腳本只能觸發(fā)“測試、修改源碼、重新運(yùn)行測試”這類安全操作。像生產(chǎn)環(huán)境部署、清空數(shù)據(jù)庫這類危險(xiǎn)操作絕不能放進(jìn)自愈循環(huán)里。具體做法是限制 Claude Code 的允許工具列表或者通過 hook 對危險(xiǎn)命令直接攔截。第三個(gè)護(hù)欄是問題類型的判斷。自愈機(jī)制最擅長的是機(jī)械性問題編譯報(bào)錯(cuò)、單測斷言失敗、類型不對、路徑寫錯(cuò)。這些問題是確定的修復(fù)目標(biāo)明確的Agent 自己就能搞定。但如果是設(shè)計(jì)層面的問題比如模塊職責(zé)混亂、接口方案不合理、狀態(tài)管理設(shè)計(jì)有缺陷我不建議讓 Agent 自己悶頭修。這種問題需要人來拍板Agent 的自愈只會(huì)讓代碼在錯(cuò)誤的框架下變得更復(fù)雜。4. Routine腳本化把重復(fù)性工作固化為可復(fù)用流水線4.1 CLAUDE.md項(xiàng)目記憶的根Routine 腳本化的起點(diǎn)是先解決 Agent 的“項(xiàng)目記憶”問題。Claude Code 在每次會(huì)話啟動(dòng)時(shí)都會(huì)自動(dòng)讀取項(xiàng)目根目錄下的CLAUDE.md把它作為理解項(xiàng)目的核心依據(jù)。這個(gè)文件里寫的不是代碼而是“這個(gè)項(xiàng)目是什么、技術(shù)棧是什么、代碼結(jié)構(gòu)如何、有哪些約定和禁忌”。CLAUDE.md 寫得好不好直接決定 Agent 的初始行為像不像一個(gè)“老團(tuán)隊(duì)成員”。比如我會(huì)在 CLAUDE.md 里明確寫# 項(xiàng)目約定 - 前端使用 React TypeScript組件統(tǒng)一放在 src/components - 后端使用 Node.js禁止在服務(wù)端代碼里寫業(yè)務(wù)邏輯 - 所有公共函數(shù)必須有 JSDoc 注釋 - 提交前必須運(yùn)行 pnpm lint 和 pnpm test:unit - 禁止直接修改 lockfile依賴變更需通過 pnpm add/remove這些約定有什么用當(dāng) Agent 被要求“新增一個(gè)頁面”時(shí)它讀一遍 CLAUDE.md 就知道該往哪個(gè)目錄放文件、用什么語法風(fēng)格、完成后要跑什么校驗(yàn)。你不需要在任何一次任務(wù)里重復(fù)交代這些背景這就是“經(jīng)驗(yàn)沉淀”。4.2 ROUTINE.md操作流程的復(fù)用模板如果說 CLAUDE.md 是“項(xiàng)目是什么”那 ROUTINE.md 就是“這類事情怎么做”。Routine 這個(gè)概念來自工程實(shí)踐中的“標(biāo)準(zhǔn)操作流程”SOP思想把固定重復(fù)的工作流程變成一份 Agent 可以直接照做的模板。以 PR 發(fā)布前檢查為例我一般會(huì)在.claude/routines/目錄里放一份流程文件# 文件名.claude/routines/release-check.md ## 觸發(fā)條件 任何 PR 在打上 release 標(biāo)簽前按此流程執(zhí)行。 ## 執(zhí)行步驟 1. 運(yùn)行 pnpm lint若有 error 則修復(fù)后重跑直到 0 error 2. 運(yùn)行 pnpm test:unit若有失敗則定位原因并修復(fù)再重跑直到全綠 3. 運(yùn)行 pnpm build確認(rèn)構(gòu)建產(chǎn)物正常生成 4. 對比本 PR 涉及的文件生成一份風(fēng)險(xiǎn)清單寫入 .claude/changes.md 5. 若步驟 2 或 3 修復(fù)輪數(shù)超過 3 次停止并請求人工介入 ## 完成標(biāo)準(zhǔn) - lint 0 error - 單測全部通過 - build 產(chǎn)物存在且無異常警告 - .claude/changes.md 已生成內(nèi)容包含變更文件清單和高風(fēng)險(xiǎn)項(xiàng)說明這份 Routine 解決了什么問題你不需要在任務(wù)描述里一點(diǎn)點(diǎn)交代“先做什么再做什么”只需要一句話“執(zhí)行 release-check routine”。Agent 會(huì)自動(dòng)讀取這份模板按步驟逐項(xiàng)執(zhí)行。每次流程的顆粒度一致結(jié)果質(zhì)量和執(zhí)行路徑都可預(yù)期。4.3 把Routine串進(jìn)CLI與Git工作流Routine 文件本身只是“說明書”想讓它真正跑起來還需要把它和 Claude Code 的命令行能力串起來。Claude Code 支持claude -p 指令這種非交互式執(zhí)行模式我經(jīng)常拿它和腳本配合。比如在package.json里加一個(gè)腳本{ scripts: { release-check: claude -p \請按照 .claude/routines/release-check.md 的流程執(zhí)行本次發(fā)布前檢查\ --allowedTools Bash,Read,Edit,Write } }這樣不管是本地開發(fā)還是 CI 里一行npm run release-check就能觸發(fā)整套標(biāo)準(zhǔn)流程。Routine 不再只是 Agent 的參考文本它變成了團(tuán)隊(duì)工作流中的一等公民可固化、可復(fù)用、可通過命令行隨時(shí)調(diào)用。4.4 Routine拆分的顆粒度把“怎么做”和“為什么做”分開最后聊一個(gè)我踩過坑的經(jīng)驗(yàn)Routine 文件一定要把“怎么做”寫清楚把“為什么做”留給 CLAUDE.md 或者代碼注釋。原因很簡單——Agent 是目標(biāo)驅(qū)動(dòng)型執(zhí)行者你給它留的自由度越小它跑出來的結(jié)果越可控。我最早寫 Routine 時(shí)犯過一個(gè)錯(cuò)喜歡把“為什么要跑 lint、為什么要跑單測”也寫進(jìn)去。結(jié)果 Agent 遇到“某一步看起來無關(guān)緊要”的情況時(shí)會(huì)基于自己的理解跳過步驟產(chǎn)出完全不可預(yù)期?，F(xiàn)在我的習(xí)慣是Routine 里只寫“必須做什么、按什么順序、完成標(biāo)準(zhǔn)是什么”所有解釋性內(nèi)容全部刪掉。流程文件就應(yīng)該是無情、機(jī)械、不容變通的。那如何防止 Agent 在 Routine 中途跑偏可以在步驟里反復(fù)強(qiáng)調(diào)“嚴(yán)格按順序執(zhí)行不要跳過任何一步”。再加上我在 3.3 節(jié)說的輪數(shù)護(hù)欄基本上能把不可控因素壓到最低。5. 環(huán)境部署與模型接入從安裝到切換DeepSeek/Qwen/GLM5.1 三平臺(tái)安裝與版本升級(jí)先解決環(huán)境問題。Claude Code 最常見的安裝方式是 npm 全局安裝macOS、Ubuntu、Windows建議配合 WSL 或 Git Bash 使用都可以這樣裝npm install -g anthropic-ai/claude-code claude --version裝完在終端直接敲claude就能進(jìn)入交互模式。升級(jí)也很簡單Claude Code 內(nèi)置了claude update命令可以自動(dòng)拉取并安裝最新版本省去了手動(dòng)卸載重裝的麻煩。如果你關(guān)心“在線升級(jí)最新版本”這個(gè)事claude update就是最省心的路徑。網(wǎng)上還有通過原生安裝器裝的方式體驗(yàn)更好但 npm 方式勝在跨平臺(tái)統(tǒng)一我目前主力環(huán)境就是 Ubuntu Server WSL 的組合npm 安裝一次可以同時(shí)覆蓋幾種使用場景省心。5.2 不支持地區(qū)提示怎么應(yīng)對分區(qū)配置與驗(yàn)證這里有一個(gè)很多人會(huì)遇到的情況安裝或運(yùn)行時(shí)終端可能會(huì)提示“Claude Code might not be available in your country. Check supported countries”。這并不是安裝失敗而是 Claude Code 在啟動(dòng)時(shí)做的一次區(qū)域可用性檢查。它會(huì)在提示后照常打開交互界面但它確實(shí)會(huì)影響部分用戶的使用預(yù)期。一個(gè)穩(wěn)妥的做法是安裝完成后先確認(rèn) npm 源正常再用claude --version驗(yàn)證版本號(hào)能打印出來。只要版本號(hào)正常輸出核心運(yùn)行時(shí)就已經(jīng)就位了。同時(shí)建議保留我的經(jīng)驗(yàn)這類工具經(jīng)常更新每次claude update之后都重新跑一次claude doctor如果有該命令或者claude --version做環(huán)境自檢能省掉不少后續(xù)排錯(cuò)的時(shí)間。5.3 用cc-switch切換DeepSeek、Qwen、GLM等模型Claude Code 默認(rèn)是綁定 Anthropic 賬號(hào)的但很多人手頭用的是 DeepSeek、通義千問Qwen、智譜 GLM 這類模型的 API。這就要用到 cc-switch 這類配置管理工具。cc-switch 做的事情很簡單替你維護(hù)多套 API 供應(yīng)商配置一鍵切換 Claude Code 指向的接口地址和鑒權(quán)信息。原理其實(shí)一點(diǎn)都不神秘Claude Code 本身支持通過環(huán)境變量改寫后端地址和 token核心就是這樣幾個(gè)變量export ANTHROPIC_BASE_URL你的供應(yīng)商兼容接口地址 export ANTHROPIC_AUTH_TOKEN你的供應(yīng)商API Key export ANTHROPIC_MODEL模型名稱如 deepseek-chat / glm-4-plus 等不同供應(yīng)商的兼容接口地址不一樣具體要以各家官方文檔為準(zhǔn)。DeepSeek、阿里云百煉、智譜 AI 都提供 Anthropic 兼容接口所以 Claude Code 可以無縫切換過去使用。cc-switch 的價(jià)值在于它把這些配置從“每次手動(dòng) export”變成了“配置文件里點(diǎn)幾下就切完”。它會(huì)修改 Claude Code 的配置文件寫入不同的 base URL、token 和默認(rèn)模型名下次啟動(dòng)claude時(shí)自動(dòng)生效。切換模型時(shí)不需要?jiǎng)幽愕南到y(tǒng)環(huán)境變量確實(shí)是第三方 API 使用場景下的常用工具。5.4 VS Code聯(lián)調(diào)與插件配置如果你習(xí)慣在編輯器里工作Claude Code 官方提供了 VS Code 擴(kuò)展。裝完擴(kuò)展后側(cè)邊欄會(huì)多出一個(gè) Claude 面板你可以在里面發(fā)起會(huì)話。它和終端的核心能力是打通的同一個(gè) Agent 運(yùn)行時(shí)同一個(gè)工具調(diào)用體系區(qū)別只是多了一個(gè)可視化的 diff 預(yù)覽和文件追蹤功能。我自己在 VS Code 里的用法是終端負(fù)責(zé)跑命令行層面的 Routine 和自愈閉環(huán)編輯器面板負(fù)責(zé)需要逐行審閱代碼的場景。兩個(gè)入口共用一套配置和記憶不會(huì)出現(xiàn)“終端里的 Agent 不知道我改了什么”的情況。配置方面擴(kuò)展會(huì)在首次使用時(shí)引導(dǎo)你選擇可執(zhí)行文件路徑和登錄方式如果走了第三方模型路線確保 5.3 的環(huán)境變量在啟動(dòng) VS Code 前已生效即可。6. 一次真實(shí)改造把PR檢查從單步聊天升級(jí)為編排流水線6.1 改造前人肉搬運(yùn)的聊天式PR檢查最后我把前面三條線串起來講一個(gè)真實(shí)的改造案例你會(huì)發(fā)現(xiàn)這幾個(gè)概念的組合威力比單獨(dú)用大得多。我有一個(gè)開源項(xiàng)目過去每次提 PR 都挺痛苦的。過程是這樣的我先自己在本地跑 lint有錯(cuò)就手動(dòng)改改完跑單測掛了再手動(dòng)修修完 build 又報(bào)錯(cuò)再接著改。偶爾想偷懶就把報(bào)錯(cuò)信息復(fù)制給 Claude Code 聊天窗口讓它給修改建議然后我再復(fù)制回編輯器。一個(gè) PR 檢查流程快的時(shí)候 20 分鐘碰上復(fù)雜的 bug 能折騰一晚上。6.2 改造后Routine固化流程多Agent并行檢查自愈兜底后來我花了半天時(shí)間把整個(gè)流程重構(gòu)成了現(xiàn)在的樣子。第一步寫release-check.mdRoutine把 lint、test、build 的步驟和完成標(biāo)準(zhǔn)全部固化塞進(jìn).claude/routines/目錄。第二步在.claude/agents/里定義了三個(gè) Subagent一個(gè)負(fù)責(zé)跑前端 lint 并修復(fù)一個(gè)負(fù)責(zé)跑后端單測一個(gè)負(fù)責(zé)檢查構(gòu)建產(chǎn)物和生成風(fēng)險(xiǎn)清單。第三步在 settings.json 里加了 PostToolUse hook讓任何測試類命令失敗時(shí)自動(dòng)觸發(fā)修復(fù)指令?，F(xiàn)在執(zhí)行 PR 檢查只需要在項(xiàng)目根目錄敲一行claude -p 按 release-check routine 執(zhí)行 PR 發(fā)布檢查發(fā)現(xiàn)問題就地修復(fù)直到滿足完成標(biāo)準(zhǔn)主 Agent 會(huì)按 Routine 的步驟拆解任務(wù)把前端檢查、后端測試、構(gòu)建檢查分別派給三個(gè) Subagent 并行推進(jìn)。某個(gè)環(huán)節(jié)掛了hook 感知到測試命令返回非零碼自動(dòng)把失敗信息塞回上下文讓 Agent 修完再跑。如果修了 3 輪還沒好Agent 停下把詳細(xì)日志和它嘗試過的方案交給我。這個(gè)改造帶來的變化是質(zhì)變級(jí)的。同樣一個(gè) PR 檢查流程我從 20 分鐘起步的折騰變成了“一條命令走完通過就合不通過看日志”。最關(guān)鍵的還不是快而是可預(yù)期——每次跑的步驟一樣質(zhì)量標(biāo)準(zhǔn)一樣失敗處理策略一樣。它終于從“靠人臨時(shí)發(fā)揮”變成了“靠流程兜底”。6.3 這套組合拳最怕什么三個(gè)容易翻車的細(xì)節(jié)這個(gè)方案跑了兩個(gè)月我踩過三個(gè)坑值得單獨(dú)寫出來。第一個(gè)坑是 Routine 文件寫得不夠“死”。有一次我在步驟里寫“運(yùn)行構(gòu)建并確認(rèn)產(chǎn)物正?！盇gent 檢查完只看了構(gòu)建日志就報(bào)告成功了沒去驗(yàn)證產(chǎn)物文件是否真的存在。后來我把完成標(biāo)準(zhǔn)改成“檢查 dist 目錄下 index.js 文件存在且大小非 0”從此沒再翻過車。第二個(gè)坑是并行 Subagent 之間的文件沖突。兩個(gè)子任務(wù)同時(shí)改同一個(gè)文件可能出現(xiàn)互相覆蓋。現(xiàn)在我的做法是不同 Subagent 只允許操作自己負(fù)責(zé)的目錄在 Subagent 的角色定義里寫清楚“你只能修改 src/ 下的文件”主 Agent 匯總時(shí)再做一次交叉檢查。第三個(gè)坑是自愈循環(huán)卡在“同一類錯(cuò)誤上反復(fù)修”。Agent 修完跑、跑完掛、掛了再修如果根因是同一個(gè)設(shè)計(jì)問題它會(huì)浪費(fèi)大量輪次。所以我給 Routine 加了輪數(shù)上限就像 3.3 節(jié)說的3 輪不過立刻上報(bào)。這個(gè)護(hù)欄讓自愈機(jī)制只處理它擅長的問題剩下的留給人工決策。最后分享一點(diǎn)個(gè)人體會(huì)。多 Agent 編排、閉環(huán)自愈、Routine 腳本化這三板斧單獨(dú)拿出來都不算新鮮真正讓工作流質(zhì)變的是它們組合在一起Routine 提供流程框架多 Agent 提供執(zhí)行效率自愈提供容錯(cuò)兜底。如果你也想在自己的項(xiàng)目里落地這套打法我的建議是別貪多先挑一個(gè)每周都在重復(fù)的瑣碎流程做成第一個(gè) Routine配一個(gè)自愈 hook等跑順了再往里加 Subagent。從一個(gè)小閉環(huán)開始你會(huì)明顯感覺到它和之前聊天式用法的差距。 Claude Code實(shí)戰(zhàn)：從聊天框到多Agent編排與自愈流水線
Claude Code 發(fā)布之后很多人的第一反應(yīng)是把它當(dāng)成終端里的 ChatGPT貼一段報(bào)錯(cuò)問一句“怎么改”復(fù)制答案再貼下一段。我見過的最常見用法就是這樣一問一答單步推進(jìn)。這種用法不能說完全沒用但它恰好浪費(fèi)了 Claude Code 最值錢的部分——它不是一個(gè)聊天框而是一個(gè)跑在終端里的 Agent 運(yùn)行時(shí)。它真正的價(jià)值在于能自己規(guī)劃任務(wù)、自己調(diào)用工具、自己驗(yàn)證結(jié)果甚至在自己出錯(cuò)之后自己爬起來修好自己。這一篇我準(zhǔn)備分四條線把 Claude Code 講透多 Agent 編排怎么把單線程對話變成多角色并行作戰(zhàn)閉環(huán)自愈怎么讓 Agent 在測試失敗時(shí)自動(dòng)修復(fù)直到全綠Routine 腳本化怎么把重復(fù)勞動(dòng)固化成一碰就能跑的流水線最后結(jié)合很多人都關(guān)心的安裝、IDE 接入和第三方模型接入DeepSeek、Qwen、GLM 這類講一下落地細(xì)節(jié)。目標(biāo)只有一個(gè)把它從“高級(jí)問答工具”升級(jí)成真正能交付結(jié)果的“自動(dòng)化工程師”。1. 單步聊天的瓶頸為什么Claude Code不該被當(dāng)成聊天框用1.1 聊天框工作流的三個(gè)死穴先把話說透單步聊天模式在簡單小問題上確實(shí)有效但一旦進(jìn)入真實(shí)工程立刻會(huì)暴露三個(gè)致命問題。第一個(gè)是上下文斷裂。你問完一個(gè)問題得到一段代碼復(fù)制進(jìn)編輯器跑一下報(bào)錯(cuò)再把新報(bào)錯(cuò)貼回去。每一輪都意味著大量的上下文重傳項(xiàng)目的重要背景、之前的結(jié)論、已經(jīng)改過的文件統(tǒng)統(tǒng)需要重復(fù)描述。任務(wù)稍微復(fù)雜一點(diǎn)人和 Agent 都會(huì)迷失在“剛才說到哪了”的混亂里。第二個(gè)是反饋回路缺失。聊天框只能輸出建議不能真的動(dòng)手。它說“把這兩個(gè)函數(shù)抽出來”你改完發(fā)現(xiàn)單測掛了再貼給它看它再給建議你再去改。這個(gè)循環(huán)里真正干活的是人Agent 只是在旁邊當(dāng)參謀。而 Claude Code 不是這樣——它能自己運(yùn)行測試、自己讀報(bào)錯(cuò)、自己改代碼形成完整的行動(dòng)-反饋-修正閉環(huán)。第三個(gè)是經(jīng)驗(yàn)無法沉淀。聊天記錄關(guān)掉就沒了同一個(gè)項(xiàng)目的“提交前檢查流程”下次還得從頭再聊一遍。你從一次問答里得到的只有一段代碼不是一個(gè)可以復(fù)用的工作流程。長此以往工具使用效率始終停留在第一周的水平。1.2 Claude Code的真實(shí)身份終端里的Agent運(yùn)行時(shí)我們得先糾正一個(gè)認(rèn)知Claude Code 和網(wǎng)頁聊天最大的區(qū)別不在于界面而在于“它擁有執(zhí)行權(quán)限”。Claude Code 底層是圍繞工具調(diào)用Tool Use設(shè)計(jì)的 Agent。它手里有一整套工具讀文件、寫文件、執(zhí)行 Shell 命令、運(yùn)行測試、搜索代碼、編輯代碼片段。當(dāng)它接到一個(gè)任務(wù)時(shí)它會(huì)自己做規(guī)劃然后反復(fù)調(diào)用這些工具去驗(yàn)證自己的想法。這意味著它能直接在你的倉庫里動(dòng)代碼、跑出真實(shí)的測試結(jié)果再根據(jù)結(jié)果調(diào)整策略。這看起來只是一個(gè)工程細(xì)節(jié)實(shí)際影響卻是革命性的。網(wǎng)頁聊天里的代碼永遠(yuǎn)只是“建議”你需要手動(dòng)搬運(yùn)Claude Code 里的代碼是“實(shí)施”它會(huì)自己改完自己跑測試。這個(gè)差異決定了它能接手的任務(wù)復(fù)雜度上限完全不同。我還想強(qiáng)調(diào)一個(gè)容易被忽略的點(diǎn)Claude Code 有主 Agent 和子 AgentSubagent的層級(jí)設(shè)計(jì)主 Agent 負(fù)責(zé)拆解目標(biāo)和匯總結(jié)果子 Agent 負(fù)責(zé)具體執(zhí)行。加上 hooks鉤子機(jī)制可以在工具調(diào)用的生命周期里注入你自己的邏輯它天生就是為“可編排、可自愈、可固化”設(shè)計(jì)的。如果你只用它來一問一答等于開著一輛賽車在小區(qū)里遛彎。2. 多Agent編排從一問一答到多角色并行作戰(zhàn)2.1 主Agent與SubagentClaude Code天然就是多Agent架構(gòu)很多人不知道Claude Code 內(nèi)部本身就是一個(gè)多 Agent 架構(gòu)而不是單個(gè)模型死磕到底。主 AgentPrimary Agent負(fù)責(zé)理解你的目標(biāo)、拆解任務(wù)、決定調(diào)用哪些工具、以及把子任務(wù)的產(chǎn)出合并成最終答案。當(dāng)它遇到可以并行或需要專門處理的子問題時(shí)會(huì)通過 Task 工具派發(fā)一個(gè) Subagent。每個(gè) Subagent 都有自己的角色定義、自己的上下文窗口、自己的任務(wù)說明。子 Agent 跑完回來后把結(jié)論交給主 Agent 匯總。這種設(shè)計(jì)最直接的好處是上下文隔離。假設(shè)一個(gè)重構(gòu)任務(wù)涉及前端組件、后端接口、測試用例三塊如果只有一個(gè) Agent 處理它會(huì)帶著全部上下文來回切換很快就把注意力耗散在不同的代碼區(qū)域里。拆成三個(gè) Subagent 后每個(gè)子 Agent 只需要加載自己負(fù)責(zé)的那部分內(nèi)容精力集中出錯(cuò)率低還可以并行推進(jìn)。在項(xiàng)目里你可以通過.claude/agents/目錄來定義自己的專屬 Subagent。比如我想讓一個(gè)專門做代碼審查的 Agent 幫我挑毛病我就寫一個(gè)reviewer.md# 文件名.claude/agents/reviewer.md 你是資深代碼審查員具有 10 年工程實(shí)踐經(jīng)驗(yàn)。你的工作原則 - 只審查不修改發(fā)現(xiàn)問題必須清楚指出代碼位置和修改建議 - 重點(diǎn)防范安全漏洞、性能隱患、可維護(hù)性三類問題 - 輸出時(shí)按嚴(yán)重程度排序先列 P0 阻斷性問題再列優(yōu)化建議 - 不空談理論每一條意見都要能落地主 Agent 需要審查時(shí)會(huì)把這個(gè) Subagent 拉進(jìn)子任務(wù)里讓 review 專注于挑刺而主 Agent 自己專注在“怎么改”的決策上。這就是多 Agent 編排的價(jià)值不同角色負(fù)責(zé)不同職責(zé)而不是一個(gè) Agent 又想寫代碼又想批評(píng)自己——自己審自己的代碼審出來的問題通常都很淺。2.2 三種編排模式串行流水線、扇出聚合與多角色會(huì)商實(shí)際用下來我把多 Agent 編排總結(jié)為三種模式它們對應(yīng)不同場景大家可以按需選用。第一種是串行流水線。上游 Agent 的產(chǎn)出是下游 Agent 的輸入適合有明確依賴關(guān)系的鏈路。比如代碼生成 Agent 先產(chǎn)出新模塊測試 Agent 再對模塊補(bǔ)測試文檔 Agent 最后同步更新文檔。每一環(huán)節(jié)的上下文都限定在本環(huán)節(jié)內(nèi)邏輯清晰好排查。第二種是扇出聚合。主 Agent 把一個(gè)任務(wù)拆成 N 個(gè)獨(dú)立的子任務(wù)同時(shí)派出多個(gè) Subagent 并行執(zhí)行最后把結(jié)果收回來合并。適合大量獨(dú)立文件的批量處理比如多文件重構(gòu)、多目錄掃描。我記得有一次處理一個(gè)倉庫的大規(guī)模命名規(guī)范調(diào)整拆成 6 個(gè) Subagent 并行跑總共用了不到三分鐘換成單 Agent 串行至少得翻三倍時(shí)間。第三種是多角色會(huì)商。開發(fā) Agent 產(chǎn)出代碼審查 Agent 輸出問題清單主 Agent 再綜合兩邊意見做決策。這特別適合“既要快又要穩(wěn)”的場景相當(dāng)于在團(tuán)隊(duì)里強(qiáng)行塞進(jìn)了一個(gè)獨(dú)立評(píng)審角色。我簡單放一個(gè)對比表方便大家在方案設(shè)計(jì)時(shí)快速做選擇編排模式適用場景優(yōu)勢主要風(fēng)險(xiǎn)串行流水線有明確上下游依賴的流程職責(zé)清晰結(jié)果可控單環(huán)節(jié)失敗會(huì)阻塞整條鏈路扇出聚合批量獨(dú)立任務(wù)并發(fā)提速明顯結(jié)果合并需要主 Agent 做歸納多角色會(huì)商寫碼加審查的組合質(zhì)量兜底強(qiáng)消耗 token 更多決策鏈路變長2.3 編排粒度與上下文管理的權(quán)衡關(guān)于多 Agent 編排我必須提醒一句不是拆得越細(xì)越好。Subagent 雖然能隔離上下文但隔離也意味著信息壁壘。子 Agent 之間不能直接對話所有跨子任務(wù)的信息都必須經(jīng)過主 Agent 中轉(zhuǎn)。如果你把一個(gè)本來很簡單的任務(wù)拆成七八個(gè)子任務(wù)主 Agent 會(huì)花大量精力在“傳遞上下文”和“合并結(jié)論”上反而得不償失。我自己的經(jīng)驗(yàn)是一個(gè)子任務(wù)拆分的邊界應(yīng)該是“它能否獨(dú)立完成驗(yàn)證”。如果這個(gè)子任務(wù)跑完能自己給出確定性的結(jié)果——比如“Lint 通過”“測試全綠”“文件已生成”那它就值得拆出去。如果它必須依賴另一個(gè)子任務(wù)的結(jié)果才能繼續(xù)那它更適合作為串行鏈路中的一環(huán)而不是獨(dú)立 Subagent。還有一點(diǎn)Subagent 的上下文通常比主 Agent 更小。越是復(fù)雜的上下文越應(yīng)該留在主 Agent 里把具體的、局部的、機(jī)械性的操作推給 Subagent。這就像搞工程項(xiàng)目經(jīng)理應(yīng)該掌握全局而水電工只需要管好自己那面墻。3. 閉環(huán)自愈讓Agent在報(bào)錯(cuò)之后自己爬起來3.1 hook機(jī)制把自動(dòng)反饋裝進(jìn)工具調(diào)用生命周期閉環(huán)自愈核心就一句話Agent 錯(cuò)了能自己知道然后自己修復(fù)、自己驗(yàn)證直到滿意。Claude Code 實(shí)現(xiàn)這一步的關(guān)鍵是 hooks 機(jī)制。hooks 可以理解成一組“監(jiān)聽器”。Claude Code 在工具調(diào)用的各個(gè)階段都會(huì)觸發(fā)特定事件你可以在這些事件上掛自己的腳本注入額外的邏輯。常見的有幾類PreToolUse工具執(zhí)行前觸發(fā)、PostToolUse工具執(zhí)行后觸發(fā)、NotificationClaude Code 需要發(fā)送通知時(shí)觸發(fā)、UserPromptSubmit用戶提交 prompt 時(shí)觸發(fā)、StopAgent 完成一輪回答后觸發(fā)。真正構(gòu)成自愈閉環(huán)的是PostToolUse和Notification的組合。舉個(gè)例子我想讓 Claude Code 在跑測試失敗后自動(dòng)進(jìn)入修復(fù)模式可以在項(xiàng)目根目錄的.claude/settings.json里配一個(gè) hook{ hooks: { PostToolUse: [ { matcher: Bash, hooks: [ { type: command, command: python3 .claude/scripts/auto_repair.py } ] } ] } }這段配置的意思是每次 Claude Code 執(zhí)行完 Bash 工具后自動(dòng)運(yùn)行auto_repair.py。腳本會(huì)讀取 hook 傳入的 JSON里面包含剛執(zhí)行的命令、返回碼、輸出摘要如果發(fā)現(xiàn)命令是測試命令且返回碼非零就把“測試失敗”作為一條明確指令追加到當(dāng)前會(huì)話的上下文里讓 Agent 知道需要修復(fù)并重新運(yùn)行。3.2 一個(gè)測試失敗自動(dòng)修復(fù)的自愈循環(huán)實(shí)例這里我寫一個(gè)簡化版的自動(dòng)修復(fù)腳本邏輯方便理解整套閉環(huán)是怎么轉(zhuǎn)起來的# .claude/scripts/auto_repair.py import json, sys data json.load(sys.stdin) tool_name data.get(tool_name, ) command data.get(tool_input, {}).get(command, ) exit_code data.get(tool_response, {}).get(exit_code, 0) stderr data.get(tool_response, {}).get(stderr, )[-2000:] # 只對測試類命令生效 if tool_name ! Bash or pytest not in command and npm test not in command: sys.exit(0) if exit_code ! 0: # 通過標(biāo)準(zhǔn)輸出向 Claude Code 注入修復(fù)指令 print( 測試命令返回了非零退出碼。請立即分析上述錯(cuò)誤定位失敗的用例 修復(fù)對應(yīng)源碼后重新運(yùn)行相同的測試命令直到測試全部通過。 f最近錯(cuò)誤{stderr} )這個(gè)腳本的邏輯很直接監(jiān)聽到測試失敗就把失敗信息和修復(fù)指令打包成一段 prompt 塞回對話流。Claude Code 收到這段指令后會(huì)自己去查代碼、改代碼、重新跑測試。如果又失敗hook 再次觸發(fā)再次注入修復(fù)指令。循環(huán)往復(fù)直到通過或者達(dá)到某個(gè)終止條件。這樣構(gòu)建出來的閉環(huán)本質(zhì)上是把“人肉搬運(yùn)報(bào)錯(cuò)信息”這個(gè)環(huán)節(jié)省掉了。效果很明顯——以前測試掛了你要復(fù)制報(bào)錯(cuò)、貼給 Agent、等答案、復(fù)制修改、再跑測試。現(xiàn)在測試掛了Agent 自己就能跳起來處理。3.3 自愈的邊界什么時(shí)候要人為介入閉環(huán)自愈不是萬能的它有非常明確的適用邊界。我在實(shí)際項(xiàng)目中給自愈循環(huán)設(shè)了嚴(yán)格的“護(hù)欄”否則它會(huì)變成一個(gè)吞 token 的無底洞。第一個(gè)護(hù)欄是輪數(shù)限制。我會(huì)在 prompt 里明確告訴 Agent“如果連續(xù)修復(fù) 3 輪測試仍未通過停止并報(bào)告等待人工決策?！睕]有這個(gè)限制有些棘手的連環(huán) bug 能讓 Agent 跑幾十輪消耗驚人而且大概率是白費(fèi)。第二個(gè)護(hù)欄是權(quán)限白名單。自愈腳本只能觸發(fā)“測試、修改源碼、重新運(yùn)行測試”這類安全操作。像生產(chǎn)環(huán)境部署、清空數(shù)據(jù)庫這類危險(xiǎn)操作絕不能放進(jìn)自愈循環(huán)里。具體做法是限制 Claude Code 的允許工具列表或者通過 hook 對危險(xiǎn)命令直接攔截。第三個(gè)護(hù)欄是問題類型的判斷。自愈機(jī)制最擅長的是機(jī)械性問題編譯報(bào)錯(cuò)、單測斷言失敗、類型不對、路徑寫錯(cuò)。這些問題是確定的修復(fù)目標(biāo)明確的Agent 自己就能搞定。但如果是設(shè)計(jì)層面的問題比如模塊職責(zé)混亂、接口方案不合理、狀態(tài)管理設(shè)計(jì)有缺陷我不建議讓 Agent 自己悶頭修。這種問題需要人來拍板Agent 的自愈只會(huì)讓代碼在錯(cuò)誤的框架下變得更復(fù)雜。4. Routine腳本化把重復(fù)性工作固化為可復(fù)用流水線4.1 CLAUDE.md項(xiàng)目記憶的根Routine 腳本化的起點(diǎn)是先解決 Agent 的“項(xiàng)目記憶”問題。Claude Code 在每次會(huì)話啟動(dòng)時(shí)都會(huì)自動(dòng)讀取項(xiàng)目根目錄下的CLAUDE.md把它作為理解項(xiàng)目的核心依據(jù)。這個(gè)文件里寫的不是代碼而是“這個(gè)項(xiàng)目是什么、技術(shù)棧是什么、代碼結(jié)構(gòu)如何、有哪些約定和禁忌”。CLAUDE.md 寫得好不好直接決定 Agent 的初始行為像不像一個(gè)“老團(tuán)隊(duì)成員”。比如我會(huì)在 CLAUDE.md 里明確寫# 項(xiàng)目約定 - 前端使用 React TypeScript組件統(tǒng)一放在 src/components - 后端使用 Node.js禁止在服務(wù)端代碼里寫業(yè)務(wù)邏輯 - 所有公共函數(shù)必須有 JSDoc 注釋 - 提交前必須運(yùn)行 pnpm lint 和 pnpm test:unit - 禁止直接修改 lockfile依賴變更需通過 pnpm add/remove這些約定有什么用當(dāng) Agent 被要求“新增一個(gè)頁面”時(shí)它讀一遍 CLAUDE.md 就知道該往哪個(gè)目錄放文件、用什么語法風(fēng)格、完成后要跑什么校驗(yàn)。你不需要在任何一次任務(wù)里重復(fù)交代這些背景這就是“經(jīng)驗(yàn)沉淀”。4.2 ROUTINE.md操作流程的復(fù)用模板如果說 CLAUDE.md 是“項(xiàng)目是什么”那 ROUTINE.md 就是“這類事情怎么做”。Routine 這個(gè)概念來自工程實(shí)踐中的“標(biāo)準(zhǔn)操作流程”SOP思想把固定重復(fù)的工作流程變成一份 Agent 可以直接照做的模板。以 PR 發(fā)布前檢查為例我一般會(huì)在.claude/routines/目錄里放一份流程文件# 文件名.claude/routines/release-check.md ## 觸發(fā)條件 任何 PR 在打上 release 標(biāo)簽前按此流程執(zhí)行。 ## 執(zhí)行步驟 1. 運(yùn)行 pnpm lint若有 error 則修復(fù)后重跑直到 0 error 2. 運(yùn)行 pnpm test:unit若有失敗則定位原因并修復(fù)再重跑直到全綠 3. 運(yùn)行 pnpm build確認(rèn)構(gòu)建產(chǎn)物正常生成 4. 對比本 PR 涉及的文件生成一份風(fēng)險(xiǎn)清單寫入 .claude/changes.md 5. 若步驟 2 或 3 修復(fù)輪數(shù)超過 3 次停止并請求人工介入 ## 完成標(biāo)準(zhǔn) - lint 0 error - 單測全部通過 - build 產(chǎn)物存在且無異常警告 - .claude/changes.md 已生成內(nèi)容包含變更文件清單和高風(fēng)險(xiǎn)項(xiàng)說明這份 Routine 解決了什么問題你不需要在任務(wù)描述里一點(diǎn)點(diǎn)交代“先做什么再做什么”只需要一句話“執(zhí)行 release-check routine”。Agent 會(huì)自動(dòng)讀取這份模板按步驟逐項(xiàng)執(zhí)行。每次流程的顆粒度一致結(jié)果質(zhì)量和執(zhí)行路徑都可預(yù)期。4.3 把Routine串進(jìn)CLI與Git工作流Routine 文件本身只是“說明書”想讓它真正跑起來還需要把它和 Claude Code 的命令行能力串起來。Claude Code 支持claude -p 指令這種非交互式執(zhí)行模式我經(jīng)常拿它和腳本配合。比如在package.json里加一個(gè)腳本{ scripts: { release-check: claude -p \請按照 .claude/routines/release-check.md 的流程執(zhí)行本次發(fā)布前檢查\ --allowedTools Bash,Read,Edit,Write } }這樣不管是本地開發(fā)還是 CI 里一行npm run release-check就能觸發(fā)整套標(biāo)準(zhǔn)流程。Routine 不再只是 Agent 的參考文本它變成了團(tuán)隊(duì)工作流中的一等公民可固化、可復(fù)用、可通過命令行隨時(shí)調(diào)用。4.4 Routine拆分的顆粒度把“怎么做”和“為什么做”分開最后聊一個(gè)我踩過坑的經(jīng)驗(yàn)Routine 文件一定要把“怎么做”寫清楚把“為什么做”留給 CLAUDE.md 或者代碼注釋。原因很簡單——Agent 是目標(biāo)驅(qū)動(dòng)型執(zhí)行者你給它留的自由度越小它跑出來的結(jié)果越可控。我最早寫 Routine 時(shí)犯過一個(gè)錯(cuò)喜歡把“為什么要跑 lint、為什么要跑單測”也寫進(jìn)去。結(jié)果 Agent 遇到“某一步看起來無關(guān)緊要”的情況時(shí)會(huì)基于自己的理解跳過步驟產(chǎn)出完全不可預(yù)期?，F(xiàn)在我的習(xí)慣是Routine 里只寫“必須做什么、按什么順序、完成標(biāo)準(zhǔn)是什么”所有解釋性內(nèi)容全部刪掉。流程文件就應(yīng)該是無情、機(jī)械、不容變通的。那如何防止 Agent 在 Routine 中途跑偏可以在步驟里反復(fù)強(qiáng)調(diào)“嚴(yán)格按順序執(zhí)行不要跳過任何一步”。再加上我在 3.3 節(jié)說的輪數(shù)護(hù)欄基本上能把不可控因素壓到最低。5. 環(huán)境部署與模型接入從安裝到切換DeepSeek/Qwen/GLM5.1 三平臺(tái)安裝與版本升級(jí)先解決環(huán)境問題。Claude Code 最常見的安裝方式是 npm 全局安裝macOS、Ubuntu、Windows建議配合 WSL 或 Git Bash 使用都可以這樣裝npm install -g anthropic-ai/claude-code claude --version裝完在終端直接敲claude就能進(jìn)入交互模式。升級(jí)也很簡單Claude Code 內(nèi)置了claude update命令可以自動(dòng)拉取并安裝最新版本省去了手動(dòng)卸載重裝的麻煩。如果你關(guān)心“在線升級(jí)最新版本”這個(gè)事claude update就是最省心的路徑。網(wǎng)上還有通過原生安裝器裝的方式體驗(yàn)更好但 npm 方式勝在跨平臺(tái)統(tǒng)一我目前主力環(huán)境就是 Ubuntu Server WSL 的組合npm 安裝一次可以同時(shí)覆蓋幾種使用場景省心。5.2 不支持地區(qū)提示怎么應(yīng)對分區(qū)配置與驗(yàn)證這里有一個(gè)很多人會(huì)遇到的情況安裝或運(yùn)行時(shí)終端可能會(huì)提示“Claude Code might not be available in your country. Check supported countries”。這并不是安裝失敗而是 Claude Code 在啟動(dòng)時(shí)做的一次區(qū)域可用性檢查。它會(huì)在提示后照常打開交互界面但它確實(shí)會(huì)影響部分用戶的使用預(yù)期。一個(gè)穩(wěn)妥的做法是安裝完成后先確認(rèn) npm 源正常再用claude --version驗(yàn)證版本號(hào)能打印出來。只要版本號(hào)正常輸出核心運(yùn)行時(shí)就已經(jīng)就位了。同時(shí)建議保留我的經(jīng)驗(yàn)這類工具經(jīng)常更新每次claude update之后都重新跑一次claude doctor如果有該命令或者claude --version做環(huán)境自檢能省掉不少后續(xù)排錯(cuò)的時(shí)間。5.3 用cc-switch切換DeepSeek、Qwen、GLM等模型Claude Code 默認(rèn)是綁定 Anthropic 賬號(hào)的但很多人手頭用的是 DeepSeek、通義千問Qwen、智譜 GLM 這類模型的 API。這就要用到 cc-switch 這類配置管理工具。cc-switch 做的事情很簡單替你維護(hù)多套 API 供應(yīng)商配置一鍵切換 Claude Code 指向的接口地址和鑒權(quán)信息。原理其實(shí)一點(diǎn)都不神秘Claude Code 本身支持通過環(huán)境變量改寫后端地址和 token核心就是這樣幾個(gè)變量export ANTHROPIC_BASE_URL你的供應(yīng)商兼容接口地址 export ANTHROPIC_AUTH_TOKEN你的供應(yīng)商API Key export ANTHROPIC_MODEL模型名稱如 deepseek-chat / glm-4-plus 等不同供應(yīng)商的兼容接口地址不一樣具體要以各家官方文檔為準(zhǔn)。DeepSeek、阿里云百煉、智譜 AI 都提供 Anthropic 兼容接口所以 Claude Code 可以無縫切換過去使用。cc-switch 的價(jià)值在于它把這些配置從“每次手動(dòng) export”變成了“配置文件里點(diǎn)幾下就切完”。它會(huì)修改 Claude Code 的配置文件寫入不同的 base URL、token 和默認(rèn)模型名下次啟動(dòng)claude時(shí)自動(dòng)生效。切換模型時(shí)不需要?jiǎng)幽愕南到y(tǒng)環(huán)境變量確實(shí)是第三方 API 使用場景下的常用工具。5.4 VS Code聯(lián)調(diào)與插件配置如果你習(xí)慣在編輯器里工作Claude Code 官方提供了 VS Code 擴(kuò)展。裝完擴(kuò)展后側(cè)邊欄會(huì)多出一個(gè) Claude 面板你可以在里面發(fā)起會(huì)話。它和終端的核心能力是打通的同一個(gè) Agent 運(yùn)行時(shí)同一個(gè)工具調(diào)用體系區(qū)別只是多了一個(gè)可視化的 diff 預(yù)覽和文件追蹤功能。我自己在 VS Code 里的用法是終端負(fù)責(zé)跑命令行層面的 Routine 和自愈閉環(huán)編輯器面板負(fù)責(zé)需要逐行審閱代碼的場景。兩個(gè)入口共用一套配置和記憶不會(huì)出現(xiàn)“終端里的 Agent 不知道我改了什么”的情況。配置方面擴(kuò)展會(huì)在首次使用時(shí)引導(dǎo)你選擇可執(zhí)行文件路徑和登錄方式如果走了第三方模型路線確保 5.3 的環(huán)境變量在啟動(dòng) VS Code 前已生效即可。6. 一次真實(shí)改造把PR檢查從單步聊天升級(jí)為編排流水線6.1 改造前人肉搬運(yùn)的聊天式PR檢查最后我把前面三條線串起來講一個(gè)真實(shí)的改造案例你會(huì)發(fā)現(xiàn)這幾個(gè)概念的組合威力比單獨(dú)用大得多。我有一個(gè)開源項(xiàng)目過去每次提 PR 都挺痛苦的。過程是這樣的我先自己在本地跑 lint有錯(cuò)就手動(dòng)改改完跑單測掛了再手動(dòng)修修完 build 又報(bào)錯(cuò)再接著改。偶爾想偷懶就把報(bào)錯(cuò)信息復(fù)制給 Claude Code 聊天窗口讓它給修改建議然后我再復(fù)制回編輯器。一個(gè) PR 檢查流程快的時(shí)候 20 分鐘碰上復(fù)雜的 bug 能折騰一晚上。6.2 改造后Routine固化流程多Agent并行檢查自愈兜底后來我花了半天時(shí)間把整個(gè)流程重構(gòu)成了現(xiàn)在的樣子。第一步寫release-check.mdRoutine把 lint、test、build 的步驟和完成標(biāo)準(zhǔn)全部固化塞進(jìn).claude/routines/目錄。第二步在.claude/agents/里定義了三個(gè) Subagent一個(gè)負(fù)責(zé)跑前端 lint 并修復(fù)一個(gè)負(fù)責(zé)跑后端單測一個(gè)負(fù)責(zé)檢查構(gòu)建產(chǎn)物和生成風(fēng)險(xiǎn)清單。第三步在 settings.json 里加了 PostToolUse hook讓任何測試類命令失敗時(shí)自動(dòng)觸發(fā)修復(fù)指令?，F(xiàn)在執(zhí)行 PR 檢查只需要在項(xiàng)目根目錄敲一行claude -p 按 release-check routine 執(zhí)行 PR 發(fā)布檢查發(fā)現(xiàn)問題就地修復(fù)直到滿足完成標(biāo)準(zhǔn)主 Agent 會(huì)按 Routine 的步驟拆解任務(wù)把前端檢查、后端測試、構(gòu)建檢查分別派給三個(gè) Subagent 并行推進(jìn)。某個(gè)環(huán)節(jié)掛了hook 感知到測試命令返回非零碼自動(dòng)把失敗信息塞回上下文讓 Agent 修完再跑。如果修了 3 輪還沒好Agent 停下把詳細(xì)日志和它嘗試過的方案交給我。這個(gè)改造帶來的變化是質(zhì)變級(jí)的。同樣一個(gè) PR 檢查流程我從 20 分鐘起步的折騰變成了“一條命令走完通過就合不通過看日志”。最關(guān)鍵的還不是快而是可預(yù)期——每次跑的步驟一樣質(zhì)量標(biāo)準(zhǔn)一樣失敗處理策略一樣。它終于從“靠人臨時(shí)發(fā)揮”變成了“靠流程兜底”。6.3 這套組合拳最怕什么三個(gè)容易翻車的細(xì)節(jié)這個(gè)方案跑了兩個(gè)月我踩過三個(gè)坑值得單獨(dú)寫出來。第一個(gè)坑是 Routine 文件寫得不夠“死”。有一次我在步驟里寫“運(yùn)行構(gòu)建并確認(rèn)產(chǎn)物正?！盇gent 檢查完只看了構(gòu)建日志就報(bào)告成功了沒去驗(yàn)證產(chǎn)物文件是否真的存在。后來我把完成標(biāo)準(zhǔn)改成“檢查 dist 目錄下 index.js 文件存在且大小非 0”從此沒再翻過車。第二個(gè)坑是并行 Subagent 之間的文件沖突。兩個(gè)子任務(wù)同時(shí)改同一個(gè)文件可能出現(xiàn)互相覆蓋。現(xiàn)在我的做法是不同 Subagent 只允許操作自己負(fù)責(zé)的目錄在 Subagent 的角色定義里寫清楚“你只能修改 src/ 下的文件”主 Agent 匯總時(shí)再做一次交叉檢查。第三個(gè)坑是自愈循環(huán)卡在“同一類錯(cuò)誤上反復(fù)修”。Agent 修完跑、跑完掛、掛了再修如果根因是同一個(gè)設(shè)計(jì)問題它會(huì)浪費(fèi)大量輪次。所以我給 Routine 加了輪數(shù)上限就像 3.3 節(jié)說的3 輪不過立刻上報(bào)。這個(gè)護(hù)欄讓自愈機(jī)制只處理它擅長的問題剩下的留給人工決策。最后分享一點(diǎn)個(gè)人體會(huì)。多 Agent 編排、閉環(huán)自愈、Routine 腳本化這三板斧單獨(dú)拿出來都不算新鮮真正讓工作流質(zhì)變的是它們組合在一起Routine 提供流程框架多 Agent 提供執(zhí)行效率自愈提供容錯(cuò)兜底。如果你也想在自己的項(xiàng)目里落地這套打法我的建議是別貪多先挑一個(gè)每周都在重復(fù)的瑣碎流程做成第一個(gè) Routine配一個(gè)自愈 hook等跑順了再往里加 Subagent。從一個(gè)小閉環(huán)開始你會(huì)明顯感覺到它和之前聊天式用法的差距。