：構(gòu)建可驗證、可治理、可擴展的分布式系統(tǒng))
最近在帶團(tuán)隊做一套訂單中臺改造從單體往分布式微服務(wù)遷移壓力最大的不是寫業(yè)務(wù)代碼而是控質(zhì)量、控變更、控邊界。恰好這幾個月我們把 Claude Code 深度接進(jìn)了日常研發(fā)流程用它輔助設(shè)計、編碼、補測試、寫遷移腳本跑完一輪下來我最大的感受是這工具能不能發(fā)揮價值完全取決于你把它放在什么位置、用什么規(guī)則約束它。把它當(dāng)“自動補全”你得到的只是零散代碼片段把它當(dāng)成一個“能寫代碼的架構(gòu)師實習(xí)生”并且配好驗證、治理、擴展的整套規(guī)則它能實打?qū)嵉貛湍憬桓渡a(chǎn)級系統(tǒng)。這篇博文我想整理的就是這套用法如何用 Claude Code 構(gòu)建一個可驗證、可治理、可擴展的生產(chǎn)級分布式系統(tǒng)。內(nèi)容會覆蓋環(huán)境配置、驗證策略、代碼治理、架構(gòu)擴展以及一套可以直接復(fù)制的實操流程。不管是剛接觸 Claude Code 的后端工程師還是想在團(tuán)隊里推 AI 輔助開發(fā)的技術(shù)負(fù)責(zé)人都能從中拿到能落地的方案。1. 先搞清楚目標(biāo)可驗證、可治理、可擴展到底意味著什么1.1 三個關(guān)鍵詞不是擺設(shè)是生產(chǎn)系統(tǒng)的生死線“可驗證、可治理、可擴展”這三個詞平時在技術(shù)方案里見得很多但真落到分布式系統(tǒng)上每一環(huán)都有非常具體的指向?？沈炞C說的是你交付出去的每一個服務(wù)、每一次改動都能通過自動化手段證明它是對的。不是“本地跑通了”而是單元測試、契約測試、集成測試、端到端驗證全部能過數(shù)據(jù)變更能回滾接口改動能被契約約束住。分布式系統(tǒng)里服務(wù)之間的調(diào)用鏈拉得很長A 服務(wù)改了接口B 服務(wù)可能到上線那天才知道壞了。沒有驗證體系改代碼就是在踩地雷?？芍卫碚f的是團(tuán)隊多人協(xié)作時AI 生成的代碼不是失控的。誰在什么時候改了哪塊邏輯、用了什么模型、跑了哪些命令全部有日志、有權(quán)限控制、有審查機制。這一點最容易被人忽視尤其是個人開發(fā)者用 Claude Code 的時候感覺“它能直接改文件太爽了”但在生產(chǎn)系統(tǒng)里這種權(quán)限裸奔狀態(tài)就是事故的溫床?？蓴U展說的是系統(tǒng)的架構(gòu)演進(jìn)能跟上業(yè)務(wù)增長。今天你是 2 個服務(wù)的單體集群明天可能是 20 個微服務(wù)后天可能是跨地域多活。用 Claude Code 寫出來的代碼如果一開始就是貼死業(yè)務(wù)邏輯的“面條代碼”那擴展的時候不是改代碼是推翻重來。1.2 Claude Code 在分布式系統(tǒng)建設(shè)中扮演什么角色我的定位是它是“結(jié)對程序員 代碼審查助手 運維腳本生成器”三合一但它不是架構(gòu)師。架構(gòu)方向的決策必須由人來做Claude Code 負(fù)責(zé)的是把決策落實到代碼層面并且?guī)湍惆雅K活累活干了。舉個例子我讓它幫我生成一個分布式限流組件它能在幾分鐘內(nèi)給你一個包含令牌桶算法、Redis 存儲、Spring AOP 接入的完整模塊單元測試都給你寫好。但如果我問它“我們到底應(yīng)該用 Redis 分布式鎖還是 ZooKeeper 鎖”它能給出的只是泛泛的優(yōu)劣勢對比真正拍板還得靠你自己對業(yè)務(wù)場景的理解。所以我的團(tuán)隊里立了一條規(guī)矩Claude Code 輸出的所有架構(gòu)設(shè)計類內(nèi)容必須經(jīng)過一名高級工程師人工審查后才允許進(jìn)入代碼庫。這不是不信任工具而是對生產(chǎn)系統(tǒng)的敬畏。1.3 我搭建這套體系前的配置基線在進(jìn)入具體章節(jié)之前先把我這邊的基礎(chǔ)環(huán)境交代一下后面講的所有操作都是基于這套環(huán)境Claude Code 版本持續(xù)保持最新版npm 全局安裝執(zhí)行方式macOS 本地終端 CI 服務(wù)器GitHub Actions遠(yuǎn)程執(zhí)行集成工具VS Code 插件 MCPModel Context Protocol連接 MySQL、Redis、Kafka權(quán)限模式默認(rèn)非自動執(zhí)行所有寫文件/執(zhí)行命令操作需人工確認(rèn)會話管理按項目隔離每個服務(wù)一個獨立工作區(qū)這套配置的核心思路是Claude Code 有很強的能力但我要把它關(guān)在“籠子”里使用。讓它能看見完整的項目上下文能提出方案、寫代碼、跑測試但所有副作用操作都要經(jīng)過確認(rèn)和記錄后面會展開講。2. 環(huán)境準(zhǔn)備與基礎(chǔ)配置把地基打牢再開工2.1 安裝與初始化的完整步驟Claude Code 的安裝非常簡單一條 npm 命令搞定前提是你的機器上已經(jīng)有 Node.js 18 環(huán)境npm install -g anthropic-ai/claude-code安裝完成后在終端輸入claude進(jìn)入交互式界面首次使用會引導(dǎo)你完成認(rèn)證登錄。這里要說一個我踩過的坑如果你在公司內(nèi)網(wǎng)環(huán)境或者網(wǎng)絡(luò)代理設(shè)置比較復(fù)雜登錄環(huán)節(jié)容易卡住甚至報 403。我遇到過幾次排查下來基本都是代理環(huán)境變量導(dǎo)致的 SSL 握手問題解決辦法是清理環(huán)境變量或者確認(rèn)代理對 Anthropic 域名的訪問策略。認(rèn)證完成之后我強烈建議你做的第一件事不是開始寫代碼而是運行claude config set -g theme dark claude config set -g verbose false把界面和日志先調(diào)整到適合長期工作的狀態(tài)。默認(rèn)配置下日志很啰嗦會刷掉你的注意力。2.2 在 VS Code 里集成 Claude Code很多人習(xí)慣在 IDE 里使用 AI 工具Claude Code 官方提供了 VS Code 插件安裝后可以在編輯器側(cè)邊欄直接打開會話面板。安裝方式有兩種在 VS Code 擴展市場搜索 “Claude Code” 直接安裝如果你已經(jīng)在終端里安裝過 Claude Code擴展會自動識別到本機的 Claude Code 可執(zhí)行文件這里有一個重要配置插件默認(rèn)會繼承終端里的認(rèn)證狀態(tài)但如果你的終端用的是 zsh 而 VS Code 里跑的是默認(rèn) shell可能出現(xiàn)“找不到 claude 命令”的問題。需要在 VS Code 的 settings.json 里指定 claude 的絕對路徑比如{ claude-code.path: /usr/local/bin/claude }路徑可以用which claude查出來。2.3 CLAUDE.md讓 AI 讀懂你的項目規(guī)則Claude Code 最核心的配置是項目根目錄下的CLAUDE.md文件。這個文件相當(dāng)于給 AI 的“入職手冊”在每次會話開始時Claude Code 會自動讀取它作為理解項目、執(zhí)行任務(wù)的背景知識。我的團(tuán)隊里每個服務(wù)倉庫的CLAUDE.md都會包含以下幾塊內(nèi)容你可以直接參照這個結(jié)構(gòu)寫# 項目名稱 一句話描述項目定位如訂單中臺 - 核心交易服務(wù) ## 技術(shù)棧 - 語言/框架Java 17 Spring Boot 3.2 - 存儲MySQL 8.0主庫/ Redis 7緩存 - 消息Kafka 3.x - 部署Docker Kubernetes ## 項目結(jié)構(gòu) - 模塊劃分controller / service / repository / domain / infrastructure - 分層規(guī)則controller 層不允許寫業(yè)務(wù)邏輯repository 層不允許出現(xiàn)業(yè)務(wù)判斷 ## 編碼規(guī)范 - 所有對外接口必須返回統(tǒng)一響應(yīng)體 ResultT - 所有金額字段必須用 BigDecimal禁止用 Double - 創(chuàng)建/更新時間統(tǒng)一用 Long 類型毫秒時間戳 ## 測試要求 - 每個 service 方法必須有對應(yīng)單元測試 - 對外接口變更必須同步更新契約測試文件 - 本地跑全量測試命令./mvnw verify ## 禁止事項 - 不要修改 pom.xml 的依賴版本除非明確要求 - 不要直接操作生產(chǎn)數(shù)據(jù)庫所有變更走遷移腳本 - 不要在 service 里直接 new 線程池必須使用項目統(tǒng)一線程池組件這個文件的作用非常大。沒有它的時候Claude Code 生成的代碼每一份都“似曾相識但又不完全對”有它之后生成的代碼里 80% 的規(guī)范問題直接消失。我甚至建議給全局加一個~/.claude/CLAUDE.md把你個人的通用編碼偏好寫進(jìn)去這樣不管開哪個項目AI 都會默認(rèn)遵守你的習(xí)慣。2.4 權(quán)限控制別讓 AI 裸奔Claude Code 默認(rèn)在執(zhí)行寫文件、運行命令等操作時會向你請求確認(rèn)但在某些模式下比如--dangerously-skip-permissions它會跳過所有確認(rèn)這個模式我在生產(chǎn)環(huán)境里是絕對禁用的。我這邊推薦的做法是在啟動會話時就明確權(quán)限邊界claude --allowedTools Read,Edit,Write,Bash(npm test:*) --disallowedTools Bash(git push),Bash(rm -rf)上面的命令允許 Claude Code 讀文件、編輯文件、運行測試命令但禁止執(zhí)行g(shù)it push和危險的刪除命令。你可以根據(jù)實際場景調(diào)整允許/禁止的工具列表我的原則是能讓它干活的權(quán)限要給但會給生產(chǎn)環(huán)境造成不可逆影響的操作一律禁止自動執(zhí)行。權(quán)限配置的關(guān)鍵參數(shù)我整理成了表格方便你對照使用配置項作用推薦設(shè)置--allowedTools允許自動執(zhí)行的操作白名單按需授權(quán)只給當(dāng)前任務(wù)需要的--disallowedTools禁止執(zhí)行的操作黑名單加入高危命令如git push --force、生產(chǎn)環(huán)境刪除操作--permission-mode權(quán)限模式默認(rèn)確認(rèn)模式禁用dangerously-skip-permissions--model指定使用的模型根據(jù)任務(wù)復(fù)雜度選擇簡單任務(wù)用小模型省錢--max-turns單次會話最大輪數(shù)防止死循環(huán)消耗配額2.5 用 MCP 打通數(shù)據(jù)源讓 AI 能“看見”數(shù)據(jù)庫Claude Code 的上下文窗口再大也不可能預(yù)知你的業(yè)務(wù)數(shù)據(jù)長什么樣。所以我們要用 MCP 把開發(fā)環(huán)境的數(shù)據(jù)庫、消息隊列、緩存等基礎(chǔ)設(shè)施“接入”到 AI 的視野里。MCP 的配置也是寫在CLAUDE.md或者單獨的配置文件里我舉個例子連接 MySQL 的配置片段## MCP Servers - mysql: 通過 mysql-mcp-server 連接schema 信息自動同步 命令: npx mysql-mcp-server --host 127.0.0.1 --port 3306 --user dev --password dev123配置好之后你可以直接對 Claude Code 說“幫我查一下訂單表結(jié)構(gòu)找出所有金額字段”它能通過 MCP 直接查庫并返回結(jié)果這比貼建表語句給它是完全不同的體驗。但這里有一個重要提醒在生產(chǎn)環(huán)境千萬不要給 MCP 配寫權(quán)限只讓它讀 schema、讀數(shù)據(jù)用于理解業(yè)務(wù)任何寫操作必須走人工確認(rèn)或遷移腳本。3. 可驗證性如何確保 AI 寫出來的代碼真的能上線3.1 AI 生成代碼最大的風(fēng)險不是“寫錯”而是“看起來對”我發(fā)現(xiàn)很多團(tuán)隊不敢用 AI 寫生產(chǎn)代碼核心原因不是模型能力不行而是 AI 生成代碼有一種迷惑性——它語法正確、結(jié)構(gòu)完整、甚至注釋都寫好了但業(yè)務(wù)邏輯可能完全是錯的。舉一個我實際遇到的例子。讓 Claude Code 實現(xiàn)一個“訂單超時自動關(guān)閉”功能它很自然地寫出了一個定時任務(wù)每五分鐘掃描一次訂單表把超過三十分鐘未支付的訂單置為關(guān)閉狀態(tài)。單看代碼邏輯完全沒問題。但懂業(yè)務(wù)的人一眼就能看出問題這個方案在分布式環(huán)境下是錯的。如果系統(tǒng)部署了多個實例定時任務(wù)會在每個實例上同時跑不做分布式鎖就會產(chǎn)生重復(fù)掃描、重復(fù)更新甚至并發(fā)扣減庫存的嚴(yán)重事故。這就是 AI 編碼的陷阱它擅長生成“符合常規(guī)模式的代碼”但不理解你系統(tǒng)的特殊約束。解法只有一個——把所有關(guān)鍵行為的驗證閉環(huán)前置到開發(fā)流程里用測試、契約、檢查機制把錯誤擋在上線之前。3.2 三層驗證架構(gòu)單測、契約、端到端我這邊把驗證分成三層每一層對應(yīng)不同粒度的保障第一層是單元測試覆蓋最小業(yè)務(wù)單元的輸入輸出和邊界條件。這一層最容易讓 Claude Code 自動生成但也是我審查最嚴(yán)格的一層。我會要求它對每個 service 方法生成測試包括正常路徑、異常路徑、邊界值、并發(fā)場景生成完再讓人工抽查。第二層是契約測試這是分布式系統(tǒng)的關(guān)鍵護(hù)城河。服務(wù)之間通過 HTTP 或消息通信接口的請求響應(yīng)結(jié)構(gòu)一旦變化下游服務(wù)立刻遭殃。我們用 Pact 或者 Spring Cloud Contract 做消費者驅(qū)動的契約測試把每個服務(wù)的對外接口規(guī)范固化成文件任何一方改動契約CI 就會報錯逼著雙方協(xié)商兼容方案。第三層是端到端測試用 Testcontainers 起一套完整的依賴環(huán)境MySQL、Redis、Kafka模擬真實業(yè)務(wù)鏈路跑通核心流程。這一層不是為了測每一個細(xì)節(jié)而是驗證系統(tǒng)級的行為符合預(yù)期比如“下單 → 扣庫存 → 發(fā)消息 → 訂單狀態(tài)變更”這條主鏈路。這三層驗證跑下來我才能放心地把 Claude Code 生成的代碼合入主干分支。3.3 讓 Claude Code 先生成測試再生成實現(xiàn)操作上有一個非常有效的小技巧不要讓它直接寫實現(xiàn)代碼而是先讓它寫測試。我的做法是這樣的拿一個“用戶積分變更”的需求舉例我在會話里敲入請為 UserScoreService.changeScore(Long userId, int delta) 方法編寫單元測試。 業(yè)務(wù)規(guī)則 1. 積分為負(fù)數(shù)時拋 IllegalArgumentException 2. 用戶不存在時拋 UserNotFoundException 3. 變更后的積分不能小于 0 請先寫測試再根據(jù)測試反推實現(xiàn)。這么說的好處是Claude Code 會先基于業(yè)務(wù)規(guī)則定義預(yù)期行為然后為了通過測試去寫實現(xiàn)代碼。這樣生成的代碼天然帶著“驗證基因”而不是天馬行空地自由發(fā)揮。我實測下來用這種方式生成的代碼review 時發(fā)現(xiàn)的邏輯錯誤數(shù)量明顯減少。3.4 把驗證嵌入 CI/CDAI 生成的代碼也要過流水線Claude Code 不僅能幫你寫業(yè)務(wù)代碼還能幫你把這些驗證流程集成到 CI 流水線里。我讓它在 GitHub Actions 里自動生成了一套工作流核心階段如下name: verify on: [push, pull_request] jobs: test: runs-on: ubuntu-latest services: mysql: image: mysql:8.0 env: MYSQL_ROOT_PASSWORD: test ports: [3306:3306] steps: - uses: actions/checkoutv4 - name: Run unit tests run: ./mvnw test - name: Run contract tests run: ./mvnw verify -Pcontract-tests - name: Run end-to-end tests run: ./mvnw verify -Pe2e-tests每一個 PR 進(jìn)來這套流水線都會完整跑一遍三層驗證任何一層失敗都不允許合并。這樣做還有一個好處Claude Code 提出了一些方案改動時它會先看 CI 跑不跑得過而不是只拿“本地編譯過了”當(dāng)理由。這是可驗證性的最終保證。4. 可治理性多人協(xié)作下如何管住 AI 的“手”4.1 治理的核心可追溯、可審計、可控回滾當(dāng)團(tuán)隊里每個人都用 Claude Code 寫代碼時最大的問題不是代碼質(zhì)量問題而是失控問題。A 讓 AI 改了配置B 讓 AI 動了接口C 讓 AI 跑了數(shù)據(jù)庫遷移腳本——這些操作如果沒有記錄、沒有審批、沒有回滾通道系統(tǒng)遲早被自己人搞掛?？勺匪菔钦f每一段由 AI 生成的改動都能追溯到對應(yīng)的需求和操作者?？蓪徲嬍钦f每個關(guān)鍵動作都有日志留痕出了問題能復(fù)盤?？煽鼗貪L是說任何 AI 做的變更都有對應(yīng)的回滾方案絕不出現(xiàn)“改壞了沒法回”的局面。4.2 規(guī)范先行把約束寫進(jìn) CLAUDE.md在多人協(xié)作的場景下CLAUDE.md不僅僅是給 AI 看的規(guī)范更是團(tuán)隊對 AI 的使用公約。除了前面提到的技術(shù)棧和結(jié)構(gòu)約束我們還加了一些治理條款## AI 使用治理規(guī)則必須遵守 1. 任何涉及數(shù)據(jù)庫表結(jié)構(gòu)變更的操作必須先輸出遷移腳本并提交 DBA 審查 2. 修改對外接口簽名或請求響應(yīng)結(jié)構(gòu)時必須同步更新契約測試并通知下游負(fù)責(zé)人 3. 生成代碼時必須包含完整注釋注明業(yè)務(wù)背景和設(shè)計理由禁止只有“根據(jù)需求實現(xiàn)”這種無意義注釋 4. 禁止 AI 直接修改 Kubernetes 部署文件中的鏡像版本發(fā)布操作由運維流水線統(tǒng)一處理 5. 所有 AI 會話的關(guān)鍵輸出保存到 docs/ai-sessions/ 目錄按日期命名這些條款不是限制 AI 的能力而是把不確定性壓縮到可控范圍。尤其第 5 條我會讓 Claude Code 在每次重要會話結(jié)束時自動把對話摘要、產(chǎn)出物、未決問題導(dǎo)出成 Markdown 文件這樣即使寫代碼的人休假了后來的人打開目錄就能看到那次改動的完整背景。4.3 代碼審查時AI 生成代碼的特殊審查點傳統(tǒng)的人工代碼審查關(guān)注的是業(yè)務(wù)邏輯正確性、代碼風(fēng)格、性能問題。但審查 AI 生成的代碼我額外加了幾個檢查項這里整理成表格審查維度檢查點原因真實性依賴的包、API 是否存在版本號是否真實AI 會“發(fā)明”不存在的庫尤其是小眾工具庫安全性是否有硬編碼密鑰、SQL 注入、越權(quán)風(fēng)險AI 默認(rèn)生成“能跑”的代碼不默認(rèn)安全的代碼業(yè)務(wù)匹配是否理解項目特有的業(yè)務(wù)規(guī)則和約束容易生成通用方案忽略你系統(tǒng)的特殊性邊界處理超時、重試、熔斷等容錯邏輯是否完整分布式系統(tǒng)里這些比業(yè)務(wù)主流程更重要性能隱患是否存在 N1 查詢、循環(huán)調(diào)用 RPC、大事務(wù)AI 容易生成代碼正確但性能災(zāi)難的寫法我一般要求團(tuán)隊里每個人在 review AI 生成代碼時按這個表格逐項過一遍而不是像以前那樣憑感覺掃一眼就點通過。這套做法推行之后我們合并到主干的 AI 生成代碼線上問題率降了一個數(shù)量級。4.4 審計日志Claude Code 自己的“黑匣子”Claude Code 默認(rèn)會在會話中進(jìn)行詳細(xì)的操作記錄包括每次調(diào)用模型的輸入輸出、執(zhí)行過的命令、修改過的文件。但在多人協(xié)作環(huán)境下默認(rèn)的日志放在各自本地沒法統(tǒng)一審計。我們的做法是給開發(fā)者統(tǒng)一配置日志輸出目錄并通過 CI 流程收集會話記錄。具體的配置方式是在啟動 Claude Code 時指定日志路徑claude --session-log-path ~/.claude/logs然后在 CI 中加入一步掃描這些日志文件并上傳到團(tuán)隊內(nèi)部的存儲。這樣做的好處是當(dāng)你發(fā)現(xiàn)某段生產(chǎn)代碼有問題時可以立刻反查是在哪個會話里被生成的、當(dāng)時的上下文是什么、有沒有執(zhí)行過額外操作這比“開發(fā)者回憶”靠譜得多。4.5 發(fā)布管控AI 生成的改動不能直接上生產(chǎn)最后一條治理紅線是發(fā)布管控。我定的規(guī)矩是Claude Code 生成或修改的代碼必須先通過常規(guī)的 PR 流程合并到主干分支再通過 CI 流水線完成部署。任何“讓 AI 直接改生產(chǎn)環(huán)境”的行為在我的團(tuán)隊里都屬于嚴(yán)重違規(guī)。有些人可能會覺得這太保守了AI 改產(chǎn)線腳本更快。但對生產(chǎn)系統(tǒng)來說快不是第一位的穩(wěn)才是。我寧可在治理流程上多花十分鐘也不愿在生產(chǎn)事故后花十個小時復(fù)盤。這個原則同樣適用于你個人的項目哪怕只有你自己一個開發(fā)者也應(yīng)該走完整的發(fā)布鏈路這是職業(yè)習(xí)慣問題。5. 可擴展性從架構(gòu)設(shè)計到代碼落地讓系統(tǒng)能跟著業(yè)務(wù)一起長大5.1 擴展性不是事后補的是設(shè)計出來的一個分布式系統(tǒng)能不能輕松擴容不取決于你最后用了多少臺機器而取決于你寫前幾個服務(wù)時怎么設(shè)計的。如果服務(wù)之間有隱式的共享數(shù)據(jù)庫、繞過 API 直接訪問其他服務(wù)的表、或者把有狀態(tài)數(shù)據(jù)都放在本地內(nèi)存里那系統(tǒng)的擴展天花板在你設(shè)計的第一天就注定了。用 Claude Code 輔助開發(fā)時我會在項目啟動前就讓它輸出一份“擴展性設(shè)計檢查清單”把它作為后續(xù)所有代碼生成的約束條件。這份檢查清單包括服務(wù)是否做到無狀態(tài)化Session 是否外移到 Redis服務(wù)之間的調(diào)用是否全部通過 API 網(wǎng)關(guān)適配沒有直接暴露內(nèi)部服務(wù)地址數(shù)據(jù)庫層面是否有分庫分表預(yù)案當(dāng)前表結(jié)構(gòu)是否預(yù)留了分片鍵核心鏈路是否使用消息隊列解耦還是寫死了同步調(diào)用所有第三方依賴是否有超時、重試、熔斷配置這份清單一旦定下來就在CLAUDE.md里固化成規(guī)范Claude Code 生成新服務(wù)時就會自動帶上這些考量。5.2 讓 Claude Code 幫你做架構(gòu)評審很多人不知道 Claude Code 還有一個很好用的場景架構(gòu)評審。在寫代碼之前我經(jīng)常把當(dāng)前系統(tǒng)的部署圖、核心接口定義、數(shù)據(jù)庫表結(jié)構(gòu)喂給 Claude Code然后讓它以“外部架構(gòu)師”的視角提建議。比如我說“我們目前訂單服務(wù)訪問數(shù)據(jù)庫耗時較高并發(fā)量上來了之后接口響應(yīng)變得越來越慢請幫忙分析可能原因并給出優(yōu)化建議?！彼鼤敵鲆话娼Y(jié)構(gòu)化分析包含索引問題、連接池配置、緩存缺失、慢查詢等多個維度并且給出對應(yīng)的代碼改動建議。但這里我要潑一盆冷水AI 的架構(gòu)建議只能作為參考不能作為決策依據(jù)。它沒有你系統(tǒng)的全量指標(biāo)看不到真實的鏈路追蹤更不了解團(tuán)隊的維護(hù)能力。我會把它的輸出當(dāng)成一份“待驗證的候選方案列表”挑出有道理的方案再人工驗證而不是拿過來就用。5.3 用 AI 生成可復(fù)用的分布式基礎(chǔ)組件分布式系統(tǒng)里有很多重復(fù)造輪子的基礎(chǔ)組件分布式鎖、分布式 ID 生成器、限流器、鏈路追蹤工具類、統(tǒng)一異常處理。這些組件的特點是模式固定、邏輯相對通用非常適合讓 Claude Code 生成初版再由團(tuán)隊里的高級工程師審查打磨。舉一個實際例子我讓 Claude Code 生成一個基于 Redis 的分布式鎖工具類它給出的核心實現(xiàn)包含public class RedisDistributedLock { private final StringRedisTemplate redisTemplate; public boolean tryLock(String lockKey, String requestId, long expireSeconds) { Boolean result redisTemplate.opsForValue() .setIfAbsent(lockKey, requestId, Duration.ofSeconds(expireSeconds)); return Boolean.TRUE.equals(result); } public boolean releaseLock(String lockKey, String requestId) { String script if redis.call(get, KEYS[1]) ARGV[1] then return redis.call(del, KEYS[1]) else return 0 end; Long result redisTemplate.execute( new DefaultRedisScript(script, Long.class), Collections.singletonList(lockKey), requestId ); return Long.valueOf(1L).equals(result); } }這段代碼的亮點是釋放鎖的時候用了 Lua 腳本保證原子性并且校驗了持有者身份避免了誤刪別人的鎖。這些細(xì)節(jié)如果靠人從零寫可能也能寫出來但 AI 在幾分鐘內(nèi)給出一個可用的初版效率提升是實打?qū)嵉摹?.4 規(guī)范生成模塊化代碼避免“一鍋粥”可擴展性的敵人永遠(yuǎn)是不合理的耦合。我見過太多系統(tǒng)一開始是一個大單體后來拆微服務(wù)的時候發(fā)現(xiàn)業(yè)務(wù)邏輯糾纏在一起根本切不開。Claude Code 寫代碼時如果沒有任何約束它會傾向于把所有相關(guān)邏輯放在最方便的位置很快形成“上帝類”和循環(huán)依賴。我用的辦法是在項目的CLAUDE.md里明確規(guī)定模塊邊界和依賴規(guī)則。比如訂單服務(wù)的代碼生成規(guī)則## 模塊依賴規(guī)則 - domain 模塊純業(yè)務(wù)實體與業(yè)務(wù)規(guī)則不依賴任何框架和其他模塊 - application 模塊用例編排依賴 domain 模塊 - infrastructure 模塊數(shù)據(jù)庫、消息、外部接口實現(xiàn)依賴 domain 模塊接口禁止反向依賴 - controller 模塊HTTP 層適配依賴 application 模塊這樣規(guī)定之后Claude Code 生成新代碼時就會自動放到合理的位置不會出現(xiàn) controller 里寫 SQL 這種低級問題。模塊邊界清晰了未來系統(tǒng)的每個服務(wù)才能獨立演進(jìn)、獨立擴縮容。5.5 緩存、消息隊列與數(shù)據(jù)庫擴展的 AI 輔助分布式系統(tǒng)擴容時最先遇到的瓶頸往往是存儲和流量。我可以讓 Claude Code 幫我做以下幾類擴展準(zhǔn)備緩存擴展方面讓它分析現(xiàn)有接口的緩存策略標(biāo)出哪些接口缺少緩存穿透、擊穿、雪崩的保護(hù)然后生成對應(yīng)的更新代碼。消息隊列擴展方面讓它根據(jù)業(yè)務(wù)事件設(shè)計 Topic 劃分方案生成生產(chǎn)者、消費者的骨架代碼并配置好重試和死信隊列。數(shù)據(jù)庫擴展方面讓它分析大表和慢查詢生成索引優(yōu)化建議和分庫分表預(yù)研代碼。這些操作我不建議一次性全部交給 AI 自動完成而是每完成一項就進(jìn)行人工 review 和測試。擴展性建設(shè)是一個持續(xù)演進(jìn)的過程不是一錘子買賣。把它拆成一個個小任務(wù)夾在迭代里做反而比“下一版大重構(gòu)”更容易落地。6. 實操全流程從零到一構(gòu)建一個生產(chǎn)級分布式服務(wù)6.1 場景設(shè)定搭建“積分服務(wù)”并接入主系統(tǒng)為了讓整個流程更直觀我拿一個具體的例子演示完整操作。假設(shè)業(yè)務(wù)上需要一個獨立的積分服務(wù)包含積分發(fā)放、積分查詢、積分過期回收三個核心能力并且需要支持后續(xù)并發(fā)量翻倍后的水平擴展。我的第一步操作是在會話里給 Claude Code 清晰的需求描述并且告訴它我們既有的技術(shù)規(guī)范和約束。描述越具體產(chǎn)出越可控。請在 services/points-service 下創(chuàng)建積分服務(wù)模塊。 功能需求 1. 提供積分發(fā)放接口內(nèi)部調(diào)用increasePoints 2. 提供積分查詢接口getUserPoints 3. 提供積分過期回收的定時任務(wù)按過期時間批量關(guān)閉過期積分 技術(shù)約束 - Java 17 Spring Boot 3.2 - 數(shù)據(jù)庫 MySQL表結(jié)構(gòu)按領(lǐng)域模型設(shè)計須包含樂觀鎖版本號字段 - 對外接口走公司統(tǒng)一 API 網(wǎng)關(guān)協(xié)議 - 所有金額/積分字段采用 Long 存儲單位個 - 模塊結(jié)構(gòu)遵循項目已有分層規(guī)范 - 編寫完整單元測試6.2 查看 Claude Code 的產(chǎn)出物結(jié)構(gòu)收到需求后Claude Code 會在工作區(qū)里創(chuàng)建對應(yīng)的目錄結(jié)構(gòu)。一次典型生成出來的骨架大概是這樣的services/points-service/ ├── pom.xml ├── src/main/java/com/example/points/ │ ├── PointsServiceApplication.java │ ├── controller/PointsController.java │ ├── application/PointsApplicationService.java │ ├── domain/model/PointsAccount.java │ ├── domain/model/PointsRecord.java │ ├── domain/repository/PointsRepository.java │ ├── domain/service/PointsExpiryCalculator.java │ └── infrastructure/ │ ├── persistence/PointsRepositoryImpl.java │ ├── message/PointsEventPublisher.java │ └── config/PointsDataSourceConfig.java ├── src/main/resources/ │ ├── application.yml │ └── db/migration/V1__create_points_tables.sql └── src/test/java/com/example/points/ ├── domain/PointsExpiryCalculatorTest.java └── application/PointsApplicationServiceTest.java這個結(jié)構(gòu)已經(jīng)基本符合我們團(tuán)隊的分層規(guī)范了。遷移腳本、配置、測試一股腦兒生成好我只需要逐項審查確認(rèn)。整個過程從零點開始到初步可跑狀態(tài)不會超過十分鐘這在以前至少是半天的工作量。6.3 關(guān)鍵代碼實現(xiàn)的審查與修正當(dāng)然生成的代碼不能無腦接受。我以積分過期回收的定時任務(wù)為例展示一下審查時需要注意的細(xì)節(jié)。Claude Code 生成的初版可能是基于Scheduled(cron 0 */5 * * * ?)的本地定時任務(wù)邏輯上也能跑。但放到分布式環(huán)境里需要保證多實例部署時不重復(fù)執(zhí)行。所以我在 review 時會要求它改成基于 Redis 分布式鎖的方案并且增加“每次掃描分頁處理、單條處理失敗不影響批次整體”的容錯邏輯。我會在會話里直接提出修改意見當(dāng)前實現(xiàn)存在兩個問題 1. 多實例部署時定時任務(wù)會重復(fù)執(zhí)行請加入 Redis 分布式鎖保護(hù) 2. 掃描邏輯需要分頁處理避免一次性加載全部過期記錄導(dǎo)致內(nèi)存溢出 請修改實現(xiàn)并補充對應(yīng)的單元測試。Claude Code 會基于反饋修改代碼這個過程我們稱之為“AI 代碼迭代循環(huán)”。一般經(jīng)過兩三輪這樣的修正生成的代碼就能達(dá)到上線標(biāo)準(zhǔn)。6.4 讓 AI 生成 Dockerfile 與 Kubernetes 部署清單生產(chǎn)系統(tǒng)的最后一步是部署。我同樣會讓 Claude Code 基于已有項目的部署模板為積分服務(wù)生成 Dockerfile 和 Kubernetes 配置。生成時它會自動帶上健康檢查、資源限制、優(yōu)雅停機等生產(chǎn)必備配置。Dockerfile 的關(guān)鍵內(nèi)容如下FROM maven:3.9-eclipse-temurin-17 AS builder COPY . /workspace WORKDIR /workspace RUN mvn clean package -DskipTests FROM eclipse-temurin:17-jre COPY --frombuilder /workspace/target/points-service.jar /app/app.jar EXPOSE 8080 ENTRYPOINT [java, -jar, /app/app.jar]Kubernetes 部署文件里它也會自動加上livenessProbe和readinessProbe的配置保證實例在啟動完成前不會被流量打到在異常時能被自動重啟。這些細(xì)節(jié)對一個生產(chǎn)系統(tǒng)來說至關(guān)重要也不會被 AI 漏掉。6.5 運行全鏈路驗證并記錄會話在所有文件生成和修正完成之后我要求 Claude Code 跑一遍完整的驗證命令鏈條編譯、單測、契約測試、構(gòu)建 Docker 鏡像然后把整次會話的關(guān)鍵決策摘要導(dǎo)出到docs/ai-sessions/2025-xx-xx-points-service.md作為后續(xù)審計和追溯的依據(jù)。這一步做完一個生產(chǎn)級分布式服務(wù)才算真正交付。從需求到上線過程中 AI 承擔(dān)了大約七成的編碼和配置工作剩下三成的人工工作集中在需求明確、方案決策、代碼審查和最終驗證上。這個比例是我們在實踐中覺得比較舒服的配比——既能提升效率又能守住質(zhì)量底線。7. 常見問題與排查技巧實錄7.1 安裝失敗或登錄 403我自己和團(tuán)隊同事在安裝和登錄階段遇到的問題最多這里把典型現(xiàn)象和解決辦法整理出來現(xiàn)象可能原因解決辦法npm 安裝報權(quán)限錯誤Node.js 安裝目錄權(quán)限不足用 nvm 管理 Node.js避免全局安裝權(quán)限問題登錄時瀏覽器回調(diào) 403代理環(huán)境變量干擾檢查HTTPS_PROXY等環(huán)境變量臨時清除后重試登錄半天跳轉(zhuǎn)不回來系統(tǒng)默認(rèn)瀏覽器兼容問題用claude login手動復(fù)制認(rèn)證鏈接到無痕窗口完成VS Code 插件找不到命令PATH 不一致在 settings.json 中顯式指定claude-code.path有一個通用排查思路先把所有第三方代理環(huán)境變量臨時清空回歸最干凈的網(wǎng)絡(luò)環(huán)境看問題是否消失。大部分登錄相關(guān)的詭異問題都是這一類原因引起的。7.2 會話中卡住或輸出中斷Claude Code 在處理特別長的上下文或者大規(guī)模重構(gòu)任務(wù)時偶爾會出現(xiàn)響應(yīng)中斷。我的經(jīng)驗是把大任務(wù)拆成小任務(wù)來問每次只讓它處理一個模塊或一個功能成功率會高很多。另外重要操作前先存?zhèn)€檔claude --resume # 或手動保存會話用 --continue 恢復(fù)--resume可以恢復(fù)最近的會話不怕中斷丟上下文。我還會在長任務(wù)里定期把中間成果 commit 到 git 分支這樣即使 AI 跑偏了也能輕松回退到正常狀態(tài)。7.3 MCP 讀不到數(shù)據(jù)庫或數(shù)據(jù)不一致MCP 連接數(shù)據(jù)庫后最常見的問題是連不上或查出來的數(shù)據(jù)不是最新的。排查步驟我一般按這個順序確認(rèn) MCP Server 使用的數(shù)據(jù)庫賬號有遠(yuǎn)程訪問權(quán)限如果走 SSH 隧道確認(rèn)隧道端口映射正確檢查 MCP 配置里是否指定了正確的 database 名稱確認(rèn)讀取走的是主庫還是從庫延遲是否影響判斷這里我特別提醒一點MCP 里讀到的數(shù)據(jù)只能用于理解業(yè)務(wù)不要讓它影響你的架構(gòu)決策。生產(chǎn)系統(tǒng)的判斷還是要以監(jiān)控大盤、鏈路追蹤和真實壓測數(shù)據(jù)為準(zhǔn)。7.4 配額和限額問題持續(xù)高強度使用 Claude Code尤其是團(tuán)隊多人共享賬號時很容易遇到請求頻率限制或者周配額耗盡的提示。這類問題沒有太多取巧空間我這邊是這么處理的日常小任務(wù)補注釋、格式化、寫測試樁代碼使用輕量模型不占用頂級模型配額重要架構(gòu)設(shè)計任務(wù)集中在一個會話里完成避免反復(fù)開啟新會話重復(fù)消耗團(tuán)隊按服務(wù)模塊分配使用責(zé)任避免多人同時跑重型任務(wù)高峰期錯峰使用把大規(guī)模重構(gòu)任務(wù)安排到非高峰時段執(zhí)行說到底配額管理也是治理的一部分。把它納入團(tuán)隊資源規(guī)劃里比臨時抱佛腳到處找解決辦法要靠譜得多。7.5 對話歷史保存與團(tuán)隊共享有些同事會問“Claude Code 怎么保存對話歷史”其實 CLI 模式下每次會話都有日志記錄關(guān)鍵是找到并善用這些日志。我之前已經(jīng)在治理章節(jié)提過設(shè)置統(tǒng)一日志路徑的方法這里再說一個團(tuán)隊場景下的實用技巧把重要的 AI 會話輸出以 Markdown 形式導(dǎo)出到一個共享倉庫。具體的做法是在會話結(jié)束時讓 Claude Code 自己把討論內(nèi)容和結(jié)論整理成文檔請將本次會話的關(guān)鍵決策、生成的文件列表、遺留問題整理為一份 Markdown 文檔保存到 docs/ai-sessions/2025-xx-xx-points-service-review.md這樣每次重要改動都有據(jù)可查團(tuán)隊其他人也能通過這些文檔了解 AI 參與開發(fā)的完整脈絡(luò)避免“在 AI 會話里發(fā)生過什么”成為黑箱。寫在最后我的一些真實體會折騰了大半年 Claude Code我自己最深的體會是AI 不是用來替代工程師思考的而是用來放大工程師的思考效率的。你越清楚自己要什么、越懂得設(shè)定邊界它給你的幫助就越大。反之如果你自己都不知道系統(tǒng)該怎么設(shè)計就把問題拋給它它只會用漂亮的代碼包裝你的混亂最后把麻煩留到生產(chǎn)環(huán)境。我現(xiàn)在每天的工作流里Claude Code 仍然像一名實習(xí)生我會給它清晰的任務(wù)說明、約束條件和驗收標(biāo)準(zhǔn)它負(fù)責(zé)快速出活我負(fù)責(zé)把關(guān)方向和質(zhì)量。它寫出來的東西我會看它給的建議我會復(fù)核它跑出來的測試我會再跑一遍確認(rèn)。這個過程聽起來比“全自動寫代碼”慢但真正長期跑下來系統(tǒng)的穩(wěn)定性、團(tuán)隊的可維護(hù)性都遠(yuǎn)遠(yuǎn)好于讓 AI 自由發(fā)揮的方案。開源生態(tài)里關(guān)于 Claude Code 的玩法一直在進(jìn)化MCP 協(xié)議也催生了不少新的集成方式。我的建議是保持關(guān)注但不要盲目追求花哨的用法。對生產(chǎn)級分布式系統(tǒng)來說能穩(wěn)定復(fù)現(xiàn)、能解釋清楚、能快速回滾永遠(yuǎn)比“看起來很酷”重要得多。先把這套“可驗證、可治理、可擴展”的原則落地再慢慢玩出屬于自己的最佳實踐這條路我試過走得通。 Claude Code實戰(zhàn)：構(gòu)建可驗證、可治理、可擴展的分布式系統(tǒng)
最近在帶團(tuán)隊做一套訂單中臺改造從單體往分布式微服務(wù)遷移壓力最大的不是寫業(yè)務(wù)代碼而是控質(zhì)量、控變更、控邊界。恰好這幾個月我們把 Claude Code 深度接進(jìn)了日常研發(fā)流程用它輔助設(shè)計、編碼、補測試、寫遷移腳本跑完一輪下來我最大的感受是這工具能不能發(fā)揮價值完全取決于你把它放在什么位置、用什么規(guī)則約束它。把它當(dāng)“自動補全”你得到的只是零散代碼片段把它當(dāng)成一個“能寫代碼的架構(gòu)師實習(xí)生”并且配好驗證、治理、擴展的整套規(guī)則它能實打?qū)嵉貛湍憬桓渡a(chǎn)級系統(tǒng)。這篇博文我想整理的就是這套用法如何用 Claude Code 構(gòu)建一個可驗證、可治理、可擴展的生產(chǎn)級分布式系統(tǒng)。內(nèi)容會覆蓋環(huán)境配置、驗證策略、代碼治理、架構(gòu)擴展以及一套可以直接復(fù)制的實操流程。不管是剛接觸 Claude Code 的后端工程師還是想在團(tuán)隊里推 AI 輔助開發(fā)的技術(shù)負(fù)責(zé)人都能從中拿到能落地的方案。1. 先搞清楚目標(biāo)可驗證、可治理、可擴展到底意味著什么1.1 三個關(guān)鍵詞不是擺設(shè)是生產(chǎn)系統(tǒng)的生死線“可驗證、可治理、可擴展”這三個詞平時在技術(shù)方案里見得很多但真落到分布式系統(tǒng)上每一環(huán)都有非常具體的指向?？沈炞C說的是你交付出去的每一個服務(wù)、每一次改動都能通過自動化手段證明它是對的。不是“本地跑通了”而是單元測試、契約測試、集成測試、端到端驗證全部能過數(shù)據(jù)變更能回滾接口改動能被契約約束住。分布式系統(tǒng)里服務(wù)之間的調(diào)用鏈拉得很長A 服務(wù)改了接口B 服務(wù)可能到上線那天才知道壞了。沒有驗證體系改代碼就是在踩地雷?？芍卫碚f的是團(tuán)隊多人協(xié)作時AI 生成的代碼不是失控的。誰在什么時候改了哪塊邏輯、用了什么模型、跑了哪些命令全部有日志、有權(quán)限控制、有審查機制。這一點最容易被人忽視尤其是個人開發(fā)者用 Claude Code 的時候感覺“它能直接改文件太爽了”但在生產(chǎn)系統(tǒng)里這種權(quán)限裸奔狀態(tài)就是事故的溫床?？蓴U展說的是系統(tǒng)的架構(gòu)演進(jìn)能跟上業(yè)務(wù)增長。今天你是 2 個服務(wù)的單體集群明天可能是 20 個微服務(wù)后天可能是跨地域多活。用 Claude Code 寫出來的代碼如果一開始就是貼死業(yè)務(wù)邏輯的“面條代碼”那擴展的時候不是改代碼是推翻重來。1.2 Claude Code 在分布式系統(tǒng)建設(shè)中扮演什么角色我的定位是它是“結(jié)對程序員 代碼審查助手 運維腳本生成器”三合一但它不是架構(gòu)師。架構(gòu)方向的決策必須由人來做Claude Code 負(fù)責(zé)的是把決策落實到代碼層面并且?guī)湍惆雅K活累活干了。舉個例子我讓它幫我生成一個分布式限流組件它能在幾分鐘內(nèi)給你一個包含令牌桶算法、Redis 存儲、Spring AOP 接入的完整模塊單元測試都給你寫好。但如果我問它“我們到底應(yīng)該用 Redis 分布式鎖還是 ZooKeeper 鎖”它能給出的只是泛泛的優(yōu)劣勢對比真正拍板還得靠你自己對業(yè)務(wù)場景的理解。所以我的團(tuán)隊里立了一條規(guī)矩Claude Code 輸出的所有架構(gòu)設(shè)計類內(nèi)容必須經(jīng)過一名高級工程師人工審查后才允許進(jìn)入代碼庫。這不是不信任工具而是對生產(chǎn)系統(tǒng)的敬畏。1.3 我搭建這套體系前的配置基線在進(jìn)入具體章節(jié)之前先把我這邊的基礎(chǔ)環(huán)境交代一下后面講的所有操作都是基于這套環(huán)境Claude Code 版本持續(xù)保持最新版npm 全局安裝執(zhí)行方式macOS 本地終端 CI 服務(wù)器GitHub Actions遠(yuǎn)程執(zhí)行集成工具VS Code 插件 MCPModel Context Protocol連接 MySQL、Redis、Kafka權(quán)限模式默認(rèn)非自動執(zhí)行所有寫文件/執(zhí)行命令操作需人工確認(rèn)會話管理按項目隔離每個服務(wù)一個獨立工作區(qū)這套配置的核心思路是Claude Code 有很強的能力但我要把它關(guān)在“籠子”里使用。讓它能看見完整的項目上下文能提出方案、寫代碼、跑測試但所有副作用操作都要經(jīng)過確認(rèn)和記錄后面會展開講。2. 環(huán)境準(zhǔn)備與基礎(chǔ)配置把地基打牢再開工2.1 安裝與初始化的完整步驟Claude Code 的安裝非常簡單一條 npm 命令搞定前提是你的機器上已經(jīng)有 Node.js 18 環(huán)境npm install -g anthropic-ai/claude-code安裝完成后在終端輸入claude進(jìn)入交互式界面首次使用會引導(dǎo)你完成認(rèn)證登錄。這里要說一個我踩過的坑如果你在公司內(nèi)網(wǎng)環(huán)境或者網(wǎng)絡(luò)代理設(shè)置比較復(fù)雜登錄環(huán)節(jié)容易卡住甚至報 403。我遇到過幾次排查下來基本都是代理環(huán)境變量導(dǎo)致的 SSL 握手問題解決辦法是清理環(huán)境變量或者確認(rèn)代理對 Anthropic 域名的訪問策略。認(rèn)證完成之后我強烈建議你做的第一件事不是開始寫代碼而是運行claude config set -g theme dark claude config set -g verbose false把界面和日志先調(diào)整到適合長期工作的狀態(tài)。默認(rèn)配置下日志很啰嗦會刷掉你的注意力。2.2 在 VS Code 里集成 Claude Code很多人習(xí)慣在 IDE 里使用 AI 工具Claude Code 官方提供了 VS Code 插件安裝后可以在編輯器側(cè)邊欄直接打開會話面板。安裝方式有兩種在 VS Code 擴展市場搜索 “Claude Code” 直接安裝如果你已經(jīng)在終端里安裝過 Claude Code擴展會自動識別到本機的 Claude Code 可執(zhí)行文件這里有一個重要配置插件默認(rèn)會繼承終端里的認(rèn)證狀態(tài)但如果你的終端用的是 zsh 而 VS Code 里跑的是默認(rèn) shell可能出現(xiàn)“找不到 claude 命令”的問題。需要在 VS Code 的 settings.json 里指定 claude 的絕對路徑比如{ claude-code.path: /usr/local/bin/claude }路徑可以用which claude查出來。2.3 CLAUDE.md讓 AI 讀懂你的項目規(guī)則Claude Code 最核心的配置是項目根目錄下的CLAUDE.md文件。這個文件相當(dāng)于給 AI 的“入職手冊”在每次會話開始時Claude Code 會自動讀取它作為理解項目、執(zhí)行任務(wù)的背景知識。我的團(tuán)隊里每個服務(wù)倉庫的CLAUDE.md都會包含以下幾塊內(nèi)容你可以直接參照這個結(jié)構(gòu)寫# 項目名稱 一句話描述項目定位如訂單中臺 - 核心交易服務(wù) ## 技術(shù)棧 - 語言/框架Java 17 Spring Boot 3.2 - 存儲MySQL 8.0主庫/ Redis 7緩存 - 消息Kafka 3.x - 部署Docker Kubernetes ## 項目結(jié)構(gòu) - 模塊劃分controller / service / repository / domain / infrastructure - 分層規(guī)則controller 層不允許寫業(yè)務(wù)邏輯repository 層不允許出現(xiàn)業(yè)務(wù)判斷 ## 編碼規(guī)范 - 所有對外接口必須返回統(tǒng)一響應(yīng)體 ResultT - 所有金額字段必須用 BigDecimal禁止用 Double - 創(chuàng)建/更新時間統(tǒng)一用 Long 類型毫秒時間戳 ## 測試要求 - 每個 service 方法必須有對應(yīng)單元測試 - 對外接口變更必須同步更新契約測試文件 - 本地跑全量測試命令./mvnw verify ## 禁止事項 - 不要修改 pom.xml 的依賴版本除非明確要求 - 不要直接操作生產(chǎn)數(shù)據(jù)庫所有變更走遷移腳本 - 不要在 service 里直接 new 線程池必須使用項目統(tǒng)一線程池組件這個文件的作用非常大。沒有它的時候Claude Code 生成的代碼每一份都“似曾相識但又不完全對”有它之后生成的代碼里 80% 的規(guī)范問題直接消失。我甚至建議給全局加一個~/.claude/CLAUDE.md把你個人的通用編碼偏好寫進(jìn)去這樣不管開哪個項目AI 都會默認(rèn)遵守你的習(xí)慣。2.4 權(quán)限控制別讓 AI 裸奔Claude Code 默認(rèn)在執(zhí)行寫文件、運行命令等操作時會向你請求確認(rèn)但在某些模式下比如--dangerously-skip-permissions它會跳過所有確認(rèn)這個模式我在生產(chǎn)環(huán)境里是絕對禁用的。我這邊推薦的做法是在啟動會話時就明確權(quán)限邊界claude --allowedTools Read,Edit,Write,Bash(npm test:*) --disallowedTools Bash(git push),Bash(rm -rf)上面的命令允許 Claude Code 讀文件、編輯文件、運行測試命令但禁止執(zhí)行g(shù)it push和危險的刪除命令。你可以根據(jù)實際場景調(diào)整允許/禁止的工具列表我的原則是能讓它干活的權(quán)限要給但會給生產(chǎn)環(huán)境造成不可逆影響的操作一律禁止自動執(zhí)行。權(quán)限配置的關(guān)鍵參數(shù)我整理成了表格方便你對照使用配置項作用推薦設(shè)置--allowedTools允許自動執(zhí)行的操作白名單按需授權(quán)只給當(dāng)前任務(wù)需要的--disallowedTools禁止執(zhí)行的操作黑名單加入高危命令如git push --force、生產(chǎn)環(huán)境刪除操作--permission-mode權(quán)限模式默認(rèn)確認(rèn)模式禁用dangerously-skip-permissions--model指定使用的模型根據(jù)任務(wù)復(fù)雜度選擇簡單任務(wù)用小模型省錢--max-turns單次會話最大輪數(shù)防止死循環(huán)消耗配額2.5 用 MCP 打通數(shù)據(jù)源讓 AI 能“看見”數(shù)據(jù)庫Claude Code 的上下文窗口再大也不可能預(yù)知你的業(yè)務(wù)數(shù)據(jù)長什么樣。所以我們要用 MCP 把開發(fā)環(huán)境的數(shù)據(jù)庫、消息隊列、緩存等基礎(chǔ)設(shè)施“接入”到 AI 的視野里。MCP 的配置也是寫在CLAUDE.md或者單獨的配置文件里我舉個例子連接 MySQL 的配置片段## MCP Servers - mysql: 通過 mysql-mcp-server 連接schema 信息自動同步 命令: npx mysql-mcp-server --host 127.0.0.1 --port 3306 --user dev --password dev123配置好之后你可以直接對 Claude Code 說“幫我查一下訂單表結(jié)構(gòu)找出所有金額字段”它能通過 MCP 直接查庫并返回結(jié)果這比貼建表語句給它是完全不同的體驗。但這里有一個重要提醒在生產(chǎn)環(huán)境千萬不要給 MCP 配寫權(quán)限只讓它讀 schema、讀數(shù)據(jù)用于理解業(yè)務(wù)任何寫操作必須走人工確認(rèn)或遷移腳本。3. 可驗證性如何確保 AI 寫出來的代碼真的能上線3.1 AI 生成代碼最大的風(fēng)險不是“寫錯”而是“看起來對”我發(fā)現(xiàn)很多團(tuán)隊不敢用 AI 寫生產(chǎn)代碼核心原因不是模型能力不行而是 AI 生成代碼有一種迷惑性——它語法正確、結(jié)構(gòu)完整、甚至注釋都寫好了但業(yè)務(wù)邏輯可能完全是錯的。舉一個我實際遇到的例子。讓 Claude Code 實現(xiàn)一個“訂單超時自動關(guān)閉”功能它很自然地寫出了一個定時任務(wù)每五分鐘掃描一次訂單表把超過三十分鐘未支付的訂單置為關(guān)閉狀態(tài)。單看代碼邏輯完全沒問題。但懂業(yè)務(wù)的人一眼就能看出問題這個方案在分布式環(huán)境下是錯的。如果系統(tǒng)部署了多個實例定時任務(wù)會在每個實例上同時跑不做分布式鎖就會產(chǎn)生重復(fù)掃描、重復(fù)更新甚至并發(fā)扣減庫存的嚴(yán)重事故。這就是 AI 編碼的陷阱它擅長生成“符合常規(guī)模式的代碼”但不理解你系統(tǒng)的特殊約束。解法只有一個——把所有關(guān)鍵行為的驗證閉環(huán)前置到開發(fā)流程里用測試、契約、檢查機制把錯誤擋在上線之前。3.2 三層驗證架構(gòu)單測、契約、端到端我這邊把驗證分成三層每一層對應(yīng)不同粒度的保障第一層是單元測試覆蓋最小業(yè)務(wù)單元的輸入輸出和邊界條件。這一層最容易讓 Claude Code 自動生成但也是我審查最嚴(yán)格的一層。我會要求它對每個 service 方法生成測試包括正常路徑、異常路徑、邊界值、并發(fā)場景生成完再讓人工抽查。第二層是契約測試這是分布式系統(tǒng)的關(guān)鍵護(hù)城河。服務(wù)之間通過 HTTP 或消息通信接口的請求響應(yīng)結(jié)構(gòu)一旦變化下游服務(wù)立刻遭殃。我們用 Pact 或者 Spring Cloud Contract 做消費者驅(qū)動的契約測試把每個服務(wù)的對外接口規(guī)范固化成文件任何一方改動契約CI 就會報錯逼著雙方協(xié)商兼容方案。第三層是端到端測試用 Testcontainers 起一套完整的依賴環(huán)境MySQL、Redis、Kafka模擬真實業(yè)務(wù)鏈路跑通核心流程。這一層不是為了測每一個細(xì)節(jié)而是驗證系統(tǒng)級的行為符合預(yù)期比如“下單 → 扣庫存 → 發(fā)消息 → 訂單狀態(tài)變更”這條主鏈路。這三層驗證跑下來我才能放心地把 Claude Code 生成的代碼合入主干分支。3.3 讓 Claude Code 先生成測試再生成實現(xiàn)操作上有一個非常有效的小技巧不要讓它直接寫實現(xiàn)代碼而是先讓它寫測試。我的做法是這樣的拿一個“用戶積分變更”的需求舉例我在會話里敲入請為 UserScoreService.changeScore(Long userId, int delta) 方法編寫單元測試。 業(yè)務(wù)規(guī)則 1. 積分為負(fù)數(shù)時拋 IllegalArgumentException 2. 用戶不存在時拋 UserNotFoundException 3. 變更后的積分不能小于 0 請先寫測試再根據(jù)測試反推實現(xiàn)。這么說的好處是Claude Code 會先基于業(yè)務(wù)規(guī)則定義預(yù)期行為然后為了通過測試去寫實現(xiàn)代碼。這樣生成的代碼天然帶著“驗證基因”而不是天馬行空地自由發(fā)揮。我實測下來用這種方式生成的代碼review 時發(fā)現(xiàn)的邏輯錯誤數(shù)量明顯減少。3.4 把驗證嵌入 CI/CDAI 生成的代碼也要過流水線Claude Code 不僅能幫你寫業(yè)務(wù)代碼還能幫你把這些驗證流程集成到 CI 流水線里。我讓它在 GitHub Actions 里自動生成了一套工作流核心階段如下name: verify on: [push, pull_request] jobs: test: runs-on: ubuntu-latest services: mysql: image: mysql:8.0 env: MYSQL_ROOT_PASSWORD: test ports: [3306:3306] steps: - uses: actions/checkoutv4 - name: Run unit tests run: ./mvnw test - name: Run contract tests run: ./mvnw verify -Pcontract-tests - name: Run end-to-end tests run: ./mvnw verify -Pe2e-tests每一個 PR 進(jìn)來這套流水線都會完整跑一遍三層驗證任何一層失敗都不允許合并。這樣做還有一個好處Claude Code 提出了一些方案改動時它會先看 CI 跑不跑得過而不是只拿“本地編譯過了”當(dāng)理由。這是可驗證性的最終保證。4. 可治理性多人協(xié)作下如何管住 AI 的“手”4.1 治理的核心可追溯、可審計、可控回滾當(dāng)團(tuán)隊里每個人都用 Claude Code 寫代碼時最大的問題不是代碼質(zhì)量問題而是失控問題。A 讓 AI 改了配置B 讓 AI 動了接口C 讓 AI 跑了數(shù)據(jù)庫遷移腳本——這些操作如果沒有記錄、沒有審批、沒有回滾通道系統(tǒng)遲早被自己人搞掛?？勺匪菔钦f每一段由 AI 生成的改動都能追溯到對應(yīng)的需求和操作者?？蓪徲嬍钦f每個關(guān)鍵動作都有日志留痕出了問題能復(fù)盤?？煽鼗貪L是說任何 AI 做的變更都有對應(yīng)的回滾方案絕不出現(xiàn)“改壞了沒法回”的局面。4.2 規(guī)范先行把約束寫進(jìn) CLAUDE.md在多人協(xié)作的場景下CLAUDE.md不僅僅是給 AI 看的規(guī)范更是團(tuán)隊對 AI 的使用公約。除了前面提到的技術(shù)棧和結(jié)構(gòu)約束我們還加了一些治理條款## AI 使用治理規(guī)則必須遵守 1. 任何涉及數(shù)據(jù)庫表結(jié)構(gòu)變更的操作必須先輸出遷移腳本并提交 DBA 審查 2. 修改對外接口簽名或請求響應(yīng)結(jié)構(gòu)時必須同步更新契約測試并通知下游負(fù)責(zé)人 3. 生成代碼時必須包含完整注釋注明業(yè)務(wù)背景和設(shè)計理由禁止只有“根據(jù)需求實現(xiàn)”這種無意義注釋 4. 禁止 AI 直接修改 Kubernetes 部署文件中的鏡像版本發(fā)布操作由運維流水線統(tǒng)一處理 5. 所有 AI 會話的關(guān)鍵輸出保存到 docs/ai-sessions/ 目錄按日期命名這些條款不是限制 AI 的能力而是把不確定性壓縮到可控范圍。尤其第 5 條我會讓 Claude Code 在每次重要會話結(jié)束時自動把對話摘要、產(chǎn)出物、未決問題導(dǎo)出成 Markdown 文件這樣即使寫代碼的人休假了后來的人打開目錄就能看到那次改動的完整背景。4.3 代碼審查時AI 生成代碼的特殊審查點傳統(tǒng)的人工代碼審查關(guān)注的是業(yè)務(wù)邏輯正確性、代碼風(fēng)格、性能問題。但審查 AI 生成的代碼我額外加了幾個檢查項這里整理成表格審查維度檢查點原因真實性依賴的包、API 是否存在版本號是否真實AI 會“發(fā)明”不存在的庫尤其是小眾工具庫安全性是否有硬編碼密鑰、SQL 注入、越權(quán)風(fēng)險AI 默認(rèn)生成“能跑”的代碼不默認(rèn)安全的代碼業(yè)務(wù)匹配是否理解項目特有的業(yè)務(wù)規(guī)則和約束容易生成通用方案忽略你系統(tǒng)的特殊性邊界處理超時、重試、熔斷等容錯邏輯是否完整分布式系統(tǒng)里這些比業(yè)務(wù)主流程更重要性能隱患是否存在 N1 查詢、循環(huán)調(diào)用 RPC、大事務(wù)AI 容易生成代碼正確但性能災(zāi)難的寫法我一般要求團(tuán)隊里每個人在 review AI 生成代碼時按這個表格逐項過一遍而不是像以前那樣憑感覺掃一眼就點通過。這套做法推行之后我們合并到主干的 AI 生成代碼線上問題率降了一個數(shù)量級。4.4 審計日志Claude Code 自己的“黑匣子”Claude Code 默認(rèn)會在會話中進(jìn)行詳細(xì)的操作記錄包括每次調(diào)用模型的輸入輸出、執(zhí)行過的命令、修改過的文件。但在多人協(xié)作環(huán)境下默認(rèn)的日志放在各自本地沒法統(tǒng)一審計。我們的做法是給開發(fā)者統(tǒng)一配置日志輸出目錄并通過 CI 流程收集會話記錄。具體的配置方式是在啟動 Claude Code 時指定日志路徑claude --session-log-path ~/.claude/logs然后在 CI 中加入一步掃描這些日志文件并上傳到團(tuán)隊內(nèi)部的存儲。這樣做的好處是當(dāng)你發(fā)現(xiàn)某段生產(chǎn)代碼有問題時可以立刻反查是在哪個會話里被生成的、當(dāng)時的上下文是什么、有沒有執(zhí)行過額外操作這比“開發(fā)者回憶”靠譜得多。4.5 發(fā)布管控AI 生成的改動不能直接上生產(chǎn)最后一條治理紅線是發(fā)布管控。我定的規(guī)矩是Claude Code 生成或修改的代碼必須先通過常規(guī)的 PR 流程合并到主干分支再通過 CI 流水線完成部署。任何“讓 AI 直接改生產(chǎn)環(huán)境”的行為在我的團(tuán)隊里都屬于嚴(yán)重違規(guī)。有些人可能會覺得這太保守了AI 改產(chǎn)線腳本更快。但對生產(chǎn)系統(tǒng)來說快不是第一位的穩(wěn)才是。我寧可在治理流程上多花十分鐘也不愿在生產(chǎn)事故后花十個小時復(fù)盤。這個原則同樣適用于你個人的項目哪怕只有你自己一個開發(fā)者也應(yīng)該走完整的發(fā)布鏈路這是職業(yè)習(xí)慣問題。5. 可擴展性從架構(gòu)設(shè)計到代碼落地讓系統(tǒng)能跟著業(yè)務(wù)一起長大5.1 擴展性不是事后補的是設(shè)計出來的一個分布式系統(tǒng)能不能輕松擴容不取決于你最后用了多少臺機器而取決于你寫前幾個服務(wù)時怎么設(shè)計的。如果服務(wù)之間有隱式的共享數(shù)據(jù)庫、繞過 API 直接訪問其他服務(wù)的表、或者把有狀態(tài)數(shù)據(jù)都放在本地內(nèi)存里那系統(tǒng)的擴展天花板在你設(shè)計的第一天就注定了。用 Claude Code 輔助開發(fā)時我會在項目啟動前就讓它輸出一份“擴展性設(shè)計檢查清單”把它作為后續(xù)所有代碼生成的約束條件。這份檢查清單包括服務(wù)是否做到無狀態(tài)化Session 是否外移到 Redis服務(wù)之間的調(diào)用是否全部通過 API 網(wǎng)關(guān)適配沒有直接暴露內(nèi)部服務(wù)地址數(shù)據(jù)庫層面是否有分庫分表預(yù)案當(dāng)前表結(jié)構(gòu)是否預(yù)留了分片鍵核心鏈路是否使用消息隊列解耦還是寫死了同步調(diào)用所有第三方依賴是否有超時、重試、熔斷配置這份清單一旦定下來就在CLAUDE.md里固化成規(guī)范Claude Code 生成新服務(wù)時就會自動帶上這些考量。5.2 讓 Claude Code 幫你做架構(gòu)評審很多人不知道 Claude Code 還有一個很好用的場景架構(gòu)評審。在寫代碼之前我經(jīng)常把當(dāng)前系統(tǒng)的部署圖、核心接口定義、數(shù)據(jù)庫表結(jié)構(gòu)喂給 Claude Code然后讓它以“外部架構(gòu)師”的視角提建議。比如我說“我們目前訂單服務(wù)訪問數(shù)據(jù)庫耗時較高并發(fā)量上來了之后接口響應(yīng)變得越來越慢請幫忙分析可能原因并給出優(yōu)化建議?！彼鼤敵鲆话娼Y(jié)構(gòu)化分析包含索引問題、連接池配置、緩存缺失、慢查詢等多個維度并且給出對應(yīng)的代碼改動建議。但這里我要潑一盆冷水AI 的架構(gòu)建議只能作為參考不能作為決策依據(jù)。它沒有你系統(tǒng)的全量指標(biāo)看不到真實的鏈路追蹤更不了解團(tuán)隊的維護(hù)能力。我會把它的輸出當(dāng)成一份“待驗證的候選方案列表”挑出有道理的方案再人工驗證而不是拿過來就用。5.3 用 AI 生成可復(fù)用的分布式基礎(chǔ)組件分布式系統(tǒng)里有很多重復(fù)造輪子的基礎(chǔ)組件分布式鎖、分布式 ID 生成器、限流器、鏈路追蹤工具類、統(tǒng)一異常處理。這些組件的特點是模式固定、邏輯相對通用非常適合讓 Claude Code 生成初版再由團(tuán)隊里的高級工程師審查打磨。舉一個實際例子我讓 Claude Code 生成一個基于 Redis 的分布式鎖工具類它給出的核心實現(xiàn)包含public class RedisDistributedLock { private final StringRedisTemplate redisTemplate; public boolean tryLock(String lockKey, String requestId, long expireSeconds) { Boolean result redisTemplate.opsForValue() .setIfAbsent(lockKey, requestId, Duration.ofSeconds(expireSeconds)); return Boolean.TRUE.equals(result); } public boolean releaseLock(String lockKey, String requestId) { String script if redis.call(get, KEYS[1]) ARGV[1] then return redis.call(del, KEYS[1]) else return 0 end; Long result redisTemplate.execute( new DefaultRedisScript(script, Long.class), Collections.singletonList(lockKey), requestId ); return Long.valueOf(1L).equals(result); } }這段代碼的亮點是釋放鎖的時候用了 Lua 腳本保證原子性并且校驗了持有者身份避免了誤刪別人的鎖。這些細(xì)節(jié)如果靠人從零寫可能也能寫出來但 AI 在幾分鐘內(nèi)給出一個可用的初版效率提升是實打?qū)嵉摹?.4 規(guī)范生成模塊化代碼避免“一鍋粥”可擴展性的敵人永遠(yuǎn)是不合理的耦合。我見過太多系統(tǒng)一開始是一個大單體后來拆微服務(wù)的時候發(fā)現(xiàn)業(yè)務(wù)邏輯糾纏在一起根本切不開。Claude Code 寫代碼時如果沒有任何約束它會傾向于把所有相關(guān)邏輯放在最方便的位置很快形成“上帝類”和循環(huán)依賴。我用的辦法是在項目的CLAUDE.md里明確規(guī)定模塊邊界和依賴規(guī)則。比如訂單服務(wù)的代碼生成規(guī)則## 模塊依賴規(guī)則 - domain 模塊純業(yè)務(wù)實體與業(yè)務(wù)規(guī)則不依賴任何框架和其他模塊 - application 模塊用例編排依賴 domain 模塊 - infrastructure 模塊數(shù)據(jù)庫、消息、外部接口實現(xiàn)依賴 domain 模塊接口禁止反向依賴 - controller 模塊HTTP 層適配依賴 application 模塊這樣規(guī)定之后Claude Code 生成新代碼時就會自動放到合理的位置不會出現(xiàn) controller 里寫 SQL 這種低級問題。模塊邊界清晰了未來系統(tǒng)的每個服務(wù)才能獨立演進(jìn)、獨立擴縮容。5.5 緩存、消息隊列與數(shù)據(jù)庫擴展的 AI 輔助分布式系統(tǒng)擴容時最先遇到的瓶頸往往是存儲和流量。我可以讓 Claude Code 幫我做以下幾類擴展準(zhǔn)備緩存擴展方面讓它分析現(xiàn)有接口的緩存策略標(biāo)出哪些接口缺少緩存穿透、擊穿、雪崩的保護(hù)然后生成對應(yīng)的更新代碼。消息隊列擴展方面讓它根據(jù)業(yè)務(wù)事件設(shè)計 Topic 劃分方案生成生產(chǎn)者、消費者的骨架代碼并配置好重試和死信隊列。數(shù)據(jù)庫擴展方面讓它分析大表和慢查詢生成索引優(yōu)化建議和分庫分表預(yù)研代碼。這些操作我不建議一次性全部交給 AI 自動完成而是每完成一項就進(jìn)行人工 review 和測試。擴展性建設(shè)是一個持續(xù)演進(jìn)的過程不是一錘子買賣。把它拆成一個個小任務(wù)夾在迭代里做反而比“下一版大重構(gòu)”更容易落地。6. 實操全流程從零到一構(gòu)建一個生產(chǎn)級分布式服務(wù)6.1 場景設(shè)定搭建“積分服務(wù)”并接入主系統(tǒng)為了讓整個流程更直觀我拿一個具體的例子演示完整操作。假設(shè)業(yè)務(wù)上需要一個獨立的積分服務(wù)包含積分發(fā)放、積分查詢、積分過期回收三個核心能力并且需要支持后續(xù)并發(fā)量翻倍后的水平擴展。我的第一步操作是在會話里給 Claude Code 清晰的需求描述并且告訴它我們既有的技術(shù)規(guī)范和約束。描述越具體產(chǎn)出越可控。請在 services/points-service 下創(chuàng)建積分服務(wù)模塊。 功能需求 1. 提供積分發(fā)放接口內(nèi)部調(diào)用increasePoints 2. 提供積分查詢接口getUserPoints 3. 提供積分過期回收的定時任務(wù)按過期時間批量關(guān)閉過期積分 技術(shù)約束 - Java 17 Spring Boot 3.2 - 數(shù)據(jù)庫 MySQL表結(jié)構(gòu)按領(lǐng)域模型設(shè)計須包含樂觀鎖版本號字段 - 對外接口走公司統(tǒng)一 API 網(wǎng)關(guān)協(xié)議 - 所有金額/積分字段采用 Long 存儲單位個 - 模塊結(jié)構(gòu)遵循項目已有分層規(guī)范 - 編寫完整單元測試6.2 查看 Claude Code 的產(chǎn)出物結(jié)構(gòu)收到需求后Claude Code 會在工作區(qū)里創(chuàng)建對應(yīng)的目錄結(jié)構(gòu)。一次典型生成出來的骨架大概是這樣的services/points-service/ ├── pom.xml ├── src/main/java/com/example/points/ │ ├── PointsServiceApplication.java │ ├── controller/PointsController.java │ ├── application/PointsApplicationService.java │ ├── domain/model/PointsAccount.java │ ├── domain/model/PointsRecord.java │ ├── domain/repository/PointsRepository.java │ ├── domain/service/PointsExpiryCalculator.java │ └── infrastructure/ │ ├── persistence/PointsRepositoryImpl.java │ ├── message/PointsEventPublisher.java │ └── config/PointsDataSourceConfig.java ├── src/main/resources/ │ ├── application.yml │ └── db/migration/V1__create_points_tables.sql └── src/test/java/com/example/points/ ├── domain/PointsExpiryCalculatorTest.java └── application/PointsApplicationServiceTest.java這個結(jié)構(gòu)已經(jīng)基本符合我們團(tuán)隊的分層規(guī)范了。遷移腳本、配置、測試一股腦兒生成好我只需要逐項審查確認(rèn)。整個過程從零點開始到初步可跑狀態(tài)不會超過十分鐘這在以前至少是半天的工作量。6.3 關(guān)鍵代碼實現(xiàn)的審查與修正當(dāng)然生成的代碼不能無腦接受。我以積分過期回收的定時任務(wù)為例展示一下審查時需要注意的細(xì)節(jié)。Claude Code 生成的初版可能是基于Scheduled(cron 0 */5 * * * ?)的本地定時任務(wù)邏輯上也能跑。但放到分布式環(huán)境里需要保證多實例部署時不重復(fù)執(zhí)行。所以我在 review 時會要求它改成基于 Redis 分布式鎖的方案并且增加“每次掃描分頁處理、單條處理失敗不影響批次整體”的容錯邏輯。我會在會話里直接提出修改意見當(dāng)前實現(xiàn)存在兩個問題 1. 多實例部署時定時任務(wù)會重復(fù)執(zhí)行請加入 Redis 分布式鎖保護(hù) 2. 掃描邏輯需要分頁處理避免一次性加載全部過期記錄導(dǎo)致內(nèi)存溢出 請修改實現(xiàn)并補充對應(yīng)的單元測試。Claude Code 會基于反饋修改代碼這個過程我們稱之為“AI 代碼迭代循環(huán)”。一般經(jīng)過兩三輪這樣的修正生成的代碼就能達(dá)到上線標(biāo)準(zhǔn)。6.4 讓 AI 生成 Dockerfile 與 Kubernetes 部署清單生產(chǎn)系統(tǒng)的最后一步是部署。我同樣會讓 Claude Code 基于已有項目的部署模板為積分服務(wù)生成 Dockerfile 和 Kubernetes 配置。生成時它會自動帶上健康檢查、資源限制、優(yōu)雅停機等生產(chǎn)必備配置。Dockerfile 的關(guān)鍵內(nèi)容如下FROM maven:3.9-eclipse-temurin-17 AS builder COPY . /workspace WORKDIR /workspace RUN mvn clean package -DskipTests FROM eclipse-temurin:17-jre COPY --frombuilder /workspace/target/points-service.jar /app/app.jar EXPOSE 8080 ENTRYPOINT [java, -jar, /app/app.jar]Kubernetes 部署文件里它也會自動加上livenessProbe和readinessProbe的配置保證實例在啟動完成前不會被流量打到在異常時能被自動重啟。這些細(xì)節(jié)對一個生產(chǎn)系統(tǒng)來說至關(guān)重要也不會被 AI 漏掉。6.5 運行全鏈路驗證并記錄會話在所有文件生成和修正完成之后我要求 Claude Code 跑一遍完整的驗證命令鏈條編譯、單測、契約測試、構(gòu)建 Docker 鏡像然后把整次會話的關(guān)鍵決策摘要導(dǎo)出到docs/ai-sessions/2025-xx-xx-points-service.md作為后續(xù)審計和追溯的依據(jù)。這一步做完一個生產(chǎn)級分布式服務(wù)才算真正交付。從需求到上線過程中 AI 承擔(dān)了大約七成的編碼和配置工作剩下三成的人工工作集中在需求明確、方案決策、代碼審查和最終驗證上。這個比例是我們在實踐中覺得比較舒服的配比——既能提升效率又能守住質(zhì)量底線。7. 常見問題與排查技巧實錄7.1 安裝失敗或登錄 403我自己和團(tuán)隊同事在安裝和登錄階段遇到的問題最多這里把典型現(xiàn)象和解決辦法整理出來現(xiàn)象可能原因解決辦法npm 安裝報權(quán)限錯誤Node.js 安裝目錄權(quán)限不足用 nvm 管理 Node.js避免全局安裝權(quán)限問題登錄時瀏覽器回調(diào) 403代理環(huán)境變量干擾檢查HTTPS_PROXY等環(huán)境變量臨時清除后重試登錄半天跳轉(zhuǎn)不回來系統(tǒng)默認(rèn)瀏覽器兼容問題用claude login手動復(fù)制認(rèn)證鏈接到無痕窗口完成VS Code 插件找不到命令PATH 不一致在 settings.json 中顯式指定claude-code.path有一個通用排查思路先把所有第三方代理環(huán)境變量臨時清空回歸最干凈的網(wǎng)絡(luò)環(huán)境看問題是否消失。大部分登錄相關(guān)的詭異問題都是這一類原因引起的。7.2 會話中卡住或輸出中斷Claude Code 在處理特別長的上下文或者大規(guī)模重構(gòu)任務(wù)時偶爾會出現(xiàn)響應(yīng)中斷。我的經(jīng)驗是把大任務(wù)拆成小任務(wù)來問每次只讓它處理一個模塊或一個功能成功率會高很多。另外重要操作前先存?zhèn)€檔claude --resume # 或手動保存會話用 --continue 恢復(fù)--resume可以恢復(fù)最近的會話不怕中斷丟上下文。我還會在長任務(wù)里定期把中間成果 commit 到 git 分支這樣即使 AI 跑偏了也能輕松回退到正常狀態(tài)。7.3 MCP 讀不到數(shù)據(jù)庫或數(shù)據(jù)不一致MCP 連接數(shù)據(jù)庫后最常見的問題是連不上或查出來的數(shù)據(jù)不是最新的。排查步驟我一般按這個順序確認(rèn) MCP Server 使用的數(shù)據(jù)庫賬號有遠(yuǎn)程訪問權(quán)限如果走 SSH 隧道確認(rèn)隧道端口映射正確檢查 MCP 配置里是否指定了正確的 database 名稱確認(rèn)讀取走的是主庫還是從庫延遲是否影響判斷這里我特別提醒一點MCP 里讀到的數(shù)據(jù)只能用于理解業(yè)務(wù)不要讓它影響你的架構(gòu)決策。生產(chǎn)系統(tǒng)的判斷還是要以監(jiān)控大盤、鏈路追蹤和真實壓測數(shù)據(jù)為準(zhǔn)。7.4 配額和限額問題持續(xù)高強度使用 Claude Code尤其是團(tuán)隊多人共享賬號時很容易遇到請求頻率限制或者周配額耗盡的提示。這類問題沒有太多取巧空間我這邊是這么處理的日常小任務(wù)補注釋、格式化、寫測試樁代碼使用輕量模型不占用頂級模型配額重要架構(gòu)設(shè)計任務(wù)集中在一個會話里完成避免反復(fù)開啟新會話重復(fù)消耗團(tuán)隊按服務(wù)模塊分配使用責(zé)任避免多人同時跑重型任務(wù)高峰期錯峰使用把大規(guī)模重構(gòu)任務(wù)安排到非高峰時段執(zhí)行說到底配額管理也是治理的一部分。把它納入團(tuán)隊資源規(guī)劃里比臨時抱佛腳到處找解決辦法要靠譜得多。7.5 對話歷史保存與團(tuán)隊共享有些同事會問“Claude Code 怎么保存對話歷史”其實 CLI 模式下每次會話都有日志記錄關(guān)鍵是找到并善用這些日志。我之前已經(jīng)在治理章節(jié)提過設(shè)置統(tǒng)一日志路徑的方法這里再說一個團(tuán)隊場景下的實用技巧把重要的 AI 會話輸出以 Markdown 形式導(dǎo)出到一個共享倉庫。具體的做法是在會話結(jié)束時讓 Claude Code 自己把討論內(nèi)容和結(jié)論整理成文檔請將本次會話的關(guān)鍵決策、生成的文件列表、遺留問題整理為一份 Markdown 文檔保存到 docs/ai-sessions/2025-xx-xx-points-service-review.md這樣每次重要改動都有據(jù)可查團(tuán)隊其他人也能通過這些文檔了解 AI 參與開發(fā)的完整脈絡(luò)避免“在 AI 會話里發(fā)生過什么”成為黑箱。寫在最后我的一些真實體會折騰了大半年 Claude Code我自己最深的體會是AI 不是用來替代工程師思考的而是用來放大工程師的思考效率的。你越清楚自己要什么、越懂得設(shè)定邊界它給你的幫助就越大。反之如果你自己都不知道系統(tǒng)該怎么設(shè)計就把問題拋給它它只會用漂亮的代碼包裝你的混亂最后把麻煩留到生產(chǎn)環(huán)境。我現(xiàn)在每天的工作流里Claude Code 仍然像一名實習(xí)生我會給它清晰的任務(wù)說明、約束條件和驗收標(biāo)準(zhǔn)它負(fù)責(zé)快速出活我負(fù)責(zé)把關(guān)方向和質(zhì)量。它寫出來的東西我會看它給的建議我會復(fù)核它跑出來的測試我會再跑一遍確認(rèn)。這個過程聽起來比“全自動寫代碼”慢但真正長期跑下來系統(tǒng)的穩(wěn)定性、團(tuán)隊的可維護(hù)性都遠(yuǎn)遠(yuǎn)好于讓 AI 自由發(fā)揮的方案。開源生態(tài)里關(guān)于 Claude Code 的玩法一直在進(jìn)化MCP 協(xié)議也催生了不少新的集成方式。我的建議是保持關(guān)注但不要盲目追求花哨的用法。對生產(chǎn)級分布式系統(tǒng)來說能穩(wěn)定復(fù)現(xiàn)、能解釋清楚、能快速回滾永遠(yuǎn)比“看起來很酷”重要得多。先把這套“可驗證、可治理、可擴展”的原則落地再慢慢玩出屬于自己的最佳實踐這條路我試過走得通。