實(shí)際使用 Claude Code、Cursor 這類 AI 編程工具時(shí)最常遇到的問(wèn)題并不是模型不會(huì)寫代碼而是開(kāi)發(fā)者自己還沒(méi)想清楚要做什么。需求越模糊AI 就越容易生成“看起來(lái)能用、一改就塌”的代碼。本文要討論的不是某個(gè)具體 API 的用法而是一條完整實(shí)踐路徑在 AI 編程進(jìn)入編碼之前先用 COLA 架構(gòu)思想把系統(tǒng)邊界劃定再用 MVP 方法把需求收斂到最小可交付閉環(huán)最后才讓 Claude Code 在這個(gè)約束明確的框架里生成代碼。這條路徑適合正在嘗試把 AI 編程引入日常開(kāi)發(fā)、但發(fā)現(xiàn) AI 產(chǎn)出不穩(wěn)定、返工率偏高的團(tuán)隊(duì)和個(gè)人開(kāi)發(fā)者。1. 為什么 AI 編程的第一步不是寫代碼1.1 AI 編程的主要矛盾已經(jīng)從“代碼生成”轉(zhuǎn)移到“需求約束”很多團(tuán)隊(duì)引入 AI 編程工具時(shí)第一反應(yīng)是拿它加速寫代碼。但經(jīng)過(guò)一段時(shí)間實(shí)踐會(huì)發(fā)現(xiàn)真正制約產(chǎn)出的環(huán)節(jié)已經(jīng)從鍵盤速度變成了需求質(zhì)量和架構(gòu)約束。一個(gè)沒(méi)有背景說(shuō)明、沒(méi)有模塊邊界、沒(méi)有驗(yàn)收標(biāo)準(zhǔn)的提示詞到了 Claude Code 手里它會(huì)大膽地替你補(bǔ)全所有缺失假設(shè)。這些假設(shè)大部分時(shí)候和你的真實(shí)業(yè)務(wù)不一致等代碼生成出來(lái)你需要花大量時(shí)間去做修改和返工。可以把不同提示詞形式下的 AI 產(chǎn)出質(zhì)量放在一起對(duì)比。提示詞形式AI 產(chǎn)出表現(xiàn)返工風(fēng)險(xiǎn)“幫我寫一個(gè)訂單系統(tǒng)”生成大量類業(yè)務(wù)假設(shè)全來(lái)自模型默認(rèn)理解高“按 COLA 分層創(chuàng)建訂單模塊提供下單接口不接數(shù)據(jù)庫(kù)”結(jié)構(gòu)受控范圍受控代碼量適中中需求文檔 MVP 范圍 分層邊界 驗(yàn)收標(biāo)準(zhǔn)每段代碼對(duì)應(yīng)明確需求項(xiàng)后續(xù)可改可測(cè)低所以“AI 編程別急著寫代碼”真正的意思是在打開(kāi)編輯器、輸入提示詞之前先把需求和結(jié)構(gòu)兩條線定下來(lái)。代碼生成本身已經(jīng)不再是瓶頸瓶頸是給模型的信息質(zhì)量。1.2 直接讓 Claude Code 寫代碼會(huì)發(fā)生什么先描述一個(gè)典型現(xiàn)象。讓 Claude Code 直接實(shí)現(xiàn)“用戶下單”這個(gè)功能它可能會(huì)同時(shí)生成實(shí)體類、枚舉、工具類。數(shù)據(jù)庫(kù)表結(jié)構(gòu)和 JPA 或 MyBatis 映射。REST 控制器和 DTO。訂單狀態(tài)流轉(zhuǎn)邏輯。事務(wù)和異常處理。看起來(lái)功能完整但問(wèn)題也隨之出現(xiàn)。你只想要一個(gè) MVP 驗(yàn)證業(yè)務(wù)流程它卻默認(rèn)加上了緩存、消息隊(duì)列、權(quán)限校驗(yàn)、分頁(yè)等功能這些并不屬于當(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 編程就從“猜測(cè)你的意圖”變成了“執(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 是什么它解決什么問(wèn)題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í)際開(kāi)發(fā)任務(wù)。它解決的核心問(wèn)題是讓 AI 從“回答問(wèn)題”變成“做事情”。這帶來(lái)開(kāi)發(fā)效率的提升但也要求使用者在會(huì)話開(kāi)始前就把項(xiàng)目背景、技術(shù)規(guī)范和任務(wù)目標(biāo)寫清楚否則它會(huì)把“做事情”變成“自由發(fā)揮”。Claude Code 本身并不理解你團(tuán)隊(duì)的分層約定它只理解你寫在 CLAUDE.md 和提示詞里的規(guī)則。2.2 安裝、登錄與常見(jiàn)前置檢查常見(jiàn)安裝方式是通過(guò) npm 全局安裝npm install -g anthropic-ai/claude-code安裝完成后執(zhí)行claude首次運(yùn)行需要登錄賬號(hào)并確認(rèn)訂閱方案對(duì) Claude Code 的訪問(wèn)權(quán)限。如果組織賬號(hào)策略限制運(yùn)行時(shí)會(huì)提示your organization has disabled claude subscription access for Claude Code這時(shí)候需要聯(lián)系團(tuán)隊(duì)管理員開(kāi)啟訪問(wèn)權(quán)限而不是繞過(guò)限制。注意安裝前先確認(rèn) Node.js 版本滿足 Claude Code 的要求常見(jiàn)要求是 Node.js 18 及以上。版本不匹配時(shí)可能出現(xiàn)安裝后無(wú)法啟動(dòng)的問(wèn)題。在 VS Code 中也可以安裝 Claude Code 擴(kuò)展通過(guò)編輯器側(cè)邊欄直接打開(kāi)會(huì)話。命令行和編輯器兩種方式底層走的是同一套能力選擇哪種主要看個(gè)人習(xí)慣。實(shí)際項(xiàng)目里命令行適合快速執(zhí)行任務(wù)編輯器集成適合邊看代碼邊修改。2.3 CLAUDE.md項(xiàng)目的長(zhǎng)期上下文Claude Code 會(huì)讀取項(xiàng)目根目錄下名為CLAUDE.md的文件把它當(dāng)作項(xiàng)目的長(zhǎng)期說(shuō)明。這個(gè)文件非常適合存放四類信息項(xiàng)目技術(shù)棧和目錄結(jié)構(gòu)。代碼風(fēng)格約定。構(gòu)建、測(cè)試、運(yùn)行命令。團(tuán)隊(duì)約定的架構(gòu)規(guī)則。例如一個(gè) Java 項(xiàng)目可以這樣寫# 項(xiàng)目說(shuō)明 本模塊采用 COLA 分層的簡(jiǎn)化結(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ù)庫(kù)、緩存等外部依賴 代碼風(fēng)格 - 方法名使用駝峰命名 - 禁止在 controller 中寫業(yè)務(wù)邏輯 - 所有對(duì)外接口返回統(tǒng)一 Result 結(jié)構(gòu) 常用命令 - 構(gòu)建: mvn clean package - 測(cè)試: mvn test這個(gè)文件的作用是讓每一個(gè)新會(huì)話都能繼承項(xiàng)目約定減少每次對(duì)話前重復(fù)交代背景的成本。它也是解決 AI 編程“會(huì)話切換丟失上下文”問(wèn)題的最基礎(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è)包說(shuō)明類暫時(shí)不寫業(yè)務(wù)代碼。這條指令明確給出了路徑、結(jié)構(gòu)、包名和范圍Claude Code 生成的代碼更可控。生成完成后用下面命令檢查目錄find src/main/java -type f | sort如果目錄結(jié)構(gòu)符合預(yù)期說(shuō)明這一輪的任務(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是阿里開(kāi)源的整潔面向?qū)ο蠓謱蛹軜?gòu)核心思想是讓業(yè)務(wù)代碼與技術(shù)實(shí)現(xiàn)解耦通過(guò)清晰的分層讓系統(tǒng)更容易理解和演進(jìn)。對(duì)于 AI 編程而言COLA 的價(jià)值不是理論層面的“優(yōu)雅”而是實(shí)操層面的“約束”。AI 模型在沒(méi)有約束時(shí)傾向于把代碼寫成一個(gè)大雜燴控制器里寫數(shù)據(jù)庫(kù)查詢、工具類里藏業(yè)務(wù)邏輯、實(shí)體直接暴露給前端。COLA 分層之后模型每生成一段代碼都能明確知道它屬于哪一層、能依賴誰(shuí)、不能依賴誰(shuí)。約束越清楚模型的默認(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ù)庫(kù)、緩存、外部服務(wù)實(shí)現(xiàn)infrastructure無(wú)上層依賴在 MVP 階段不需要把 COLA 全部機(jī)制都引進(jìn)來(lái)。可以只保留分層目錄和依賴方向讓 AI 生成代碼時(shí)遵循“controller 不寫業(yè)務(wù)、service 編排用例、domain 放核心邏輯、infrastructure 處理技術(shù)細(xì)節(jié)”這條規(guī)則就已經(jīng)能避免大量結(jié)構(gòu)性問(wèn)題。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。反過(guò)來(lái)如果提示詞只說(shuō)“實(shí)現(xiàn)下單”模型就需要自己決定類放在哪里、數(shù)據(jù)庫(kù)怎么訪問(wèn)、請(qǐng)求怎么接收選擇一多出錯(cuò)概率就成倍上升。這等于把架構(gòu)師的經(jīng)驗(yàn)固化成了 AI 可以讀取的約束文件。即使開(kāi)發(fā)者沒(méi)有為每個(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í)再逐步引入資源庫(kù)抽象、領(lǐng)域事件、擴(kuò)展點(diǎn)等 COLA 完整機(jī)制。這樣既能享受分層約束帶來(lái)的穩(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)庫(kù)存 - 扣減庫(kù)存 - 生成訂單記錄”這個(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ì)問(wèn)題。閉環(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)庫(kù)存并扣減庫(kù)存 以便我完成購(gòu)買。 驗(yàn)收標(biāo)準(zhǔn) - 庫(kù)存充足時(shí)訂單狀態(tài)為已創(chuàng)建庫(kù)存數(shù)量減少對(duì)應(yīng)購(gòu)買數(shù)量 - 庫(kù)存不足時(shí)下單失敗返回明確錯(cuò)誤信息庫(kù)存不變 - 訂單數(shù)據(jù)寫入數(shù)據(jù)庫(kù)包含用戶 ID、商品 ID、數(shù)量、狀態(tài)、創(chuàng)建時(shí)間這種格式對(duì) AI 非常友好因?yàn)槊恳粭l驗(yàn)收標(biāo)準(zhǔn)都可以直接映射到測(cè)試用例或代碼邏輯減少歧義。注意驗(yàn)收標(biāo)準(zhǔn)要寫“可觀察、可驗(yàn)證”的行為不要寫“性能好、代碼規(guī)范”這類無(wú)法自動(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í)體和庫(kù)存校驗(yàn)規(guī)則Java 類、單元測(cè)試T3實(shí)現(xiàn)基礎(chǔ)設(shè)施層數(shù)據(jù)庫(kù)訪問(wèn)Repository、SQLT4實(shí)現(xiàn)應(yīng)用層下單用例編排Service 類T5實(shí)現(xiàn)適配層下單接口Controller、DTOT6編寫集成測(cè)試并跑通閉環(huán)測(cè)試報(bào)告每個(gè)任務(wù)完成后立即驗(yàn)證再進(jìn)入下一個(gè)任務(wù)。這樣可以避免 AI 在一次生成長(zhǎng)任務(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)為什么做用戶是誰(shuí)。技術(shù)約束語(yǔ)言、框架、構(gòu)建工具、數(shù)據(jù)庫(kù)、包名。架構(gòu)約束分層結(jié)構(gòu)、依賴方向、統(tǒng)一返回結(jié)構(gòu)。范圍約束本次任務(wù)包含什么明確不包含什么。其中“明確不包含什么”最容易遺漏卻最重要。AI 一旦不知道邊界就會(huì)自行擴(kuò)大范圍生成一堆不屬于 MVP 的代碼。例如可以明確寫“不引入緩存組件”“不做登錄鑒權(quán)”“不創(chuàng)建測(cè)試數(shù)據(jù)之外的表”模型就不會(huì)往那個(gè)方向擴(kuò)展。5. 實(shí)戰(zhàn)用 COLA 加 Claude Code 完成一個(gè)訂單 MVP5.1 業(yè)務(wù)場(chǎng)景和 MVP 范圍定義下面用一個(gè)最小訂單場(chǎng)景演示完整流程。技術(shù)棧選擇 Spring Boot 3、Java 17、Maven為了演示保持精簡(jiǎn)。業(yè)務(wù)范圍是用戶提交訂單系統(tǒng)校驗(yàn)商品庫(kù)存校驗(yàn)通過(guò)后生成訂單并扣減庫(kù)存。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ǎn)化分層目錄結(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)目說(shuō)明后會(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)是依賴范圍明確目錄明確還明確說(shuō)了“不要?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ù)無(wú)關(guān)這也是 COLA 架構(gòu)的關(guān)鍵實(shí)踐。領(lǐng)域?qū)右坏┍?JPA 注解、Spring Bean 注解污染后續(xù)做單元測(cè)試和架構(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)庫(kù)存。 3. 創(chuàng)建訂單和訂單項(xiàng)狀態(tài)為 CREATED。 4. 調(diào)用庫(kù)存服務(wù)扣減庫(kù)存。 5. 保存訂單。 事務(wù)邊界放在應(yīng)用層使用 Transactional。 不在應(yīng)用層寫 SQL不直接操作數(shù)據(jù)庫(kù)。適配層只做接口暴露工單 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)證庫(kù)存不足場(chǎng)景curl -X POST http://localhost:8080/api/orders \ -H Content-Type: application/json \ -d {productId:1,quantity:9999,userId:100}預(yù)期返回明確錯(cuò)誤信息且訂單不落庫(kù)。這兩個(gè)測(cè)試分別覆蓋了正常分支和異常分支是 MVP 閉環(huán)驗(yàn)證的基本要求。注意不要只驗(yàn)證程序能啟動(dòng)還要驗(yàn)證正常輸入、異常輸入和數(shù)據(jù)庫(kù)狀態(tài)是否符合預(yù)期。只有啟動(dòng)成功但接口行為錯(cuò)誤的項(xiàng)目在 AI 編程場(chǎng)景里非常常見(jiàn)。6. 常見(jiàn)問(wèn)題與排查路徑6.1 Claude Code 安裝、版本與賬號(hào)問(wèn)題Claude Code 常見(jiàn)問(wèn)題集中在這幾類問(wèn)題現(xiàn)象常見(jiàn)原因檢查方式處理建議安裝后執(zhí)行 claude 提示命令不存在npm 全局目錄不在 PATH執(zhí)行 npm config get prefix把全局 bin 目錄加入 PATH啟動(dòng)時(shí)提示模型版本不識(shí)別客戶端版本和模型配置不一致執(zhí)行 claude --version 確認(rèn)版本更新 Claude Code并檢查模型配置是否指向受支持版本提示組織禁用訪問(wèn)組織賬號(hào)未開(kāi)放 Claude Code 權(quán)限查看完整提示文本聯(lián)系團(tuán)隊(duì)管理員開(kāi)啟權(quán)限不要繞過(guò)限制提示區(qū)域不可用當(dāng)前環(huán)境不在支持范圍內(nèi)結(jié)合部署環(huán)境判斷確認(rèn)部署環(huán)境支持情況不要嘗試?yán)@過(guò)限制npm 安裝緩慢或失敗網(wǎng)絡(luò)或 registry 配置問(wèn)題檢查 npm config get registry切換為團(tuán)隊(duì)維護(hù)的鏡像源后重試排查順序建議從輸入命令是否正確開(kāi)始再檢查路徑和權(quán)限然后看版本和配置最后看網(wǎng)絡(luò)環(huán)境。不要一上來(lái)就認(rèn)為模型能力有問(wèn)題。6.2 新開(kāi)會(huì)話丟失上下文記憶這是 AI 編程工具最常見(jiàn)的困擾之一。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 消耗過(guò)大AI 編程工具消耗大量 token 通常有三種原因一次交給模型的任務(wù)范圍過(guò)大讓它反復(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ì)輸出大段說(shuō)明文字。6.4 AI 生成代碼不符合分層要求即使寫了 CLAUDE.mdAI 仍可能在生成代碼時(shí)越過(guò)邊界例如在 Controller 里寫業(yè)務(wù)邏輯。處理方式檢查是否在任務(wù)描述中明確了該文件的層級(jí)歸屬。檢查 CLAUDE.md 中的依賴方向是否被模型準(zhǔn)確讀取。讓 AI 重新生成該文件并明確要求遵循分層規(guī)則。在代碼評(píng)審階段增加一條分層檢查規(guī)則人工或腳本檢查依賴方向。更推薦的做法是在工單描述中直接寫“這個(gè)文件屬于 domain 層禁止引用 Spring、禁止操作數(shù)據(jù)庫(kù)”把約束前置到生成階段而不是在生成后補(bǔ)救。7. 最佳實(shí)踐與可復(fù)用檢查清單7.1 需求文檔檢查清單[ ] 是否只有一個(gè)明確的用戶角色和核心動(dòng)作[ ] 是否每一條驗(yàn)收標(biāo)準(zhǔn)都可觀察、可測(cè)試[ ] 是否明確本次包含的內(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)文件”的粒度最壞情況也能快速定位問(wèn)題。7.3 COLA 分層代碼檢查清單[ ] Controller 是否只做參數(shù)接收和響應(yīng)封裝[ ] Service 是否只做用例編排不寫 SQL[ ] Domain 層是否保持技術(shù)無(wú)關(guān)不依賴 Spring Data[ ] Infrastructure 層是否實(shí)現(xiàn)了領(lǐng)域?qū)佣x的接口[ ] 依賴方向是否從外向內(nèi)沒(méi)有反向依賴[ ] 是否沒(mé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ù)庫(kù)連接池、日志、監(jiān)控是否配置完整。異常處理是否區(qū)分業(yè)務(wù)異常和系統(tǒng)異常。是否補(bǔ)充了權(quán)限校驗(yàn)、請(qǐng)求限流、參數(shù)校驗(yàn)等安全能力。是否把配置外置化而不是硬編碼在代碼中。是否準(zhǔn)備回滾方案和發(fā)布檢查單。是否為核心流程補(bǔ)充了集成測(cè)試和回歸測(cè)試。MVP 解決的是“業(yè)務(wù)閉環(huán)能否成立”生產(chǎn)化解決的是“系統(tǒng)能否穩(wěn)定運(yùn)行”。兩者不要混在一起做這也是“先做 MVP”的另一個(gè)原因先解決正確性問(wèn)題再解決健壯性問(wèn)題。AI 編程的產(chǎn)出質(zhì)量本質(zhì)上由你給它的約束質(zhì)量決定。COLA 提供架構(gòu)約束MVP 提供范圍約束CLAUDE.md 提供項(xiàng)目約定工單描述提供任務(wù)邊界。四層約束疊加起來(lái)Claude Code 才能從“大膽猜測(cè)者”變成“可預(yù)期執(zhí)行者”。下一步可以從兩個(gè)方向擴(kuò)展一是把訂單場(chǎng)景升級(jí)為完整狀態(tài)機(jī)引入 COLA 的狀態(tài)機(jī)機(jī)制和領(lǐng)域事件二是把單模塊的 MVP 實(shí)踐復(fù)制到多個(gè)模塊形成團(tuán)隊(duì)統(tǒng)一的 AI 編程協(xié)作規(guī)范。對(duì)新手來(lái)說(shuō)最好的練習(xí)不是去研究更復(fù)雜的提示詞技巧而是把一個(gè)非常小的 MVP按本文的工單方式完整跑一遍感受約束前后 AI 產(chǎn)出質(zhì)量的差異。