落地手冊：CLAUDE.md、Skill 與 Hook 實戰(zhàn))
1. AI Native 團隊開發(fā)落地從概念到可執(zhí)行手冊“AI Native”這個詞最近半年被聊爛了但真正落到團隊日常開發(fā)里大多數(shù)人還是一頭霧水。我所在的團隊從去年底開始全面轉向 AI Native 研發(fā)范式踩了無數(shù)坑也攢下了一套能跑通的完整流程。這篇文章不聊虛的只講我們怎么把 AI Native 從口號變成每天在用的開發(fā)手冊——包括 SDLC 怎么改、CLAUDE.md 怎么寫、Skill 和 Hook 怎么設計、團隊協(xié)作怎么落地。如果你正在帶團隊或者自己想把 AI 真正嵌進開發(fā)流程這篇內(nèi)容可以直接抄作業(yè)。先對齊一下認知AI Native 團隊不是“用 AI 寫代碼”這么簡單。它意味著整個軟件開發(fā)生命周期SDLC的每個環(huán)節(jié)——需求拆解、方案設計、編碼、測試、部署、運維——都要重新思考“人和 AI 怎么分工”。我們團隊從最初的“AI 輔助編碼”進化到現(xiàn)在的“AI 驅(qū)動開發(fā)”核心變化在于人負責定義問題和驗收標準AI 負責執(zhí)行和迭代。這個轉變聽起來簡單做起來涉及大量流程重構和工具鏈搭建。這篇文章適合三類人一是正在推動團隊 AI 轉型的技術負責人二是想在自己項目里引入 AI Native 流程的獨立開發(fā)者三是對 Skill、Hook、CLAUDE.md 這些概念好奇但不知道怎么用的工程師。我會從整體設計思路講起然后拆解每個核心環(huán)節(jié)的實操細節(jié)最后分享我們踩過的坑和排查技巧。全文基于我們團隊的真實實踐所有配置和代碼都可以直接參考。2. 整體設計與思路拆解2.1 為什么傳統(tǒng) SDLC 在 AI Native 團隊里跑不通傳統(tǒng) SDLC 的核心假設是“人寫代碼機器執(zhí)行”。需求評審完開發(fā)排期編碼測試上線。每個環(huán)節(jié)的產(chǎn)出物都是給人看的——PRD 文檔、技術方案、代碼 Review 意見。但在 AI Native 團隊里AI 不只是執(zhí)行者它還是協(xié)作者。如果繼續(xù)用傳統(tǒng)流程你會發(fā)現(xiàn)兩個致命問題第一AI 生成的代碼沒人 Review 得過來質(zhì)量參差不齊第二人和 AI 的上下文不同步AI 不知道項目的歷史決策和約束條件反復犯同樣的錯誤。我們最初的做法是讓每個人自己用 AI 工具寫代碼結果就是代碼風格混亂、重復邏輯遍地、測試覆蓋率暴跌。后來我們意識到問題不在于 AI 能力不夠而在于我們沒有給 AI 建立“團隊上下文”。就像新員工入職需要培訓一樣AI 也需要一套明確的規(guī)則和知識庫。這就是 CLAUDE.md 和 Skill 體系要解決的核心問題。2.2 AI Native SDLC 的四個核心支柱我們最終定下來的 AI Native SDLC 圍繞四個支柱構建上下文管理、技能封裝、自動化鉤子、人機驗收閉環(huán)。這四個支柱分別對應四個關鍵工具CLAUDE.md 負責上下文管理Skill 負責技能封裝Hook 負責自動化觸發(fā)驗收清單負責人機分工。為什么是這四個因為我們在實踐中發(fā)現(xiàn)AI 在開發(fā)流程中出問題90% 的情況可以歸為四類不知道項目背景上下文缺失、不知道怎么執(zhí)行特定任務技能缺失、該自動化的環(huán)節(jié)還在手動鉤子缺失、產(chǎn)出質(zhì)量沒人把關驗收缺失。把這四個問題解決了AI Native 流程就能跑通。2.3 工具選型背后的考量市面上 AI 編程工具很多我們最終選擇以 Claude 為核心構建這套體系原因有三個第一Claude 的長上下文能力在理解大型項目時優(yōu)勢明顯第二CLAUDE.md 這個約定俗成的配置文件讓團隊知識沉淀有了標準載體第三Skill 和 Hook 的擴展機制足夠靈活能覆蓋從編碼到部署的全流程。當然這不是說其他工具不能用。Codex、DeepSeek 等工具我們也在部分環(huán)節(jié)使用比如 Codex 在論文輔助和短劇腳本生成上有獨特優(yōu)勢DeepSeek 在內(nèi)網(wǎng)部署場景下更可控。關鍵是建立一套與工具無關的流程框架工具只是執(zhí)行層。我們的原則是流程定義清楚工具可以替換。3. 核心細節(jié)解析與實操要點3.1 CLAUDE.md給 AI 的團隊入職手冊CLAUDE.md 是整個體系的基石。你可以把它理解為“給 AI 看的項目 README”。我們團隊的 CLAUDE.md 放在項目根目錄每次 AI 參與開發(fā)時都會自動讀取。這份文件寫得好不好直接決定 AI 產(chǎn)出的質(zhì)量。我們的 CLAUDE.md 包含六個部分項目概述、技術棧說明、目錄結構約定、編碼規(guī)范、常用命令、禁止事項。項目概述用三句話講清楚這個項目是干什么的、服務誰、核心價值是什么。技術棧說明列出所有依賴和版本特別標注哪些庫不能用比如因為許可證問題。目錄結構約定告訴 AI 新文件應該放哪里避免它亂建目錄。編碼規(guī)范包括命名約定、注釋要求、錯誤處理模式。常用命令列出構建、測試、部署的命令。禁止事項是最重要的部分明確寫出“不要做什么”。注意CLAUDE.md 不要寫太長控制在 500 行以內(nèi)。太長了 AI 反而抓不住重點。我們的做法是把詳細規(guī)范拆到單獨的 Skill 文件里CLAUDE.md 只保留最核心的約束。實操心得CLAUDE.md 要隨著項目演進持續(xù)更新。我們每周五下午花 15 分鐘回顧本周 AI 犯過的錯誤把新的約束條件加進去。比如有一次 AI 反復在測試文件里用真實數(shù)據(jù)庫連接我們就在禁止事項里加了一條“測試必須使用 mock 數(shù)據(jù)庫”。加完之后這個問題再沒出現(xiàn)過。3.2 Skill 體系把重復任務封裝成可調(diào)用技能Skill 是 AI Native 團隊提效的關鍵。簡單說Skill 就是把一類任務的執(zhí)行方法封裝成 AI 可以調(diào)用的模塊。我們團隊目前維護了 20 多個 Skill覆蓋從代碼生成到文檔編寫的各個環(huán)節(jié)。Skill 的設計原則是“單一職責”。一個 Skill 只做一件事比如“生成 API 接口代碼”、“編寫單元測試”、“生成數(shù)據(jù)庫遷移腳本”。每個 Skill 包含三部分觸發(fā)條件、執(zhí)行步驟、驗收標準。觸發(fā)條件告訴 AI 什么時候該用這個 Skill執(zhí)行步驟是具體的操作指南驗收標準是產(chǎn)出物必須滿足的條件。以我們的“API 接口生成 Skill”為例。觸發(fā)條件是“當需要新增 REST API 接口時”。執(zhí)行步驟包括檢查是否已存在類似接口、按照項目規(guī)范生成 Controller/Service/Repository 三層代碼、生成對應的 DTO 和 VO、生成單元測試、更新 API 文檔。驗收標準是代碼通過編譯、測試覆蓋率不低于 80%、Swagger 文檔能正常渲染。Skill 的存放位置我們統(tǒng)一放在.ai/skills/目錄下每個 Skill 一個 Markdown 文件。文件命名用 kebab-case比如api-endpoint-generator.md。這樣 AI 在需要時可以通過文件名快速定位。3.3 Hook 機制讓自動化在正確的時機觸發(fā)Hook 是很多人容易忽略但極其重要的部分。Hook 的本質(zhì)是“在特定事件發(fā)生時自動執(zhí)行預定義動作”。在 AI Native 開發(fā)流程中Hook 負責把各個孤立的環(huán)節(jié)串成自動化流水線。我們團隊常用的 Hook 有三類代碼提交前 Hook、代碼生成后 Hook、部署前 Hook。代碼提交前 Hook 會自動運行 lint 和單元測試不通過就阻止提交。代碼生成后 Hook 會自動格式化代碼并運行靜態(tài)分析。部署前 Hook 會檢查環(huán)境變量配置和數(shù)據(jù)庫遷移狀態(tài)。Hook 的配置我們放在.ai/hooks/目錄下用 YAML 格式定義。一個典型的 Hook 配置包含觸發(fā)事件、執(zhí)行命令、失敗處理策略。比如代碼提交前 Hook 的配置是觸發(fā)事件為 pre-commit執(zhí)行命令為npm run lint npm run test:unit失敗處理策略為 block。提示Hook 的執(zhí)行時間要控制好。我們最初把完整的集成測試放在 pre-commit Hook 里結果每次提交要等 5 分鐘大家怨聲載道。后來改成 pre-commit 只跑 lint 和單元測試集成測試放到 CI 流水線里體驗好很多。3.4 人機驗收閉環(huán)誰對最終質(zhì)量負責AI Native 團隊最容易出問題的地方就是驗收環(huán)節(jié)。很多人覺得 AI 生成的代碼“看起來沒問題”就直接合并了結果線上事故頻發(fā)。我們的做法是建立明確的人機驗收分工AI 負責自檢人負責終審。AI 自檢包括代碼能編譯、測試能通過、符合 CLAUDE.md 里的編碼規(guī)范、沒有引入新的依賴沖突。這些檢查通過 Hook 自動完成。人負責終審的內(nèi)容包括業(yè)務邏輯是否正確、邊界條件是否覆蓋、性能是否可接受、安全是否有隱患。這些是 AI 目前還不擅長的領域。我們要求每個 PR 必須有人 Review而且 Review 意見要具體到行。如果 Review 發(fā)現(xiàn)的問題屬于“AI 反復犯的錯誤”就要把這條規(guī)則補充到 CLAUDE.md 或?qū)?Skill 里。這樣就形成了一個持續(xù)改進的閉環(huán)。4. 實操過程與核心環(huán)節(jié)實現(xiàn)4.1 從零搭建 AI Native 開發(fā)環(huán)境的完整步驟假設你現(xiàn)在要在一個新項目里落地這套體系可以按照以下步驟操作。整個過程大約需要半天時間但后續(xù)收益巨大。第一步初始化項目結構。在項目根目錄創(chuàng)建.ai/目錄里面包含skills/、hooks/、context/三個子目錄。skills/存放技能文件hooks/存放鉤子配置context/存放項目背景知識。第二步編寫 CLAUDE.md。按照前面說的六個部分組織內(nèi)容。剛開始可以簡單一些隨著項目推進逐步完善。重點是“禁止事項”部分要寫清楚這是防止 AI 犯錯的第一道防線。第三步創(chuàng)建第一批 Skill。建議從最常用的三個開始代碼生成 Skill、測試編寫 Skill、文檔生成 Skill。每個 Skill 按照觸發(fā)條件、執(zhí)行步驟、驗收標準的格式編寫。第四步配置 Hook。先配置 pre-commit Hook確保代碼提交前經(jīng)過基本檢查。然后配置 post-generation Hook確保 AI 生成的代碼自動格式化。第五步建立驗收清單。為不同類型的任務制定驗收標準比如新功能開發(fā)、Bug 修復、重構、文檔更新各自的驗收要點不同。4.2 一個完整的 AI Native 開發(fā)流程實例讓我用一個真實案例展示這套體系怎么運轉。上周我們需要給系統(tǒng)新增一個“用戶積分查詢”接口。首先我在對話中告訴 AI“請使用 api-endpoint-generator Skill 新增用戶積分查詢接口路徑為 GET /api/v1/users/{userId}/points?！盇I 自動讀取了 CLAUDE.md 和對應的 Skill 文件然后開始執(zhí)行。它先檢查了現(xiàn)有代碼發(fā)現(xiàn)已經(jīng)有 UserController于是決定在現(xiàn)有 Controller 里新增方法而不是新建文件。接著它按照項目規(guī)范生成了 Controller 方法、Service 方法、Repository 查詢、DTO 類、單元測試。生成過程中post-generation Hook 自動運行了代碼格式化。生成完成后pre-commit Hook 自動運行 lint 和單元測試全部通過。然后我進行人工 Review發(fā)現(xiàn)它沒有處理“用戶不存在”的邊界情況。我在 PR 里留言指出這個問題AI 根據(jù)我的反饋補充了異常處理邏輯。最后合并前我更新了 CLAUDE.md加了一條“所有查詢接口必須處理資源不存在的場景”。這樣下次 AI 生成類似代碼時就會自動處理這個邊界條件。4.3 關鍵參數(shù)配置與計算過程在配置 Hook 時有幾個參數(shù)需要仔細考慮。以測試覆蓋率閾值這個參數(shù)為例我們最初設置的是 90%結果發(fā)現(xiàn)很多 AI 生成的代碼為了湊覆蓋率寫了大量無意義的測試。后來我們調(diào)整為 80%但增加了“關鍵路徑必須 100% 覆蓋”的約束。具體計算方式是先識別出核心業(yè)務邏輯代碼比如支付、權限、數(shù)據(jù)一致性相關的代碼這些代碼要求 100% 分支覆蓋。非核心代碼比如工具類、DTO 轉換要求 80% 行覆蓋。整體覆蓋率不低于 85%。這個分層策略比一刀切的閾值更合理。另一個關鍵參數(shù)是 Hook 的超時時間。我們設置 pre-commit Hook 超時為 60 秒超過就中斷并提示“檢查超時請優(yōu)化或拆分提交”。這個值是根據(jù)團隊平均提交頻率和 CI 資源算出來的。太短了容易誤中斷太長了影響開發(fā)體驗。4.4 團隊協(xié)作中的上下文同步機制AI Native 團隊的一個特殊挑戰(zhàn)是每個人本地的 AI 上下文可能不一致。張三的 CLAUDE.md 更新了李四還沒拉取導致 AI 行為不一致。我們的解決方案是把.ai/目錄納入版本控制并且要求每次修改 CLAUDE.md 或 Skill 文件都必須走 PR 流程。另外我們建立了一個“AI 行為日志”機制。每次 AI 生成代碼后自動記錄使用了哪些 Skill、觸發(fā)了哪些 Hook、生成了哪些文件。這些日志匯總到每周的團隊回顧會上分析。如果發(fā)現(xiàn)某個 Skill 被頻繁使用但產(chǎn)出質(zhì)量不高就重點優(yōu)化那個 Skill。注意不要讓 AI 直接修改 CLAUDE.md 或 Skill 文件。這些文件必須由人編寫和審核。AI 可以建議修改但最終決定權在人。這是保證流程可控的關鍵。5. 常見問題與排查技巧實錄5.1 AI 不按 Skill 規(guī)范執(zhí)行怎么辦這是最常見的問題。AI 有時候會忽略 Skill 里的步驟按自己的理解生成代碼。排查思路是先檢查 Skill 文件的觸發(fā)條件是否足夠明確。如果觸發(fā)條件寫的是“當需要生成 API 時”AI 可能理解成“任何 API 相關操作”。改成“當需要新增 REST API 接口時”就明確多了。如果觸發(fā)條件沒問題檢查 Skill 文件的執(zhí)行步驟是否過于籠統(tǒng)。比如“生成測試”就不如“為每個 public 方法生成至少一個正常場景測試和一個異常場景測試”明確。步驟越具體AI 執(zhí)行越準確。還有一個技巧是在 CLAUDE.md 里加一條強制規(guī)則“執(zhí)行任何 Skill 前必須先完整閱讀該 Skill 文件并確認理解?！边@能顯著提高 Skill 的執(zhí)行準確率。5.2 Hook 執(zhí)行失敗但錯誤信息不明確Hook 失敗時AI 往往只返回一個籠統(tǒng)的錯誤碼。我們的做法是在 Hook 配置里加上詳細的錯誤輸出。比如 lint 失敗時要求輸出具體的文件、行號和錯誤原因。測試失敗時要求輸出失敗的測試用例名稱和斷言差異。另外建議給每個 Hook 配置一個“調(diào)試模式”。在調(diào)試模式下Hook 會輸出完整的執(zhí)行日志包括執(zhí)行的命令、環(huán)境變量、耗時。我們團隊在排查 Hook 問題時會臨時開啟調(diào)試模式定位到具體環(huán)節(jié)后再關閉。5.3 AI 生成的代碼風格不一致這個問題通常是因為 CLAUDE.md 里的編碼規(guī)范不夠具體。我們最初只寫了“遵循項目現(xiàn)有代碼風格”結果 AI 生成的代碼風格五花八門。后來我們改成了具體的規(guī)則變量名用 camelCase常量用 UPPER_SNAKE_CASE類名用 PascalCase縮進用 2 個空格字符串用單引號等等。還有一個有效手段是提供代碼示例。在 CLAUDE.md 里放一段“標準代碼示例”AI 會模仿這個示例的風格。我們放了一個標準的 Controller 方法和一個標準的測試方法作為參考效果立竿見影。5.4 常見問題速查表問題現(xiàn)象可能原因排查方法解決方案AI 忽略 Skill 步驟觸發(fā)條件模糊檢查 Skill 文件觸發(fā)條件改為更具體的條件描述Hook 頻繁誤報閾值設置過嚴查看 Hook 執(zhí)行日志調(diào)整閾值或增加白名單代碼風格混亂規(guī)范不夠具體對比生成代碼與規(guī)范補充具體規(guī)則和示例上下文不同步配置文件未提交檢查 git status將 .ai/ 目錄納入版本控制測試覆蓋率虛高存在無意義測試審查測試用例質(zhì)量改為關鍵路徑覆蓋策略AI 反復犯同樣錯誤規(guī)則未沉淀回顧歷史 PR 評論將規(guī)則補充到 CLAUDE.md5.5 獨家避坑技巧第一個技巧給 AI 設置“思考時間”。我們在 Skill 里加了一步“在執(zhí)行前先列出你的執(zhí)行計劃”讓 AI 先輸出計劃再執(zhí)行。這樣如果計劃有問題人可以在執(zhí)行前就糾正避免浪費。第二個技巧建立“錯誤模式庫”。我們把 AI 犯過的典型錯誤整理成一個文檔放在.ai/context/error-patterns.md。每次 AI 生成代碼前都會讀取這個文件避免重蹈覆轍。這個文檔目前積累了 30 多條錯誤模式效果非常好。第三個技巧定期“重置”上下文。AI 的上下文窗口是有限的長時間對話后它會遺忘早期內(nèi)容。我們的做法是每完成一個功能模塊就開一個新的對話只把必要的上下文CLAUDE.md 和當前任務相關的 Skill帶過去。這樣 AI 的注意力更集中產(chǎn)出質(zhì)量更高。第四個技巧用 AI 檢查 AI。我們配置了一個“代碼審查 Skill”讓 AI 先自己審查一遍生成的代碼找出潛在問題。雖然不能完全替代人工 Review但能過濾掉 60% 以上的低級問題大大減輕了人的負擔。6. 工具鏈擴展與進階玩法6.1 多工具協(xié)同的配置策略我們團隊不是只用一種 AI 工具。Claude 負責主力開發(fā)Codex 負責論文輔助和創(chuàng)意類任務DeepSeek 負責內(nèi)網(wǎng)部署場景。關鍵是怎么讓這些工具共享同一套上下文。我們的做法是把 CLAUDE.md 和 Skill 文件設計成工具無關的格式。CLAUDE.md 就是純 Markdown任何 AI 工具都能讀取。Skill 文件也是 Markdown只是觸發(fā)條件和執(zhí)行步驟的描述方式略有不同。我們?yōu)槊總€工具維護一個適配層把通用的 Skill 文件轉換成該工具能理解的格式。比如 Codex 的 Skill 文件需要額外的“示例輸入輸出”部分我們就在適配層里自動生成這部分內(nèi)容。DeepSeek 的 Skill 文件需要更詳細的步驟說明我們就在適配層里展開細節(jié)。這樣核心知識只維護一份適配層自動處理差異。6.2 內(nèi)網(wǎng)部署場景的特殊處理有些項目需要在內(nèi)網(wǎng)服務器上部署 AI 開發(fā)環(huán)境這時候會遇到網(wǎng)絡隔離、權限限制等問題。我們的經(jīng)驗是提前把所有依賴打包好包括 AI 工具的離線安裝包、Skill 文件、Hook 腳本。在內(nèi)網(wǎng)部署時先搭建一個本地鏡像源然后按照標準流程安裝。權限問題是最頭疼的。我們遇到過 DeepSeek 的 Skill 讀取文件時報權限錯誤排查后發(fā)現(xiàn)是文件系統(tǒng)的安全描述符配置問題。解決方案是用管理員權限重新配置文件訪問控制列表確保 AI 工具的運行賬戶有讀取權限。具體命令是使用icacls工具授予權限而不是直接修改文件所有者。提示內(nèi)網(wǎng)部署時建議把 AI 工具的日志級別調(diào)到 debug方便排查問題。但正式運行時要調(diào)回 info避免日志文件過大。6.3 Skill 的版本管理與迭代Skill 文件也需要版本管理。我們的做法是給每個 Skill 文件加一個版本號放在文件頭部。每次修改 Skill 都要更新版本號并在文件末尾記錄修改日志。這樣當 AI 行為異常時可以快速定位是不是 Skill 版本變更導致的。我們還建立了一個 Skill 質(zhì)量評分機制。每個 Skill 從“使用頻率”、“產(chǎn)出質(zhì)量”、“人工修改率”三個維度評分。評分低的 Skill 要么優(yōu)化要么廢棄。每季度做一次 Skill 清理保持 Skill 庫的精簡和高效。6.4 從 AI Native 到 AI Driven 的演進路徑我們團隊目前處于“AI Native”階段下一步目標是“AI Driven”。區(qū)別在于AI Native 是人主導、AI 執(zhí)行AI Driven 是 AI 主導、人監(jiān)督。具體來說AI Driven 階段 AI 會主動發(fā)現(xiàn)問題、提出方案、執(zhí)行修復人只負責審批和驗收。要實現(xiàn)這個演進需要三個前提條件第一Skill 庫足夠完善覆蓋 90% 以上的日常任務第二Hook 體系足夠健全能自動捕獲和分類問題第三驗收標準足夠明確AI 能自主判斷產(chǎn)出是否合格。我們目前完成了大約 70%預計還需要半年時間才能完全過渡。7. 一些實操后的個人體會這套體系跑了大半年最大的體會是AI Native 不是買幾個 AI 工具就完事了它是一場流程變革。工具只是載體核心是重新定義人和 AI 的分工邊界。我們團隊從最初的“AI 寫代碼、人改代碼”進化到現(xiàn)在的“人定義問題、AI 執(zhí)行、人驗收”效率提升了大約 3 倍但前期投入的流程建設時間也相當可觀。另一個體會是CLAUDE.md 和 Skill 文件的質(zhì)量直接決定 AI 產(chǎn)出的上限。我們最開始寫的 CLAUDE.md 只有 50 行AI 產(chǎn)出質(zhì)量很差。后來擴充到 300 行加上 20 多個 SkillAI 產(chǎn)出質(zhì)量有了質(zhì)的飛躍。這個過程沒有捷徑就是不斷踩坑、不斷補充規(guī)則。最后分享一個小心得不要試圖讓 AI 一次完成太復雜的任務。把大任務拆成小任務每個任務對應一個 Skill逐個執(zhí)行。這樣不僅產(chǎn)出質(zhì)量高而且出問題時容易定位。我們現(xiàn)在的做法是一個功能模塊拆成 5-8 個子任務每個子任務單獨執(zhí)行和驗收。雖然看起來步驟多了但整體效率反而更高因為返工少了。 AI Native 團隊開發(fā)落地手冊：CLAUDE.md、Skill 與 Hook 實戰(zhàn)
1. AI Native 團隊開發(fā)落地從概念到可執(zhí)行手冊“AI Native”這個詞最近半年被聊爛了但真正落到團隊日常開發(fā)里大多數(shù)人還是一頭霧水。我所在的團隊從去年底開始全面轉向 AI Native 研發(fā)范式踩了無數(shù)坑也攢下了一套能跑通的完整流程。這篇文章不聊虛的只講我們怎么把 AI Native 從口號變成每天在用的開發(fā)手冊——包括 SDLC 怎么改、CLAUDE.md 怎么寫、Skill 和 Hook 怎么設計、團隊協(xié)作怎么落地。如果你正在帶團隊或者自己想把 AI 真正嵌進開發(fā)流程這篇內(nèi)容可以直接抄作業(yè)。先對齊一下認知AI Native 團隊不是“用 AI 寫代碼”這么簡單。它意味著整個軟件開發(fā)生命周期SDLC的每個環(huán)節(jié)——需求拆解、方案設計、編碼、測試、部署、運維——都要重新思考“人和 AI 怎么分工”。我們團隊從最初的“AI 輔助編碼”進化到現(xiàn)在的“AI 驅(qū)動開發(fā)”核心變化在于人負責定義問題和驗收標準AI 負責執(zhí)行和迭代。這個轉變聽起來簡單做起來涉及大量流程重構和工具鏈搭建。這篇文章適合三類人一是正在推動團隊 AI 轉型的技術負責人二是想在自己項目里引入 AI Native 流程的獨立開發(fā)者三是對 Skill、Hook、CLAUDE.md 這些概念好奇但不知道怎么用的工程師。我會從整體設計思路講起然后拆解每個核心環(huán)節(jié)的實操細節(jié)最后分享我們踩過的坑和排查技巧。全文基于我們團隊的真實實踐所有配置和代碼都可以直接參考。2. 整體設計與思路拆解2.1 為什么傳統(tǒng) SDLC 在 AI Native 團隊里跑不通傳統(tǒng) SDLC 的核心假設是“人寫代碼機器執(zhí)行”。需求評審完開發(fā)排期編碼測試上線。每個環(huán)節(jié)的產(chǎn)出物都是給人看的——PRD 文檔、技術方案、代碼 Review 意見。但在 AI Native 團隊里AI 不只是執(zhí)行者它還是協(xié)作者。如果繼續(xù)用傳統(tǒng)流程你會發(fā)現(xiàn)兩個致命問題第一AI 生成的代碼沒人 Review 得過來質(zhì)量參差不齊第二人和 AI 的上下文不同步AI 不知道項目的歷史決策和約束條件反復犯同樣的錯誤。我們最初的做法是讓每個人自己用 AI 工具寫代碼結果就是代碼風格混亂、重復邏輯遍地、測試覆蓋率暴跌。后來我們意識到問題不在于 AI 能力不夠而在于我們沒有給 AI 建立“團隊上下文”。就像新員工入職需要培訓一樣AI 也需要一套明確的規(guī)則和知識庫。這就是 CLAUDE.md 和 Skill 體系要解決的核心問題。2.2 AI Native SDLC 的四個核心支柱我們最終定下來的 AI Native SDLC 圍繞四個支柱構建上下文管理、技能封裝、自動化鉤子、人機驗收閉環(huán)。這四個支柱分別對應四個關鍵工具CLAUDE.md 負責上下文管理Skill 負責技能封裝Hook 負責自動化觸發(fā)驗收清單負責人機分工。為什么是這四個因為我們在實踐中發(fā)現(xiàn)AI 在開發(fā)流程中出問題90% 的情況可以歸為四類不知道項目背景上下文缺失、不知道怎么執(zhí)行特定任務技能缺失、該自動化的環(huán)節(jié)還在手動鉤子缺失、產(chǎn)出質(zhì)量沒人把關驗收缺失。把這四個問題解決了AI Native 流程就能跑通。2.3 工具選型背后的考量市面上 AI 編程工具很多我們最終選擇以 Claude 為核心構建這套體系原因有三個第一Claude 的長上下文能力在理解大型項目時優(yōu)勢明顯第二CLAUDE.md 這個約定俗成的配置文件讓團隊知識沉淀有了標準載體第三Skill 和 Hook 的擴展機制足夠靈活能覆蓋從編碼到部署的全流程。當然這不是說其他工具不能用。Codex、DeepSeek 等工具我們也在部分環(huán)節(jié)使用比如 Codex 在論文輔助和短劇腳本生成上有獨特優(yōu)勢DeepSeek 在內(nèi)網(wǎng)部署場景下更可控。關鍵是建立一套與工具無關的流程框架工具只是執(zhí)行層。我們的原則是流程定義清楚工具可以替換。3. 核心細節(jié)解析與實操要點3.1 CLAUDE.md給 AI 的團隊入職手冊CLAUDE.md 是整個體系的基石。你可以把它理解為“給 AI 看的項目 README”。我們團隊的 CLAUDE.md 放在項目根目錄每次 AI 參與開發(fā)時都會自動讀取。這份文件寫得好不好直接決定 AI 產(chǎn)出的質(zhì)量。我們的 CLAUDE.md 包含六個部分項目概述、技術棧說明、目錄結構約定、編碼規(guī)范、常用命令、禁止事項。項目概述用三句話講清楚這個項目是干什么的、服務誰、核心價值是什么。技術棧說明列出所有依賴和版本特別標注哪些庫不能用比如因為許可證問題。目錄結構約定告訴 AI 新文件應該放哪里避免它亂建目錄。編碼規(guī)范包括命名約定、注釋要求、錯誤處理模式。常用命令列出構建、測試、部署的命令。禁止事項是最重要的部分明確寫出“不要做什么”。注意CLAUDE.md 不要寫太長控制在 500 行以內(nèi)。太長了 AI 反而抓不住重點。我們的做法是把詳細規(guī)范拆到單獨的 Skill 文件里CLAUDE.md 只保留最核心的約束。實操心得CLAUDE.md 要隨著項目演進持續(xù)更新。我們每周五下午花 15 分鐘回顧本周 AI 犯過的錯誤把新的約束條件加進去。比如有一次 AI 反復在測試文件里用真實數(shù)據(jù)庫連接我們就在禁止事項里加了一條“測試必須使用 mock 數(shù)據(jù)庫”。加完之后這個問題再沒出現(xiàn)過。3.2 Skill 體系把重復任務封裝成可調(diào)用技能Skill 是 AI Native 團隊提效的關鍵。簡單說Skill 就是把一類任務的執(zhí)行方法封裝成 AI 可以調(diào)用的模塊。我們團隊目前維護了 20 多個 Skill覆蓋從代碼生成到文檔編寫的各個環(huán)節(jié)。Skill 的設計原則是“單一職責”。一個 Skill 只做一件事比如“生成 API 接口代碼”、“編寫單元測試”、“生成數(shù)據(jù)庫遷移腳本”。每個 Skill 包含三部分觸發(fā)條件、執(zhí)行步驟、驗收標準。觸發(fā)條件告訴 AI 什么時候該用這個 Skill執(zhí)行步驟是具體的操作指南驗收標準是產(chǎn)出物必須滿足的條件。以我們的“API 接口生成 Skill”為例。觸發(fā)條件是“當需要新增 REST API 接口時”。執(zhí)行步驟包括檢查是否已存在類似接口、按照項目規(guī)范生成 Controller/Service/Repository 三層代碼、生成對應的 DTO 和 VO、生成單元測試、更新 API 文檔。驗收標準是代碼通過編譯、測試覆蓋率不低于 80%、Swagger 文檔能正常渲染。Skill 的存放位置我們統(tǒng)一放在.ai/skills/目錄下每個 Skill 一個 Markdown 文件。文件命名用 kebab-case比如api-endpoint-generator.md。這樣 AI 在需要時可以通過文件名快速定位。3.3 Hook 機制讓自動化在正確的時機觸發(fā)Hook 是很多人容易忽略但極其重要的部分。Hook 的本質(zhì)是“在特定事件發(fā)生時自動執(zhí)行預定義動作”。在 AI Native 開發(fā)流程中Hook 負責把各個孤立的環(huán)節(jié)串成自動化流水線。我們團隊常用的 Hook 有三類代碼提交前 Hook、代碼生成后 Hook、部署前 Hook。代碼提交前 Hook 會自動運行 lint 和單元測試不通過就阻止提交。代碼生成后 Hook 會自動格式化代碼并運行靜態(tài)分析。部署前 Hook 會檢查環(huán)境變量配置和數(shù)據(jù)庫遷移狀態(tài)。Hook 的配置我們放在.ai/hooks/目錄下用 YAML 格式定義。一個典型的 Hook 配置包含觸發(fā)事件、執(zhí)行命令、失敗處理策略。比如代碼提交前 Hook 的配置是觸發(fā)事件為 pre-commit執(zhí)行命令為npm run lint npm run test:unit失敗處理策略為 block。提示Hook 的執(zhí)行時間要控制好。我們最初把完整的集成測試放在 pre-commit Hook 里結果每次提交要等 5 分鐘大家怨聲載道。后來改成 pre-commit 只跑 lint 和單元測試集成測試放到 CI 流水線里體驗好很多。3.4 人機驗收閉環(huán)誰對最終質(zhì)量負責AI Native 團隊最容易出問題的地方就是驗收環(huán)節(jié)。很多人覺得 AI 生成的代碼“看起來沒問題”就直接合并了結果線上事故頻發(fā)。我們的做法是建立明確的人機驗收分工AI 負責自檢人負責終審。AI 自檢包括代碼能編譯、測試能通過、符合 CLAUDE.md 里的編碼規(guī)范、沒有引入新的依賴沖突。這些檢查通過 Hook 自動完成。人負責終審的內(nèi)容包括業(yè)務邏輯是否正確、邊界條件是否覆蓋、性能是否可接受、安全是否有隱患。這些是 AI 目前還不擅長的領域。我們要求每個 PR 必須有人 Review而且 Review 意見要具體到行。如果 Review 發(fā)現(xiàn)的問題屬于“AI 反復犯的錯誤”就要把這條規(guī)則補充到 CLAUDE.md 或?qū)?Skill 里。這樣就形成了一個持續(xù)改進的閉環(huán)。4. 實操過程與核心環(huán)節(jié)實現(xiàn)4.1 從零搭建 AI Native 開發(fā)環(huán)境的完整步驟假設你現(xiàn)在要在一個新項目里落地這套體系可以按照以下步驟操作。整個過程大約需要半天時間但后續(xù)收益巨大。第一步初始化項目結構。在項目根目錄創(chuàng)建.ai/目錄里面包含skills/、hooks/、context/三個子目錄。skills/存放技能文件hooks/存放鉤子配置context/存放項目背景知識。第二步編寫 CLAUDE.md。按照前面說的六個部分組織內(nèi)容。剛開始可以簡單一些隨著項目推進逐步完善。重點是“禁止事項”部分要寫清楚這是防止 AI 犯錯的第一道防線。第三步創(chuàng)建第一批 Skill。建議從最常用的三個開始代碼生成 Skill、測試編寫 Skill、文檔生成 Skill。每個 Skill 按照觸發(fā)條件、執(zhí)行步驟、驗收標準的格式編寫。第四步配置 Hook。先配置 pre-commit Hook確保代碼提交前經(jīng)過基本檢查。然后配置 post-generation Hook確保 AI 生成的代碼自動格式化。第五步建立驗收清單。為不同類型的任務制定驗收標準比如新功能開發(fā)、Bug 修復、重構、文檔更新各自的驗收要點不同。4.2 一個完整的 AI Native 開發(fā)流程實例讓我用一個真實案例展示這套體系怎么運轉。上周我們需要給系統(tǒng)新增一個“用戶積分查詢”接口。首先我在對話中告訴 AI“請使用 api-endpoint-generator Skill 新增用戶積分查詢接口路徑為 GET /api/v1/users/{userId}/points?！盇I 自動讀取了 CLAUDE.md 和對應的 Skill 文件然后開始執(zhí)行。它先檢查了現(xiàn)有代碼發(fā)現(xiàn)已經(jīng)有 UserController于是決定在現(xiàn)有 Controller 里新增方法而不是新建文件。接著它按照項目規(guī)范生成了 Controller 方法、Service 方法、Repository 查詢、DTO 類、單元測試。生成過程中post-generation Hook 自動運行了代碼格式化。生成完成后pre-commit Hook 自動運行 lint 和單元測試全部通過。然后我進行人工 Review發(fā)現(xiàn)它沒有處理“用戶不存在”的邊界情況。我在 PR 里留言指出這個問題AI 根據(jù)我的反饋補充了異常處理邏輯。最后合并前我更新了 CLAUDE.md加了一條“所有查詢接口必須處理資源不存在的場景”。這樣下次 AI 生成類似代碼時就會自動處理這個邊界條件。4.3 關鍵參數(shù)配置與計算過程在配置 Hook 時有幾個參數(shù)需要仔細考慮。以測試覆蓋率閾值這個參數(shù)為例我們最初設置的是 90%結果發(fā)現(xiàn)很多 AI 生成的代碼為了湊覆蓋率寫了大量無意義的測試。后來我們調(diào)整為 80%但增加了“關鍵路徑必須 100% 覆蓋”的約束。具體計算方式是先識別出核心業(yè)務邏輯代碼比如支付、權限、數(shù)據(jù)一致性相關的代碼這些代碼要求 100% 分支覆蓋。非核心代碼比如工具類、DTO 轉換要求 80% 行覆蓋。整體覆蓋率不低于 85%。這個分層策略比一刀切的閾值更合理。另一個關鍵參數(shù)是 Hook 的超時時間。我們設置 pre-commit Hook 超時為 60 秒超過就中斷并提示“檢查超時請優(yōu)化或拆分提交”。這個值是根據(jù)團隊平均提交頻率和 CI 資源算出來的。太短了容易誤中斷太長了影響開發(fā)體驗。4.4 團隊協(xié)作中的上下文同步機制AI Native 團隊的一個特殊挑戰(zhàn)是每個人本地的 AI 上下文可能不一致。張三的 CLAUDE.md 更新了李四還沒拉取導致 AI 行為不一致。我們的解決方案是把.ai/目錄納入版本控制并且要求每次修改 CLAUDE.md 或 Skill 文件都必須走 PR 流程。另外我們建立了一個“AI 行為日志”機制。每次 AI 生成代碼后自動記錄使用了哪些 Skill、觸發(fā)了哪些 Hook、生成了哪些文件。這些日志匯總到每周的團隊回顧會上分析。如果發(fā)現(xiàn)某個 Skill 被頻繁使用但產(chǎn)出質(zhì)量不高就重點優(yōu)化那個 Skill。注意不要讓 AI 直接修改 CLAUDE.md 或 Skill 文件。這些文件必須由人編寫和審核。AI 可以建議修改但最終決定權在人。這是保證流程可控的關鍵。5. 常見問題與排查技巧實錄5.1 AI 不按 Skill 規(guī)范執(zhí)行怎么辦這是最常見的問題。AI 有時候會忽略 Skill 里的步驟按自己的理解生成代碼。排查思路是先檢查 Skill 文件的觸發(fā)條件是否足夠明確。如果觸發(fā)條件寫的是“當需要生成 API 時”AI 可能理解成“任何 API 相關操作”。改成“當需要新增 REST API 接口時”就明確多了。如果觸發(fā)條件沒問題檢查 Skill 文件的執(zhí)行步驟是否過于籠統(tǒng)。比如“生成測試”就不如“為每個 public 方法生成至少一個正常場景測試和一個異常場景測試”明確。步驟越具體AI 執(zhí)行越準確。還有一個技巧是在 CLAUDE.md 里加一條強制規(guī)則“執(zhí)行任何 Skill 前必須先完整閱讀該 Skill 文件并確認理解?！边@能顯著提高 Skill 的執(zhí)行準確率。5.2 Hook 執(zhí)行失敗但錯誤信息不明確Hook 失敗時AI 往往只返回一個籠統(tǒng)的錯誤碼。我們的做法是在 Hook 配置里加上詳細的錯誤輸出。比如 lint 失敗時要求輸出具體的文件、行號和錯誤原因。測試失敗時要求輸出失敗的測試用例名稱和斷言差異。另外建議給每個 Hook 配置一個“調(diào)試模式”。在調(diào)試模式下Hook 會輸出完整的執(zhí)行日志包括執(zhí)行的命令、環(huán)境變量、耗時。我們團隊在排查 Hook 問題時會臨時開啟調(diào)試模式定位到具體環(huán)節(jié)后再關閉。5.3 AI 生成的代碼風格不一致這個問題通常是因為 CLAUDE.md 里的編碼規(guī)范不夠具體。我們最初只寫了“遵循項目現(xiàn)有代碼風格”結果 AI 生成的代碼風格五花八門。后來我們改成了具體的規(guī)則變量名用 camelCase常量用 UPPER_SNAKE_CASE類名用 PascalCase縮進用 2 個空格字符串用單引號等等。還有一個有效手段是提供代碼示例。在 CLAUDE.md 里放一段“標準代碼示例”AI 會模仿這個示例的風格。我們放了一個標準的 Controller 方法和一個標準的測試方法作為參考效果立竿見影。5.4 常見問題速查表問題現(xiàn)象可能原因排查方法解決方案AI 忽略 Skill 步驟觸發(fā)條件模糊檢查 Skill 文件觸發(fā)條件改為更具體的條件描述Hook 頻繁誤報閾值設置過嚴查看 Hook 執(zhí)行日志調(diào)整閾值或增加白名單代碼風格混亂規(guī)范不夠具體對比生成代碼與規(guī)范補充具體規(guī)則和示例上下文不同步配置文件未提交檢查 git status將 .ai/ 目錄納入版本控制測試覆蓋率虛高存在無意義測試審查測試用例質(zhì)量改為關鍵路徑覆蓋策略AI 反復犯同樣錯誤規(guī)則未沉淀回顧歷史 PR 評論將規(guī)則補充到 CLAUDE.md5.5 獨家避坑技巧第一個技巧給 AI 設置“思考時間”。我們在 Skill 里加了一步“在執(zhí)行前先列出你的執(zhí)行計劃”讓 AI 先輸出計劃再執(zhí)行。這樣如果計劃有問題人可以在執(zhí)行前就糾正避免浪費。第二個技巧建立“錯誤模式庫”。我們把 AI 犯過的典型錯誤整理成一個文檔放在.ai/context/error-patterns.md。每次 AI 生成代碼前都會讀取這個文件避免重蹈覆轍。這個文檔目前積累了 30 多條錯誤模式效果非常好。第三個技巧定期“重置”上下文。AI 的上下文窗口是有限的長時間對話后它會遺忘早期內(nèi)容。我們的做法是每完成一個功能模塊就開一個新的對話只把必要的上下文CLAUDE.md 和當前任務相關的 Skill帶過去。這樣 AI 的注意力更集中產(chǎn)出質(zhì)量更高。第四個技巧用 AI 檢查 AI。我們配置了一個“代碼審查 Skill”讓 AI 先自己審查一遍生成的代碼找出潛在問題。雖然不能完全替代人工 Review但能過濾掉 60% 以上的低級問題大大減輕了人的負擔。6. 工具鏈擴展與進階玩法6.1 多工具協(xié)同的配置策略我們團隊不是只用一種 AI 工具。Claude 負責主力開發(fā)Codex 負責論文輔助和創(chuàng)意類任務DeepSeek 負責內(nèi)網(wǎng)部署場景。關鍵是怎么讓這些工具共享同一套上下文。我們的做法是把 CLAUDE.md 和 Skill 文件設計成工具無關的格式。CLAUDE.md 就是純 Markdown任何 AI 工具都能讀取。Skill 文件也是 Markdown只是觸發(fā)條件和執(zhí)行步驟的描述方式略有不同。我們?yōu)槊總€工具維護一個適配層把通用的 Skill 文件轉換成該工具能理解的格式。比如 Codex 的 Skill 文件需要額外的“示例輸入輸出”部分我們就在適配層里自動生成這部分內(nèi)容。DeepSeek 的 Skill 文件需要更詳細的步驟說明我們就在適配層里展開細節(jié)。這樣核心知識只維護一份適配層自動處理差異。6.2 內(nèi)網(wǎng)部署場景的特殊處理有些項目需要在內(nèi)網(wǎng)服務器上部署 AI 開發(fā)環(huán)境這時候會遇到網(wǎng)絡隔離、權限限制等問題。我們的經(jīng)驗是提前把所有依賴打包好包括 AI 工具的離線安裝包、Skill 文件、Hook 腳本。在內(nèi)網(wǎng)部署時先搭建一個本地鏡像源然后按照標準流程安裝。權限問題是最頭疼的。我們遇到過 DeepSeek 的 Skill 讀取文件時報權限錯誤排查后發(fā)現(xiàn)是文件系統(tǒng)的安全描述符配置問題。解決方案是用管理員權限重新配置文件訪問控制列表確保 AI 工具的運行賬戶有讀取權限。具體命令是使用icacls工具授予權限而不是直接修改文件所有者。提示內(nèi)網(wǎng)部署時建議把 AI 工具的日志級別調(diào)到 debug方便排查問題。但正式運行時要調(diào)回 info避免日志文件過大。6.3 Skill 的版本管理與迭代Skill 文件也需要版本管理。我們的做法是給每個 Skill 文件加一個版本號放在文件頭部。每次修改 Skill 都要更新版本號并在文件末尾記錄修改日志。這樣當 AI 行為異常時可以快速定位是不是 Skill 版本變更導致的。我們還建立了一個 Skill 質(zhì)量評分機制。每個 Skill 從“使用頻率”、“產(chǎn)出質(zhì)量”、“人工修改率”三個維度評分。評分低的 Skill 要么優(yōu)化要么廢棄。每季度做一次 Skill 清理保持 Skill 庫的精簡和高效。6.4 從 AI Native 到 AI Driven 的演進路徑我們團隊目前處于“AI Native”階段下一步目標是“AI Driven”。區(qū)別在于AI Native 是人主導、AI 執(zhí)行AI Driven 是 AI 主導、人監(jiān)督。具體來說AI Driven 階段 AI 會主動發(fā)現(xiàn)問題、提出方案、執(zhí)行修復人只負責審批和驗收。要實現(xiàn)這個演進需要三個前提條件第一Skill 庫足夠完善覆蓋 90% 以上的日常任務第二Hook 體系足夠健全能自動捕獲和分類問題第三驗收標準足夠明確AI 能自主判斷產(chǎn)出是否合格。我們目前完成了大約 70%預計還需要半年時間才能完全過渡。7. 一些實操后的個人體會這套體系跑了大半年最大的體會是AI Native 不是買幾個 AI 工具就完事了它是一場流程變革。工具只是載體核心是重新定義人和 AI 的分工邊界。我們團隊從最初的“AI 寫代碼、人改代碼”進化到現(xiàn)在的“人定義問題、AI 執(zhí)行、人驗收”效率提升了大約 3 倍但前期投入的流程建設時間也相當可觀。另一個體會是CLAUDE.md 和 Skill 文件的質(zhì)量直接決定 AI 產(chǎn)出的上限。我們最開始寫的 CLAUDE.md 只有 50 行AI 產(chǎn)出質(zhì)量很差。后來擴充到 300 行加上 20 多個 SkillAI 產(chǎn)出質(zhì)量有了質(zhì)的飛躍。這個過程沒有捷徑就是不斷踩坑、不斷補充規(guī)則。最后分享一個小心得不要試圖讓 AI 一次完成太復雜的任務。把大任務拆成小任務每個任務對應一個 Skill逐個執(zhí)行。這樣不僅產(chǎn)出質(zhì)量高而且出問題時容易定位。我們現(xiàn)在的做法是一個功能模塊拆成 5-8 個子任務每個子任務單獨執(zhí)行和驗收。雖然看起來步驟多了但整體效率反而更高因為返工少了。