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