實際使用 Claude Code、Cursor 這類 AI 編程工具時最常遇到的問題并不是模型不會寫代碼而是開發(fā)者自己還沒想清楚要做什么。需求越模糊AI 就越容易生成“看起來能用、一改就塌”的代碼。本文要討論的不是某個具體 API 的用法而是一條完整實踐路徑在 AI 編程進入編碼之前先用 COLA 架構(gòu)思想把系統(tǒng)邊界劃定再用 MVP 方法把需求收斂到最小可交付閉環(huán)最后才讓 Claude Code 在這個約束明確的框架里生成代碼。這條路徑適合正在嘗試把 AI 編程引入日常開發(fā)、但發(fā)現(xiàn) AI 產(chǎn)出不穩(wěn)定、返工率偏高的團隊和個人開發(fā)者。1. 為什么 AI 編程的第一步不是寫代碼1.1 AI 編程的主要矛盾已經(jīng)從“代碼生成”轉(zhuǎn)移到“需求約束”很多團隊引入 AI 編程工具時第一反應(yīng)是拿它加速寫代碼。但經(jīng)過一段時間實踐會發(fā)現(xiàn)真正制約產(chǎn)出的環(huán)節(jié)已經(jīng)從鍵盤速度變成了需求質(zhì)量和架構(gòu)約束。一個沒有背景說明、沒有模塊邊界、沒有驗收標(biāo)準(zhǔn)的提示詞到了 Claude Code 手里它會大膽地替你補全所有缺失假設(shè)。這些假設(shè)大部分時候和你的真實業(yè)務(wù)不一致等代碼生成出來你需要花大量時間去做修改和返工?？梢园巡煌崾驹~形式下的 AI 產(chǎn)出質(zhì)量放在一起對比。提示詞形式AI 產(chǎn)出表現(xiàn)返工風(fēng)險“幫我寫一個訂單系統(tǒng)”生成大量類業(yè)務(wù)假設(shè)全來自模型默認理解高“按 COLA 分層創(chuàng)建訂單模塊提供下單接口不接數(shù)據(jù)庫”結(jié)構(gòu)受控范圍受控代碼量適中中需求文檔 MVP 范圍 分層邊界 驗收標(biāo)準(zhǔn)每段代碼對應(yīng)明確需求項后續(xù)可改可測低所以“AI 編程別急著寫代碼”真正的意思是在打開編輯器、輸入提示詞之前先把需求和結(jié)構(gòu)兩條線定下來。代碼生成本身已經(jīng)不再是瓶頸瓶頸是給模型的信息質(zhì)量。1.2 直接讓 Claude Code 寫代碼會發(fā)生什么先描述一個典型現(xiàn)象。讓 Claude Code 直接實現(xiàn)“用戶下單”這個功能它可能會同時生成實體類、枚舉、工具類。數(shù)據(jù)庫表結(jié)構(gòu)和 JPA 或 MyBatis 映射。REST 控制器和 DTO。訂單狀態(tài)流轉(zhuǎn)邏輯。事務(wù)和異常處理。看起來功能完整但問題也隨之出現(xiàn)。你只想要一個 MVP 驗證業(yè)務(wù)流程它卻默認加上了緩存、消息隊列、權(quán)限校驗、分頁等功能這些并不屬于當(dāng)前閉環(huán)。它還會基于自己的訓(xùn)練經(jīng)驗選擇技術(shù)組合不一定符合你項目的現(xiàn)有規(guī)范。更麻煩的是一旦需求調(diào)整這些“多余能力”和“錯誤假設(shè)”交織在一起改動成本遠比從零手寫要高。這并不是 Claude Code 能力不行而是提示詞里缺少三樣?xùn)|西需求范圍、架構(gòu)約束、驗收標(biāo)準(zhǔn)。工具越強輸入的質(zhì)量就越?jīng)Q定輸出的上限。1.3 正確順序MVP 收斂需求COLA 劃定邊界AI 負責(zé)實現(xiàn)推薦的實踐順序是先用 MVP 方法定義“最小可交付閉環(huán)”。明確用戶角色、核心動作、核心數(shù)據(jù)和驗收標(biāo)準(zhǔn)。再用 COLA 架構(gòu)或類似的清晰分層思想定義代碼邊界。哪怕只建空目錄也要讓 AI 知道每一層放什么。最后才進入編碼階段把每一條需求拆成 Claude Code 可以獨立執(zhí)行的子任務(wù)。每完成一個子任務(wù)運行驗證并把這個結(jié)果反饋給 AI作為下一個任務(wù)的前置上下文。這樣 AI 編程就從“猜測你的意圖”變成了“執(zhí)行已經(jīng)清楚定義的任務(wù)”產(chǎn)出質(zhì)量會穩(wěn)定很多。這也是本文整條技術(shù)主線的核心先想清楚再讓 AI 動手。2. Claude Code 環(huán)境準(zhǔn)備與基本用法2.1 Claude Code 是什么它解決什么問題Claude Code 是 Anthropic 推出的命令行 AI 編程代理。它可以讀取項目文件、執(zhí)行命令、創(chuàng)建和修改代碼并在會話中持續(xù)跟進任務(wù)。與聊天式 AI 工具的區(qū)別在于它被設(shè)計成“住在項目里”的工具能感知當(dāng)前目錄結(jié)構(gòu)和文件內(nèi)容更適合完成實際開發(fā)任務(wù)。它解決的核心問題是讓 AI 從“回答問題”變成“做事情”。這帶來開發(fā)效率的提升但也要求使用者在會話開始前就把項目背景、技術(shù)規(guī)范和任務(wù)目標(biāo)寫清楚否則它會把“做事情”變成“自由發(fā)揮”。Claude Code 本身并不理解你團隊的分層約定它只理解你寫在 CLAUDE.md 和提示詞里的規(guī)則。2.2 安裝、登錄與常見前置檢查常見安裝方式是通過 npm 全局安裝npm install -g anthropic-ai/claude-code安裝完成后執(zhí)行claude首次運行需要登錄賬號并確認訂閱方案對 Claude Code 的訪問權(quán)限。如果組織賬號策略限制運行時會提示your organization has disabled claude subscription access for Claude Code這時候需要聯(lián)系團隊管理員開啟訪問權(quán)限而不是繞過限制。注意安裝前先確認 Node.js 版本滿足 Claude Code 的要求常見要求是 Node.js 18 及以上。版本不匹配時可能出現(xiàn)安裝后無法啟動的問題。在 VS Code 中也可以安裝 Claude Code 擴展通過編輯器側(cè)邊欄直接打開會話。命令行和編輯器兩種方式底層走的是同一套能力選擇哪種主要看個人習(xí)慣。實際項目里命令行適合快速執(zhí)行任務(wù)編輯器集成適合邊看代碼邊修改。2.3 CLAUDE.md項目的長期上下文Claude Code 會讀取項目根目錄下名為CLAUDE.md的文件把它當(dāng)作項目的長期說明。這個文件非常適合存放四類信息項目技術(shù)棧和目錄結(jié)構(gòu)。代碼風(fēng)格約定。構(gòu)建、測試、運行命令。團隊約定的架構(gòu)規(guī)則。例如一個 Java 項目可以這樣寫# 項目說明 本模塊采用 COLA 分層的簡化結(jié)構(gòu) - 適配層: controller 包只負責(zé)參數(shù)接收和響應(yīng)封裝 - 應(yīng)用層: service 包負責(zé)用例編排和事務(wù)邊界 - 領(lǐng)域?qū)? domain 包負責(zé)核心業(yè)務(wù)邏輯 - 基礎(chǔ)設(shè)施層: infrastructure 包負責(zé)數(shù)據(jù)庫、緩存等外部依賴 代碼風(fēng)格 - 方法名使用駝峰命名 - 禁止在 controller 中寫業(yè)務(wù)邏輯 - 所有對外接口返回統(tǒng)一 Result 結(jié)構(gòu) 常用命令 - 構(gòu)建: mvn clean package - 測試: mvn test這個文件的作用是讓每一個新會話都能繼承項目約定減少每次對話前重復(fù)交代背景的成本。它也是解決 AI 編程“會話切換丟失上下文”問題的最基礎(chǔ)手段。2.4 用最小命令跑通一次生成在項目目錄下啟動會話cd /path/to/project claude在會話中輸入類似下面的指令在當(dāng)前項目 src/main/java 下創(chuàng)建一個 COLA 分層目錄結(jié)構(gòu) 包括 adapter、app、domain、infrastructure 四個包包名前綴 com.example.order。 每個包先只放一個包說明類暫時不寫業(yè)務(wù)代碼。這條指令明確給出了路徑、結(jié)構(gòu)、包名和范圍Claude Code 生成的代碼更可控。生成完成后用下面命令檢查目錄find src/main/java -type f | sort如果目錄結(jié)構(gòu)符合預(yù)期說明這一輪的任務(wù)定義是有效的。如果不符合不要急著繼續(xù)生成業(yè)務(wù)代碼先修正目錄結(jié)構(gòu)或 CLAUDE.md因為后續(xù)所有任務(wù)都依賴這個基礎(chǔ)。3. COLA 架構(gòu)AI 生成代碼的邊界護欄3.1 COLA 是什么為什么和 AI 編程有關(guān)COLAClean Object-oriented and Layered Architecture是阿里開源的整潔面向?qū)ο蠓謱蛹軜?gòu)核心思想是讓業(yè)務(wù)代碼與技術(shù)實現(xiàn)解耦通過清晰的分層讓系統(tǒng)更容易理解和演進。對于 AI 編程而言COLA 的價值不是理論層面的“優(yōu)雅”而是實操層面的“約束”。AI 模型在沒有約束時傾向于把代碼寫成一個大雜燴控制器里寫數(shù)據(jù)庫查詢、工具類里藏業(yè)務(wù)邏輯、實體直接暴露給前端。COLA 分層之后模型每生成一段代碼都能明確知道它屬于哪一層、能依賴誰、不能依賴誰。約束越清楚模型的默認行為越接近團隊規(guī)范。3.2 四層結(jié)構(gòu)與依賴方向COLA 的經(jīng)典分層可以理解為四層實際項目中常會做裁剪。層名主要職責(zé)典型包或目錄允許依賴適配層接收外部輸入處理 HTTP、DTO、Controlleradapterapp 層應(yīng)用層用例編排、事務(wù)、參數(shù)校驗app/servicedomain 層領(lǐng)域?qū)雍诵臉I(yè)務(wù)規(guī)則、實體、領(lǐng)域服務(wù)domain基礎(chǔ)設(shè)施層接口基礎(chǔ)設(shè)施層數(shù)據(jù)庫、緩存、外部服務(wù)實現(xiàn)infrastructure無上層依賴在 MVP 階段不需要把 COLA 全部機制都引進來。可以只保留分層目錄和依賴方向讓 AI 生成代碼時遵循“controller 不寫業(yè)務(wù)、service 編排用例、domain 放核心邏輯、infrastructure 處理技術(shù)細節(jié)”這條規(guī)則就已經(jīng)能避免大量結(jié)構(gòu)性問題。3.3 為什么分層約束能提升 AI 生成質(zhì)量原因在于 AI 生成代碼時上下文越清晰決策質(zhì)量越高。COLA 分層的目錄結(jié)構(gòu)本身就是一種強上下文。當(dāng)提示詞里出現(xiàn)“請在 app 層實現(xiàn)下單用例”時模型會下意識選擇創(chuàng)建 service 類、調(diào)用 domain 層接口、在方法上標(biāo)記事務(wù)注解而不是把所有代碼塞進 controller。反過來如果提示詞只說“實現(xiàn)下單”模型就需要自己決定類放在哪里、數(shù)據(jù)庫怎么訪問、請求怎么接收選擇一多出錯概率就成倍上升。這等于把架構(gòu)師的經(jīng)驗固化成了 AI 可以讀取的約束文件。即使開發(fā)者沒有為每個類寫詳細設(shè)計只要分層和依賴方向清楚了AI 的默認行為也會更接近工程規(guī)范。3.4 MVP 階段不需要完整落地 COLA強調(diào)一點MVP 階段不要為了架構(gòu)而架構(gòu)。一個最小閉環(huán)可能只有幾個類和一張表這時候引入整套 COLA 的擴展點反而會增加復(fù)雜度。推薦做法是“分層意識先行、完整機制后補”MVP 階段建立 controller、service、domain、infrastructure 四個包結(jié)構(gòu)。在 CLAUDE.md 中寫清楚依賴方向和典型職責(zé)。讓 Claude Code 嚴格按分層生成代碼。等到業(yè)務(wù)復(fù)雜度上升、多個模塊出現(xiàn)公共邏輯時再逐步引入資源庫抽象、領(lǐng)域事件、擴展點等 COLA 完整機制。這樣既能享受分層約束帶來的穩(wěn)定產(chǎn)出又不會讓 MVP 變成重流程的樣板工程。4. 先做 MVP需求收斂和任務(wù)拆分4.1 MVP 不是功能閹割而是最小可交付閉環(huán)很多團隊把 MVP 理解為“少做功能”這是片面的。MVP 的核心是找到一條能驗證業(yè)務(wù)假設(shè)的最小路徑它必須是一個閉環(huán)而不只是一堆刪減后的碎片。以一個電商訂單模塊為例錯誤理解MVP 就是不做支付、不做物流、不做售后先寫個下單接口。正確理解MVP 是“用戶選商品 - 提交訂單 - 校驗庫存 - 扣減庫存 - 生成訂單記錄”這個完整閉環(huán)其他非核心功能先不進入范圍。這個閉環(huán)的價值在于它包含了輸入、業(yè)務(wù)規(guī)則、數(shù)據(jù)持久化和輸出可以完整驗證系統(tǒng)骨架和業(yè)務(wù)流程。AI 在這個閉環(huán)內(nèi)生成的代碼既能跑通又能暴露出架構(gòu)和接口設(shè)計問題。閉環(huán)保留得越完整驗證越有效。4.2 用用戶故事和驗收標(biāo)準(zhǔn)代替模糊描述給 AI 的需求描述不建議寫成大段散文建議使用結(jié)構(gòu)化格式例如用戶故事加驗收標(biāo)準(zhǔn)用戶故事 作為一個消費者 我希望提交訂單時系統(tǒng)能校驗庫存并扣減庫存 以便我完成購買。 驗收標(biāo)準(zhǔn) - 庫存充足時訂單狀態(tài)為已創(chuàng)建庫存數(shù)量減少對應(yīng)購買數(shù)量 - 庫存不足時下單失敗返回明確錯誤信息庫存不變 - 訂單數(shù)據(jù)寫入數(shù)據(jù)庫包含用戶 ID、商品 ID、數(shù)量、狀態(tài)、創(chuàng)建時間這種格式對 AI 非常友好因為每一條驗收標(biāo)準(zhǔn)都可以直接映射到測試用例或代碼邏輯減少歧義。注意驗收標(biāo)準(zhǔn)要寫“可觀察、可驗證”的行為不要寫“性能好、代碼規(guī)范”這類無法自動判斷的表述。4.3 把 MVP 拆成 AI 可執(zhí)行的任務(wù)清單一個完整的 MVP 往往包含多個步驟不要一次性塞給 Claude Code。推薦按任務(wù)粒度拆分任務(wù)編號任務(wù)內(nèi)容輸出T1創(chuàng)建項目結(jié)構(gòu)和分層目錄目錄、pom.xmlT2實現(xiàn)領(lǐng)域?qū)佑唵螌嶓w和庫存校驗規(guī)則Java 類、單元測試T3實現(xiàn)基礎(chǔ)設(shè)施層數(shù)據(jù)庫訪問Repository、SQLT4實現(xiàn)應(yīng)用層下單用例編排Service 類T5實現(xiàn)適配層下單接口Controller、DTOT6編寫集成測試并跑通閉環(huán)測試報告每個任務(wù)完成后立即驗證再進入下一個任務(wù)。這樣可以避免 AI 在一次生成長任務(wù)時產(chǎn)生大量錯誤假設(shè)也讓排錯范圍從“整個項目”縮小到“當(dāng)前任務(wù)”。這個拆分方式也是 AI 編程實踐中最值得養(yǎng)成的習(xí)慣。4.4 給 AI 的上下文顆粒度給 Claude Code 的上下文不需要面面俱到但要包含四類信息項目背景這是什么系統(tǒng)為什么做用戶是誰。技術(shù)約束語言、框架、構(gòu)建工具、數(shù)據(jù)庫、包名。架構(gòu)約束分層結(jié)構(gòu)、依賴方向、統(tǒng)一返回結(jié)構(gòu)。范圍約束本次任務(wù)包含什么明確不包含什么。其中“明確不包含什么”最容易遺漏卻最重要。AI 一旦不知道邊界就會自行擴大范圍生成一堆不屬于 MVP 的代碼。例如可以明確寫“不引入緩存組件”“不做登錄鑒權(quán)”“不創(chuàng)建測試數(shù)據(jù)之外的表”模型就不會往那個方向擴展。5. 實戰(zhàn)用 COLA 加 Claude Code 完成一個訂單 MVP5.1 業(yè)務(wù)場景和 MVP 范圍定義下面用一個最小訂單場景演示完整流程。技術(shù)棧選擇 Spring Boot 3、Java 17、Maven為了演示保持精簡。業(yè)務(wù)范圍是用戶提交訂單系統(tǒng)校驗商品庫存校驗通過后生成訂單并扣減庫存。MVP 明確不包含不做用戶登錄和權(quán)限。不做支付。不做訂單狀態(tài)流轉(zhuǎn)的復(fù)雜狀態(tài)機。不做消息隊列和緩存。這個范圍足夠小卻覆蓋了“外部請求 - 應(yīng)用服務(wù) - 領(lǐng)域規(guī)則 - 持久化”的完整鏈路。5.2 目錄結(jié)構(gòu)設(shè)計按 COLA 簡化分層目錄結(jié)構(gòu)如下order-demo ├── pom.xml ├── CLAUDE.md └── src/main/java/com/example/order ├── adapter │ └── web │ ├── OrderController.java │ └── dto │ ├── CreateOrderRequest.java │ └── CreateOrderResponse.java ├── app │ └── service │ └── OrderServiceImpl.java ├── domain │ ├── model │ │ ├── Order.java │ │ ├── OrderItem.java │ │ └── enums │ │ └── OrderStatus.java │ ├── repository │ │ ├── OrderRepository.java │ │ └── ProductRepository.java │ └── service │ └── InventoryService.java └── infrastructure ├── persistence │ ├── OrderRepositoryImpl.java │ └── ProductRepositoryImpl.java └── config └── DatabaseConfig.java這個結(jié)構(gòu)不是 COLA 的完整形態(tài)但已經(jīng)具備“適配層、應(yīng)用層、領(lǐng)域?qū)印⒒A(chǔ)設(shè)施層”的基本邊界。AI 生成代碼時可以明確知道每個類的歸屬。5.3 給 Claude Code 的工單示例在 CLAUDE.md 中寫入項目說明后會話中提交第一個任務(wù)時可以這樣描述工單 T1 在目錄 order-demo 中初始化 Spring Boot 3 Java 17 的 Maven 項目。 依賴只保留 spring-boot-starter-web、spring-boot-starter-data-jpa、h2、 lombok、spring-boot-starter-test。 同時創(chuàng)建 COLA 分層目錄 com.example.order.adapter.web com.example.order.app.service com.example.order.domain.model com.example.order.domain.repository com.example.order.domain.service com.example.order.infrastructure.persistence 不要創(chuàng)建其他配置文件和業(yè)務(wù)代碼。這條指令的優(yōu)點是依賴范圍明確目錄明確還明確說了“不要創(chuàng)建其他內(nèi)容”。范圍約束寫得越清楚AI 越不會自由發(fā)揮。5.4 核心層代碼生成要點第二批任務(wù)是生成核心代碼。以領(lǐng)域?qū)訛槔慰梢赃@樣寫工單 T2 在 com.example.order.domain.model 下實現(xiàn) 1. Order 實體字段包括 id、userId、status、totalPrice、createTime、items。 2. OrderItem 實體字段包括 id、productId、quantity、price。 3. OrderStatus 枚舉枚舉值 CREATED、PAID、CANCELLED。 在 com.example.order.domain.service 下實現(xiàn) InventoryService 接口 CheckResult checkStock(Long productId, Integer quantity); void deductStock(Long productId, Integer quantity); 領(lǐng)域?qū)硬灰蕾?Spring Data不使用任何注解。這里刻意強調(diào)“領(lǐng)域?qū)硬灰蕾?Spring Data”是為了讓 AI 生成的領(lǐng)域?qū)ο蟊３旨夹g(shù)無關(guān)這也是 COLA 架構(gòu)的關(guān)鍵實踐。領(lǐng)域?qū)右坏┍?JPA 注解、Spring Bean 注解污染后續(xù)做單元測試和架構(gòu)調(diào)整都會很吃力。應(yīng)用層負責(zé)用例編排工單 T4 在 com.example.order.app.service 下實現(xiàn) OrderService 接口和 OrderServiceImpl。 OrderServiceImpl 負責(zé)下單用例編排 1. 根據(jù)商品 ID 查詢商品。 2. 校驗庫存。 3. 創(chuàng)建訂單和訂單項狀態(tài)為 CREATED。 4. 調(diào)用庫存服務(wù)扣減庫存。 5. 保存訂單。 事務(wù)邊界放在應(yīng)用層使用 Transactional。 不在應(yīng)用層寫 SQL不直接操作數(shù)據(jù)庫。適配層只做接口暴露工單 T5 在 com.example.order.adapter.web 下實現(xiàn) OrderController。 提供 POST /api/orders 接口接收 CreateOrderRequest 調(diào)用應(yīng)用層 OrderService 下單返回 CreateOrderResponse。 Controller 中不寫業(yè)務(wù)邏輯只做參數(shù)接收、調(diào)用和響應(yīng)封裝。每個工單都限制了任務(wù)邊界和代碼歸屬層Claude Code 在單點任務(wù)上的表現(xiàn)會穩(wěn)定很多。5.5 運行驗證與預(yù)期結(jié)果全部任務(wù)執(zhí)行完畢后運行項目mvn spring-boot:run在另一個終端調(diào)用下單接口curl -X POST http://localhost:8080/api/orders \ -H Content-Type: application/json \ -d {productId:1,quantity:2,userId:100}預(yù)期看到返回結(jié)果{ orderId: 1, status: CREATED, message: 下單成功 }再驗證庫存不足場景curl -X POST http://localhost:8080/api/orders \ -H Content-Type: application/json \ -d {productId:1,quantity:9999,userId:100}預(yù)期返回明確錯誤信息且訂單不落庫。這兩個測試分別覆蓋了正常分支和異常分支是 MVP 閉環(huán)驗證的基本要求。注意不要只驗證程序能啟動還要驗證正常輸入、異常輸入和數(shù)據(jù)庫狀態(tài)是否符合預(yù)期。只有啟動成功但接口行為錯誤的項目在 AI 編程場景里非常常見。6. 常見問題與排查路徑6.1 Claude Code 安裝、版本與賬號問題Claude Code 常見問題集中在這幾類問題現(xiàn)象常見原因檢查方式處理建議安裝后執(zhí)行 claude 提示命令不存在npm 全局目錄不在 PATH執(zhí)行 npm config get prefix把全局 bin 目錄加入 PATH啟動時提示模型版本不識別客戶端版本和模型配置不一致執(zhí)行 claude --version 確認版本更新 Claude Code并檢查模型配置是否指向受支持版本提示組織禁用訪問組織賬號未開放 Claude Code 權(quán)限查看完整提示文本聯(lián)系團隊管理員開啟權(quán)限不要繞過限制提示區(qū)域不可用當(dāng)前環(huán)境不在支持范圍內(nèi)結(jié)合部署環(huán)境判斷確認部署環(huán)境支持情況不要嘗試繞過限制npm 安裝緩慢或失敗網(wǎng)絡(luò)或 registry 配置問題檢查 npm config get registry切換為團隊維護的鏡像源后重試排查順序建議從輸入命令是否正確開始再檢查路徑和權(quán)限然后看版本和配置最后看網(wǎng)絡(luò)環(huán)境。不要一上來就認為模型能力有問題。6.2 新開會話丟失上下文記憶這是 AI 編程工具最常見的困擾之一。Claude Code 的上下文保存在會話內(nèi)新建會話后之前的對話內(nèi)容不會自動繼承。解決辦法不是讓工具記住而是把關(guān)鍵信息外置化把項目技術(shù)棧、架構(gòu)規(guī)則、常用命令寫入 CLAUDE.md。把當(dāng)前任務(wù)拆成工單并在每個工單描述中寫明前置任務(wù)編號。關(guān)鍵決策寫進項目的設(shè)計文檔目錄作為后續(xù)會話的輸入。這樣即使會話中斷也能在新會話中快速恢復(fù)上下文。把這個機制理解成“給 AI 寫交接文檔”而不是依賴模型記憶。6.3 Token 消耗過大AI 編程工具消耗大量 token 通常有三種原因一次交給模型的任務(wù)范圍過大讓它反復(fù)生成和回退。項目文件太多模型每次讀取上下文都非常昂貴。會話中反復(fù)讓模型重新讀文件、重新生成。對應(yīng)處理方式任務(wù)拆小一次只完成一個可驗證單元。在 CLAUDE.md 中明確告訴模型忽略哪些目錄例如 target、node_modules、build。頻繁使用新會話并結(jié)合 CLAUDE.md 重建上下文。在提示詞中限制輸出范圍例如“只輸出 Java 代碼不輸出解釋”。其中“不輸出解釋”對控制 token 消耗非常有效因為模型默認會輸出大段說明文字。6.4 AI 生成代碼不符合分層要求即使寫了 CLAUDE.mdAI 仍可能在生成代碼時越過邊界例如在 Controller 里寫業(yè)務(wù)邏輯。處理方式檢查是否在任務(wù)描述中明確了該文件的層級歸屬。檢查 CLAUDE.md 中的依賴方向是否被模型準(zhǔn)確讀取。讓 AI 重新生成該文件并明確要求遵循分層規(guī)則。在代碼評審階段增加一條分層檢查規(guī)則人工或腳本檢查依賴方向。更推薦的做法是在工單描述中直接寫“這個文件屬于 domain 層禁止引用 Spring、禁止操作數(shù)據(jù)庫”把約束前置到生成階段而不是在生成后補救。7. 最佳實踐與可復(fù)用檢查清單7.1 需求文檔檢查清單[ ] 是否只有一個明確的用戶角色和核心動作[ ] 是否每一條驗收標(biāo)準(zhǔn)都可觀察、可測試[ ] 是否明確本次包含的內(nèi)容[ ] 是否明確不包含的范圍[ ] 是否給出了輸入輸出樣例需求文檔是給 AI 的第一道約束這五項都滿足后AI 的返工率會明顯下降。7.2 任務(wù)拆分檢查清單[ ] 每個任務(wù)是否有獨立輸出物[ ] 每個任務(wù)完成后是否能運行驗證[ ] 任務(wù)之間是否有清晰的前置依賴關(guān)系[ ] 單個任務(wù)的控制范圍是否足夠小[ ] 是否避免了“一次性完成整個模塊”的巨型任務(wù)推薦把任務(wù)控制在“一個文件或一組強相關(guān)文件”的粒度最壞情況也能快速定位問題。7.3 COLA 分層代碼檢查清單[ ] Controller 是否只做參數(shù)接收和響應(yīng)封裝[ ] Service 是否只做用例編排不寫 SQL[ ] Domain 層是否保持技術(shù)無關(guān)不依賴 Spring Data[ ] Infrastructure 層是否實現(xiàn)了領(lǐng)域?qū)佣x的接口[ ] 依賴方向是否從外向內(nèi)沒有反向依賴[ ] 是否沒有在工具類里堆積不屬于當(dāng)前用例的業(yè)務(wù)邏輯這六項可以做成人工評審模板也可以寫成腳本檢查 import 方向作為 AI 生成代碼后的自動防線。7.4 從 MVP 走向生產(chǎn)環(huán)境MVP 跑通后進入生產(chǎn)環(huán)境前還需要補齊這些能力數(shù)據(jù)庫連接池、日志、監(jiān)控是否配置完整。異常處理是否區(qū)分業(yè)務(wù)異常和系統(tǒng)異常。是否補充了權(quán)限校驗、請求限流、參數(shù)校驗等安全能力。是否把配置外置化而不是硬編碼在代碼中。是否準(zhǔn)備回滾方案和發(fā)布檢查單。是否為核心流程補充了集成測試和回歸測試。MVP 解決的是“業(yè)務(wù)閉環(huán)能否成立”生產(chǎn)化解決的是“系統(tǒng)能否穩(wěn)定運行”。兩者不要混在一起做這也是“先做 MVP”的另一個原因先解決正確性問題再解決健壯性問題。AI 編程的產(chǎn)出質(zhì)量本質(zhì)上由你給它的約束質(zhì)量決定。COLA 提供架構(gòu)約束MVP 提供范圍約束CLAUDE.md 提供項目約定工單描述提供任務(wù)邊界。四層約束疊加起來Claude Code 才能從“大膽猜測者”變成“可預(yù)期執(zhí)行者”。下一步可以從兩個方向擴展一是把訂單場景升級為完整狀態(tài)機引入 COLA 的狀態(tài)機機制和領(lǐng)域事件二是把單模塊的 MVP 實踐復(fù)制到多個模塊形成團隊統(tǒng)一的 AI 編程協(xié)作規(guī)范。對新手來說最好的練習(xí)不是去研究更復(fù)雜的提示詞技巧而是把一個非常小的 MVP按本文的工單方式完整跑一遍感受約束前后 AI 產(chǎn)出質(zhì)量的差異。