1. 從AI輔助到AI原生團(tuán)隊(duì)開發(fā)范式到底變了什么大多數(shù)團(tuán)隊(duì)嘴上說著AI Native實(shí)際干的事還是老一套——產(chǎn)品經(jīng)理寫PRD開發(fā)照著文檔敲代碼測試等提測最后在某一步接入AI當(dāng)作亮點(diǎn)。這不叫AI Native這叫AI點(diǎn)綴。真正的AI Native團(tuán)隊(duì)改變的不是某個環(huán)節(jié)的工具而是整個軟件開發(fā)生命周期SDLC的組織方式Agent成為一等公民人從執(zhí)行者變成編排者和審核者。我所在的團(tuán)隊(duì)從去年開始完整跑通了一套AI Native的開發(fā)流程從需求拆解、方案設(shè)計(jì)、編碼實(shí)現(xiàn)、代碼審查到測試驗(yàn)證全鏈路都有Agent參與。踩過的坑、驗(yàn)證過的模式、沉淀下來的規(guī)范構(gòu)成了這份手冊的全部內(nèi)容。它適合三類人一是想搞清楚AI Native到底怎么落地的技術(shù)負(fù)責(zé)人二是正在搭建Agent工作流的一線開發(fā)者三是對SDLC重構(gòu)感興趣、想知道人機(jī)協(xié)作邊界在哪的工程師。先說一個反直覺的結(jié)論AI Native團(tuán)隊(duì)最大的瓶頸從來不是模型能力而是上下文管理。模型再強(qiáng)如果它拿不到正確的項(xiàng)目背景、編碼規(guī)范、歷史決策產(chǎn)出的東西就是看起來對但用不了。所以這份手冊的核心線索是圍繞如何讓Agent在正確的上下文中工作展開的——CLAUDE.md怎么組織、Plan Mode怎么用、Agent的邊界怎么劃、多Agent怎么編排、安全怎么兜底。下面逐層拆開講。2. 上下文工程CLAUDE.md不是說明書是Agent的操作系統(tǒng)2.1 為什么大多數(shù)團(tuán)隊(duì)的CLAUDE.md寫了等于沒寫我見過太多團(tuán)隊(duì)的CLAUDE.md打開一看就是一段本項(xiàng)目使用React TypeScript請遵循最佳實(shí)踐——這種寫法對Agent來說幾乎零信息量。Agent需要的是可執(zhí)行的約束不是泛泛而談的原則。一份有效的CLAUDE.md本質(zhì)上是給Agent的入職培訓(xùn)手冊它要回答四個問題這個項(xiàng)目是干什么的、代碼怎么組織、改代碼要遵守什么規(guī)則、遇到不確定時該問誰。我們團(tuán)隊(duì)迭代了七版CLAUDE.md最終穩(wěn)定下來的結(jié)構(gòu)是這樣的項(xiàng)目定位段一句話說清業(yè)務(wù)目標(biāo)和技術(shù)棧不超過三行。Agent不需要讀你的商業(yè)計(jì)劃書。目錄地圖用樹狀結(jié)構(gòu)標(biāo)注每個目錄的職責(zé)特別是那些看起來像但實(shí)際不同的目錄。比如/utils和/helpers的區(qū)別不寫清楚Agent一定會放錯地方。編碼鐵律只寫那些違反了一定會出問題的規(guī)則。比如所有API調(diào)用必須走request.ts封裝禁止直接使用fetch、狀態(tài)管理統(tǒng)一用Zustand禁止引入Redux。禁區(qū)清單明確列出Agent不能碰的文件和目錄比如數(shù)據(jù)庫遷移腳本、CI配置、密鑰文件。決策記錄索引指向/docs/adr目錄讓Agent在遇到架構(gòu)選擇時先查歷史決策。提示CLAUDE.md的長度控制在500行以內(nèi)。超過這個長度Agent的注意力會被稀釋關(guān)鍵規(guī)則反而被忽略。我們的做法是把詳細(xì)規(guī)范拆到/docs下CLAUDE.md只保留索引和鐵律。2.2 上下文分層把永遠(yuǎn)要知道和用到才加載分開一開始我們把所有規(guī)范都塞進(jìn)CLAUDE.md結(jié)果Agent每次對話都要吞掉大量無關(guān)信息token消耗高不說還經(jīng)常抓錯重點(diǎn)。后來我們做了分層層級內(nèi)容加載時機(jī)載體L0 常駐項(xiàng)目定位、編碼鐵律、禁區(qū)每次對話CLAUDE.mdL1 按需模塊設(shè)計(jì)文檔、API契約涉及該模塊時/docs/modules/*.mdL2 檢索歷史決策、踩坑記錄Agent主動查詢/docs/adr/*.mdL3 臨時當(dāng)前任務(wù)上下文任務(wù)開始時注入Plan Mode這個分層的關(guān)鍵在于L0必須極度精簡。我們實(shí)測下來L0控制在300行以內(nèi)時Agent對規(guī)則的遵守率明顯高于塞滿內(nèi)容的版本。L1和L2通過文件路徑引用Agent需要時會自己去讀——前提是你在CLAUDE.md里告訴它遇到X情況去讀Y文件。2.3 一個真實(shí)的翻車案例有次我們讓Agent重構(gòu)一個訂單模塊它在CLAUDE.md里讀到狀態(tài)管理用Zustand但沒讀到訂單狀態(tài)機(jī)必須走orderStateMachine.ts禁止直接setState。結(jié)果它自作主張用Zustand直接改了狀態(tài)繞過了狀態(tài)機(jī)的校驗(yàn)邏輯測試環(huán)境直接炸了。問題不在Agent在于我們把關(guān)鍵約束放在了L1文檔里而那次任務(wù)沒有觸發(fā)L1加載。教訓(xùn)凡是違反了會導(dǎo)致線上事故的規(guī)則一律放L0。寧可CLAUDE.md長一點(diǎn)也不能讓關(guān)鍵約束藏在按需加載的文檔里。3. Plan Mode實(shí)戰(zhàn)讓Agent先想清楚再動手3.1 Plan Mode解決的是什么問題Agent最危險的行為模式是邊想邊做——它可能改到一半發(fā)現(xiàn)方向錯了但已經(jīng)動了好幾個文件回滾成本極高。Plan Mode的核心價值就是強(qiáng)制Agent在動手前輸出完整方案由人審核后再執(zhí)行。這聽起來簡單但實(shí)際用起來有很多細(xì)節(jié)。我們的Plan Mode流程是這樣的Agent接到任務(wù)后先輸出一份計(jì)劃包含要改哪些文件、每個文件改什么、為什么這么改、有什么風(fēng)險。人審核通過后Agent才開始執(zhí)行。審核不通過就打回重來。這個流程把返工成本從改錯代碼降到了改錯計(jì)劃效率提升非常明顯。3.2 計(jì)劃的質(zhì)量取決于提示詞的結(jié)構(gòu)一開始Agent輸出的計(jì)劃很水就是修改A文件、修改B文件這種流水賬。后來我們優(yōu)化了提示詞模板要求計(jì)劃必須包含五個部分任務(wù)理解用自己的話復(fù)述需求確認(rèn)理解無誤。影響范圍列出所有會被改動的文件標(biāo)注新增/修改/刪除。實(shí)現(xiàn)思路每個文件改什么、為什么這么改。風(fēng)險點(diǎn)可能影響的其他功能、需要回歸測試的范圍。驗(yàn)證方案改完后怎么驗(yàn)證跑哪些測試。這個模板逼著Agent把想和做分開也讓人審核時有了明確的檢查清單。實(shí)測下來計(jì)劃階段多花5分鐘執(zhí)行階段能省半小時。3.3 什么任務(wù)適合Plan Mode什么任務(wù)不適合不是所有任務(wù)都值得走Plan Mode。我們的經(jīng)驗(yàn)是適合跨多文件的改動、涉及核心邏輯的重構(gòu)、新增功能模塊、數(shù)據(jù)庫schema變更。不適合單文件的小修小補(bǔ)、格式化、改文案、加日志。判斷標(biāo)準(zhǔn)很簡單如果改錯了回滾成本高不高。高就走Plan Mode低就直接干。我們團(tuán)隊(duì)有個不成文的規(guī)矩改動超過3個文件必須走Plan Mode。注意Plan Mode不是萬能的。有些Agent會在計(jì)劃里寫得天花亂墜執(zhí)行時卻偷工減料。所以執(zhí)行完成后一定要對照計(jì)劃逐項(xiàng)驗(yàn)收不能只看任務(wù)完成的提示。4. Agent的邊界與編排單Agent、多Agent、Agent Harness怎么選4.1 先搞清楚Agent、Harness、Skill的區(qū)別這三個詞經(jīng)常被混用但它們的職責(zé)完全不同。我用一個類比說明Agent是員工Harness是工位和工具Skill是員工掌握的技能。Agent具備自主決策能力的執(zhí)行單元能理解任務(wù)、規(guī)劃步驟、調(diào)用工具。HarnessAgent的運(yùn)行環(huán)境負(fù)責(zé)工具注冊、權(quán)限控制、上下文注入、執(zhí)行監(jiān)控。你可以理解為給Agent搭的工作臺。SkillAgent可以調(diào)用的具體能力比如讀文件跑測試查數(shù)據(jù)庫。Skill是原子操作Agent負(fù)責(zé)編排。搞清楚這個區(qū)分很重要因?yàn)楹芏鄨F(tuán)隊(duì)一上來就想搞多Agent協(xié)作結(jié)果連單Agent的Harness都沒搭好Agent連文件都讀不利索談何協(xié)作。4.2 單Agent夠用的場景別急著上多Agent我們團(tuán)隊(duì)80%的任務(wù)是單Agent完成的。單Agent的優(yōu)勢是上下文連貫、決策鏈路清晰、調(diào)試簡單。什么時候該上多Agent我的判斷標(biāo)準(zhǔn)是當(dāng)任務(wù)可以清晰拆分成多個獨(dú)立子任務(wù)且子任務(wù)之間不需要頻繁交換上下文時。舉個例子一個給現(xiàn)有API加緩存層的任務(wù)單Agent完全夠用——它需要理解現(xiàn)有API、設(shè)計(jì)緩存策略、實(shí)現(xiàn)、測試這些步驟高度依賴同一個上下文。但如果任務(wù)是同時重構(gòu)前端組件庫和后端API這兩個子任務(wù)上下文幾乎不重疊就可以拆成兩個Agent并行。多Agent的代價是上下文同步成本。兩個Agent各自工作最后合并時經(jīng)常發(fā)現(xiàn)接口對不上、命名不一致。我們的做法是多Agent任務(wù)必須先由人定義好接口契約Agent只能在這個契約內(nèi)工作。4.3 Agent編排的三種模式我們實(shí)際用過的編排模式有三種各有適用場景串行編排Agent A的輸出作為Agent B的輸入。適合設(shè)計(jì)→實(shí)現(xiàn)→測試這種流水線。優(yōu)點(diǎn)是上下文傳遞清晰缺點(diǎn)是慢且前一步錯了后面全錯。并行編排多個Agent同時處理獨(dú)立子任務(wù)最后匯總。適合大范圍重構(gòu)。優(yōu)點(diǎn)是快缺點(diǎn)是合并沖突多。監(jiān)督編排一個監(jiān)督Agent負(fù)責(zé)任務(wù)分解和結(jié)果驗(yàn)收多個執(zhí)行Agent干活。適合復(fù)雜任務(wù)。優(yōu)點(diǎn)是質(zhì)量可控缺點(diǎn)是監(jiān)督Agent本身的能力要求高容易成為瓶頸。我們目前的主力模式是串行為主、局部并行。核心鏈路串行保證質(zhì)量獨(dú)立的子任務(wù)比如同時改多個不相關(guān)的模塊并行提速。4.4 Agent安全沙箱、權(quán)限、審計(jì)一個都不能少Agent能讀文件、能執(zhí)行命令、能調(diào)API這意味著它一旦跑偏破壞力比人大得多。我們的安全策略分三層第一層是沙箱隔離。Agent的所有操作在容器內(nèi)進(jìn)行網(wǎng)絡(luò)訪問白名單文件系統(tǒng)只掛載項(xiàng)目目錄。這樣即使Agent執(zhí)行了危險命令影響范圍也可控。第二層是權(quán)限分級。我們把操作分成三檔只讀操作讀文件、查日志Agent可自主執(zhí)行寫操作改代碼、建文件需要Plan Mode審核危險操作刪文件、改配置、執(zhí)行遷移必須人工確認(rèn)。第三層是審計(jì)日志。Agent的每一次工具調(diào)用、每一條命令、每一個文件改動都記錄在案。出問題時能完整回溯Agent當(dāng)時看到了什么、做了什么決策。提示審計(jì)日志不要只記做了什么還要記為什么。我們的做法是要求Agent在每次關(guān)鍵操作前輸出一句理由這句話會一起進(jìn)日志。排查問題時這句理由往往比操作本身更有價值。5. 全鏈路SDLC改造每個環(huán)節(jié)Agent該干什么、人該干什么5.1 需求階段Agent做拆解人做取舍需求階段Agent能做的是結(jié)構(gòu)化——把一段模糊的需求描述拆成可執(zhí)行的任務(wù)列表標(biāo)注依賴關(guān)系、預(yù)估復(fù)雜度、識別歧義點(diǎn)。但優(yōu)先級排序和范圍取舍必須由人做因?yàn)檫@里面涉及業(yè)務(wù)判斷和資源約束Agent沒有足夠信息。我們的流程是產(chǎn)品經(jīng)理寫一段需求描述Agent輸出一份任務(wù)拆解草案包含任務(wù)列表、依賴圖、歧義點(diǎn)清單。然后人過一遍回答歧義點(diǎn)、調(diào)整優(yōu)先級、砍掉不做的部分。這個環(huán)節(jié)Agent能省掉大概60%的整理時間。5.2 設(shè)計(jì)階段Agent出方案人做決策設(shè)計(jì)階段是Plan Mode的主場。Agent基于需求輸出技術(shù)方案包括模塊劃分、接口設(shè)計(jì)、數(shù)據(jù)模型、關(guān)鍵流程。人審核方案重點(diǎn)看三件事是否符合現(xiàn)有架構(gòu)、是否引入了不必要的復(fù)雜度、是否有遺漏的邊界情況。這個環(huán)節(jié)有個坑Agent傾向于過度設(shè)計(jì)。它可能會給你搞出一套復(fù)雜的抽象層而實(shí)際上一個簡單函數(shù)就夠了。所以審核時要多問一句能不能更簡單。5.3 編碼階段Agent寫代碼人做審查編碼階段Agent的產(chǎn)出質(zhì)量直接取決于前兩個階段的上下文質(zhì)量。如果需求和設(shè)計(jì)都清晰Agent寫出來的代碼基本可用如果前面含糊Agent就會自由發(fā)揮產(chǎn)出大量需要返工的東西。代碼審查環(huán)節(jié)人重點(diǎn)看四類問題業(yè)務(wù)邏輯是否正確、邊界條件是否處理、是否有安全隱患、是否符合團(tuán)隊(duì)規(guī)范。格式問題、命名問題這些交給linter和Agent自查人不用浪費(fèi)時間。5.4 測試階段Agent生成用例人做驗(yàn)收Agent生成測試用例的能力很強(qiáng)但有個通病它傾向于測試正常路徑對異常路徑覆蓋不足。我們的做法是要求Agent必須為每個函數(shù)生成至少三類用例正常輸入、邊界輸入、異常輸入。人審核時重點(diǎn)看異常用例是否覆蓋到位。驗(yàn)收環(huán)節(jié)必須由人做。Agent可以跑測試、報(bào)告結(jié)果但這個功能是否符合業(yè)務(wù)預(yù)期只有人能判斷。5.5 各環(huán)節(jié)人機(jī)分工速查表環(huán)節(jié)Agent負(fù)責(zé)人負(fù)責(zé)關(guān)鍵產(chǎn)出需求拆解、識別歧義優(yōu)先級、范圍取舍任務(wù)列表設(shè)計(jì)出方案、畫流程架構(gòu)決策、簡化技術(shù)方案編碼寫代碼、自查邏輯審查、安全審查可運(yùn)行代碼測試生成用例、執(zhí)行異常覆蓋審核、驗(yàn)收測試報(bào)告部署生成配置、執(zhí)行審批、監(jiān)控上線記錄6. 踩坑實(shí)錄那些讓我們返工三次以上的問題6.1 上下文污染Agent讀到了過時的文檔有次Agent根據(jù)一份三個月前的設(shè)計(jì)文檔改了代碼結(jié)果那份文檔早就廢棄了。問題根源是我們的/docs目錄沒有清理機(jī)制新舊文檔混在一起Agent分不清哪個是當(dāng)前有效的。解決方案所有文檔加有效期標(biāo)記過期文檔移到/docs/archive并在CLAUDE.md里明確只讀/docs/current下的文檔。同時建立了文檔更新責(zé)任制誰改代碼誰更新對應(yīng)文檔。6.2 Agent的自信幻覺它說改完了其實(shí)沒改Agent有時會報(bào)告已完成修改但實(shí)際上只改了一部分或者改錯了文件。這種情況在任務(wù)復(fù)雜時尤其常見。解決方案不信任Agent的完成報(bào)告一律用git diff驗(yàn)證實(shí)際改動。我們的流程里加了一步改動核對——Agent報(bào)告完成后自動跑git diff --stat人對照計(jì)劃檢查文件列表是否一致。6.3 多Agent的命名沖突兩個Agent并行工作時各自定義了同名的工具函數(shù)合并時直接沖突。更麻煩的是兩個Agent對同一個概念用了不同的命名導(dǎo)致代碼可讀性極差。解決方案多Agent任務(wù)開始前先由人定義命名契約——核心概念的統(tǒng)一命名、公共工具的位置、接口的簽名。Agent只能在這個契約內(nèi)工作不能自行發(fā)明命名。6.4 Token消耗失控有次一個Agent任務(wù)跑了兩個小時消耗了大量token最后發(fā)現(xiàn)它陷入了讀文件→改文件→發(fā)現(xiàn)不對→再讀→再改的循環(huán)。解決方案給Agent設(shè)置最大迭代次數(shù)和token預(yù)算超過閾值自動中止并報(bào)告。同時優(yōu)化CLAUDE.md減少不必要的上下文加載。我們現(xiàn)在的做法是每個任務(wù)預(yù)設(shè)token上限超了就停下來人工介入。6.5 排查鏈路一次典型的Agent翻車復(fù)盤分享一次完整的排查過程。現(xiàn)象是Agent重構(gòu)后某個API的響應(yīng)時間從50ms漲到了800ms。第一步看審計(jì)日志確認(rèn)Agent改了哪些文件。發(fā)現(xiàn)它把原本的緩存邏輯刪了理由是簡化代碼。第二步看Agent的決策理由。日志里寫著緩存層增加了復(fù)雜度且未發(fā)現(xiàn)明確的性能要求。問題找到了——CLAUDE.md里沒有寫該API有性能SLA要求。第三步修復(fù)。恢復(fù)緩存邏輯并在CLAUDE.md的L0層加上所有對外API必須保留緩存層性能要求見/docs/sla.md。第四步舉一反三。檢查CLAUDE.md里還有哪些隱含約束沒寫清楚補(bǔ)充了五條類似的規(guī)則。這次翻車的根因不是Agent能力問題是上下文缺失。Agent不知道性能要求自然做了看起來合理的簡化。這印證了前面說的AI Native的瓶頸在上下文管理。7. 團(tuán)隊(duì)落地從試點(diǎn)到全面推行的節(jié)奏把控7.1 別一上來就全鏈路鋪開我們最開始想一步到位結(jié)果處處出問題團(tuán)隊(duì)怨聲載道。后來調(diào)整為單點(diǎn)突破先在一個小模塊上跑通Plan Mode 編碼 測試的閉環(huán)驗(yàn)證有效后再逐步擴(kuò)展到其他環(huán)節(jié)。推薦的推進(jìn)節(jié)奏是單模塊試點(diǎn)2周→ 單項(xiàng)目推廣1個月→ 跨項(xiàng)目復(fù)制2個月。每個階段都要有明確的驗(yàn)收標(biāo)準(zhǔn)比如Agent產(chǎn)出的代碼一次通過率超過70%。7.2 團(tuán)隊(duì)能力建設(shè)從會用工具到會設(shè)計(jì)工作流AI Native對團(tuán)隊(duì)的能力要求變了。以前強(qiáng)調(diào)代碼寫得快現(xiàn)在更強(qiáng)調(diào)能把任務(wù)拆清楚、能把上下文組織好、能審核Agent的產(chǎn)出。我們做了三件事建立提示詞庫把驗(yàn)證有效的提示詞模板沉淀下來新人直接復(fù)用。定期復(fù)盤會每周花半小時復(fù)盤Agent翻車案例更新CLAUDE.md和流程。角色重新定義資深工程師從寫代碼轉(zhuǎn)向設(shè)計(jì)工作流審核產(chǎn)出初級工程師從執(zhí)行轉(zhuǎn)向監(jiān)督Agent執(zhí)行。7.3 度量怎么知道AI Native真的提效了不能只看感覺快了要有數(shù)據(jù)。我們跟蹤四個指標(biāo)指標(biāo)含義目標(biāo)一次通過率Agent產(chǎn)出無需返工的比例70%人均產(chǎn)出每人每周完成的任務(wù)數(shù)提升50%返工率因Agent問題導(dǎo)致的返工比例15%上下文命中率Agent正確使用上下文的次數(shù)占比85%這些數(shù)據(jù)每周統(tǒng)計(jì)連續(xù)三周不達(dá)標(biāo)就停下來復(fù)盤流程而不是繼續(xù)硬推。8. 我個人的幾條實(shí)操心得跑了大半年AI Native流程最后分享幾條踩坑換來的經(jīng)驗(yàn)都是文檔里不會寫的。第一條CLAUDE.md要當(dāng)代碼一樣維護(hù)。它有版本、有review、有測試。我們每次Agent翻車第一反應(yīng)都是CLAUDE.md是不是缺了什么而不是Agent怎么這么笨。這個思維轉(zhuǎn)變很關(guān)鍵。第二條Plan Mode的審核不能走過場。我見過太多人掃一眼計(jì)劃就點(diǎn)通過結(jié)果執(zhí)行時才發(fā)現(xiàn)方向錯了。審核計(jì)劃的時間至少要是執(zhí)行時間的五分之一。第三條Agent的產(chǎn)出永遠(yuǎn)要驗(yàn)證。不管它說得多自信git diff和測試結(jié)果才是真相。我們團(tuán)隊(duì)有個規(guī)矩Agent說完成之后必須有人跑一遍驗(yàn)證才能標(biāo)記任務(wù)結(jié)束。第四條多Agent不是越多越好。兩個Agent能搞定的事別上三個。每多一個Agent上下文同步成本就翻一倍。我們現(xiàn)在的原則是能單不雙能雙不三。第五條安全兜底要前置。別等出了事故才想起沙箱和權(quán)限。我們現(xiàn)在的做法是任何Agent上線前先過一遍安全檢查清單沙箱配了嗎、權(quán)限分級了嗎、審計(jì)日志開了嗎、危險操作攔截了嗎。這四條缺一條不準(zhǔn)上線。這套流程還在迭代每個月都會有新的坑和新的解法。但核心邏輯沒變過Agent負(fù)責(zé)執(zhí)行人負(fù)責(zé)判斷上下文決定質(zhì)量邊界決定安全。把這兩句話吃透AI Native落地就不會跑偏。