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