這次我們來看一個很有意思的技術命題把 20 萬行存量代碼完整遷移到另一套技術棧并且要求行為分毫不差。題目里的主角不是某個重構框架也不是某種自動化遷移工具而是 Claude 和 GPT 這類大模型輔助編碼工具。結果很直接如果你把整個倉庫直接丟給模型讓它們“一次性重寫”它們真的會懵。這里的“懵”不是說模型寫不出代碼而是它們很難在有限上下文里同時把握住全局狀態(tài)、邊界條件、錯誤處理、日志文本、數(shù)據(jù)格式這些隱性行為。語法層面的翻譯很容易行為層面的還原才是難點。對于金融系統(tǒng)、交易鏈路、協(xié)議解析、計費模塊這類“錯了就要出事故”的老代碼遷移失敗的代價遠高于重寫本身。這篇文章會圍繞這樣一個場景展開存量代碼規(guī)模大約 20 萬行目標技術棧已經定好對外接口和業(yè)務行為不能變Claude / GPT 負責輔助產出代碼人工負責設計基線、驗證行為和兜底審查。我會拆解為什么整倉重寫會失敗、正確做法是什么、行為驗證怎么做、批量遷移怎么管理以及遇到問題怎么排查。如果你正在做技術棧遷移或者想在真實項目里用大模型輔助重構這篇文章可以直接當作落地參考。1. 核心問題速覽先把這次要做的事拆成一張表后面所有步驟都圍繞這張表展開。問題項說明遷移對象約 20 萬行存量代碼包含業(yè)務邏輯、對外接口、數(shù)據(jù)讀寫、日志與異常處理遷移目標換到另一套技術棧例如 Java 到 Go、Python 到 Java、Node.js 到 Rust 等核心要求行為分毫不差同一輸入得到同一輸出接口協(xié)議、數(shù)據(jù)格式、錯誤碼、時序行為保持一致AI 輔助工具Claude / GPT 系列模型負責代碼生成、解釋片段、輔助審查、生成測試樣例主要風險行為漂移、隱性依賴、上下文窗口溢出、測試覆蓋不足、批量任務中斷正確路徑模塊拆分、行為基線先行、小步遷移、差分驗證、灰度切換錯誤路徑整倉直接重寫、只看編譯通過、只對比核心路徑、沒有歷史行為基線這張表明確了整個工程的邊界模型是輔助角色行為基線是驗收標準模塊拆分是執(zhí)行單元。2. 為什么“整倉重寫”會讓 Claude / GPT 直接懵掉先說結論把 20 萬行代碼一次性塞進對話要求模型“換個技術棧重寫且行為完全一致”這件事本身就不符合大模型當前的能力邊界。問題不出在模型智商而出在任務設計。2.1 上下文不是越大越好大模型對單次輸入的上下文長度有限即使能支持很長的上下文窗口真正有效的信息密度也會隨長度下降。20 萬行代碼全部丟進去模型真正能“專注”的往往是最近出現(xiàn)的內容。業(yè)務模塊之間的調用關系、共享的配置項、藏在某個古老工具類里的全局狀態(tài)這些信息要么被截斷要么被淹沒在大量無關代碼里。結果就是模型生成的代碼“看起來像”但一跑就漏行為。更好的做法是讓模型一次只處理一個模塊把模塊的入口、出口、依賴接口、已知邊界條件寫成精確說明而不是把整個倉庫當成一個黑盒。2.2 行為往往藏在邊界里技術棧遷移最容易出現(xiàn)的問題不是主流程跑不通而是邊界行為對不上。舊系統(tǒng)可能依賴了 Java 的默認字符集、C 語言的整數(shù)溢出規(guī)則、Python 的浮點精度、某個第三方庫的歷史 bug甚至依賴操作系統(tǒng)的時區(qū)設置。這些行為沒有寫進需求文檔只存在于代碼運行結果里。如果只讓模型“照著功能重寫”它基本不可能主動復刻這些細節(jié)。唯一可靠的解法是先建立行為基線用真實的輸入輸出把這些隱性行為固定下來再讓模型在基線約束內生成新代碼。2.3 模型擅長生成代碼不擅長替你驗證行為Claude 和 GPT 在生成代碼、解釋代碼、補測試樣例方面效率確實高但“行為是否完全一致”是一個需要執(zhí)行程序才能回答的問題。模型無法可靠地告訴你“我生成的代碼和舊系統(tǒng)在 1000 條邊界輸入下表現(xiàn)完全相同”它只能給你一個合理的推測。所以正確分工是模型負責“從模塊說明生成新代碼”測試框架和差分腳本負責“驗證新舊行為是否一致”人工負責“設計測試覆蓋和審查關鍵邏輯”。誰也別替誰干活。3. 適用場景與使用邊界3.1 哪些場景需要“行為分毫不差”這種要求通常出現(xiàn)在存量系統(tǒng)遷移里典型的例子包括交易系統(tǒng)或賬務系統(tǒng)歷史訂單、對賬邏輯、沖正規(guī)則必須完全一致通信協(xié)議?；驁笪慕馕瞿K字段偏移、字節(jié)序、錯誤碼不能變對接外部系統(tǒng)的 API 服務請求參數(shù)、響應結構、狀態(tài)碼一點都不能動報表或批處理任務輸出文件格式、字段順序、匯總口徑必須和舊版一致長期運行的定時任務日志格式、埋點數(shù)據(jù)、重試策略影響下游監(jiān)控。這類場景里業(yè)務邏輯本身不一定復雜但歷史積累的隱藏約束非常多。新代碼“功能正確”還不夠必須和舊代碼“行為等價”。3.2 哪些場景不適合讓 AI 直接改代碼如果舊系統(tǒng)沒有測試、沒有文檔、沒有可運行的構建環(huán)境第一步要做的是補基線而不是讓模型開寫。模型在沒有行為約束的情況下自由發(fā)揮只會產出“看起來合理但沒人敢上線”的新代碼。也不要讓模型直接處理密鑰、證書、生產環(huán)境地址、用戶隱私數(shù)據(jù)。喂給外部模型 API 的代碼片段必須經過脫敏凡是涉及敏感信息的倉庫最好使用本地模型或者先做字段替換。3.3 合規(guī)與數(shù)據(jù)安全邊界使用 Claude / GPT 輔助編碼時要注意以下幾點代碼倉庫如果是公司私有資產上傳前需要確認數(shù)據(jù)合規(guī)要求不要直接把包含 API Key、數(shù)據(jù)庫密碼、真實手機號、身份證號的測試數(shù)據(jù)放進 prompt模型生成的代碼默認只是建議版權歸屬和引入依賴的許可證需要人工審查對外接口、協(xié)議、密鑰相關的代碼遷移后要重新走安全評審。4. 遷移前置先建立行為基線這一步是整個工程的地基優(yōu)先級高于任何模型調用。4.1 代碼盤點和模塊劃分先把 20 萬行代碼按模塊拆分而不是按文件數(shù)量切。劃分原則是每個模塊有清晰的入口和出口可以獨立編譯、獨立測試、獨立描述行為。拆完之后確認模塊之間的依賴關系優(yōu)先遷移被依賴最少的葉子模塊再逐層向上?？梢杂萌缦虑鍐巫霰P點# 統(tǒng)計代碼行數(shù)按目錄匯總 find src -type f \( -name *.java -o -name *.go \) | xargs wc -l | sort -rn # 找到模塊入口和對外接口 grep -r public interface\|func\|def src/ --include*.java --include*.go | head # 梳理模塊依賴關系 # 這里建議用 IDE 或靜態(tài)分析工具導出調用關系圖不需要一次把所有依賴關系都畫出來但至少要畫出被遷移模塊的上下游。沒有依賴圖模型生成代碼時很難判斷該保留哪些接口。4.2 建立行為基線行為基線不是“跑一遍主流程截圖”而是可重復執(zhí)行的驗證資產。至少要做三件事第一整理現(xiàn)有測試用例梳理出哪些是單元測試、哪些是集成測試、哪些是手工回歸用例。第二為沒有測試的核心邏輯補充“輸入輸出樣本”也就是 golden fixture。每一條樣本包含輸入、期望輸出、關鍵中間狀態(tài)。跑舊系統(tǒng)時把這些 fixture 自動歸檔遷移后一鍵對拍。第三記錄非功能性行為包括返回碼、日志格式、超時時間、重試次數(shù)、數(shù)據(jù)排序方式、時區(qū)處理方式。這一步直接決定后面驗證階段的效果。基線越完整Claude / GPT 的行為約束越清晰。4.3 搭建新舊兩套可運行環(huán)境遷移期間需要同時運行舊系統(tǒng)和目標系統(tǒng)所以部署環(huán)境必須支持兩套并存。建議準備migration: source_repo: ./legacy_codebase target_repo: ./new_codebase languages: from: Java 8 to: Go 1.21 modules: - name: billing path: billing depends_on: [] - name: account path: account depends_on: [billing] verify: golden_dir: ./golden diff_timeout: 30 batch: concurrency: 2 retries: 3這份配置是給整個遷移工程用的模型只負責其中一個環(huán)節(jié)也就是“根據(jù)模塊說明生成目標代碼”。5. 模塊級遷移Claude / GPT 的正確打開方式5.1 給模型的輸入結構每次調用 Claude / GPT不要給太多代碼而是給一個結構化的任務包。下面這個 prompt 模板可以直接改寫成項目里的標準化 prompt你在幫助我把一個 Java 存量模塊遷移到 Go要求行為完全一致。 模塊名稱billing 模塊邊界 - 對外只暴露 Calc(OrderDTO) ReturnDTO 這一個方法 - 只依賴 account.AccountService - 不允許依賴其他 Java 內部類 關鍵行為要求 1. 輸入金額單位是“分”輸出單位是“元”保留兩位小數(shù) 2. 折扣比例超過 0.3 時錯誤碼返回 E1001message 必須是 discount too large 3. 空訂單號直接返回 nil 4. 外部異常一律包裝成 BizError不拋出運行時異常 5. 日志時間統(tǒng)一使用 UTC格式為 2006-01-02T15:04:05Z 請生成 Go 代碼 - 文件位于 internal/billing/service.go - 方法簽名已由接口定義給出不要改動 - 先列出你識別出的邊界條件再寫代碼 注意如果某些行為無法從描述中確定請列出具體問題不要猜。這個 prompt 的設計思路是把模塊邊界、行為約束、輸出格式、不確定點全部說清楚。模型一旦開始猜測接口細節(jié)就需要停下來提問或明確標注風險點這比讓它多寫一堆代碼更有價值。5.2 人工審查清單模型生成代碼后進入人工審查環(huán)節(jié)。重點看這些位置對外接口簽名是否和既定接口一致錯誤碼和錯誤信息是否逐字匹配數(shù)值計算是否保留了舊系統(tǒng)的精度規(guī)則并發(fā)和鎖的粒度是否一致日志、埋點、Metrics 是否被原樣保留外部依賴是否新增了未授權的第三方庫。審查不一定要逐行讀但至少要做“差異審查”把模型生成的代碼和舊代碼的關鍵邏輯按模塊對照用 diff 輔助找出模型自主發(fā)揮的地方。5.3 循環(huán)迭代的節(jié)奏一次生成大概率不過。更現(xiàn)實的節(jié)奏是模型生成 - 編譯 - 單測 - 差分對拍 - 把失敗信息回投給模型 - 模型修復 - 再驗證。把每一次驗證失敗的錯誤信息、測試輸入、期望輸出、實際輸出打包給模型模型往往能準確修掉問題而不是籠統(tǒng)地重新生成。6. 行為驗證把“分毫不差”翻譯成測試斷言遷移是否成功的唯一標準是新系統(tǒng)在相同輸入下產生和舊系統(tǒng)完全相同的行為。這個標準必須用代碼執(zhí)行來驗證。6.1 差分測試差分測試的核心思路是同一份輸入分別調用舊系統(tǒng)和新系統(tǒng)比較輸出。下面是一個通用腳本模板實際項目里需要替換兩條調用路徑import json import subprocess def run_legacy(input_data: dict) - dict: result subprocess.run( [java, -jar, legacy.jar], inputjson.dumps(input_data), capture_outputTrue, textTrue, timeout30 ) return json.loads(result.stdout) def run_new(input_data: dict) - dict: result subprocess.run( [./new_billing], inputjson.dumps(input_data), capture_outputTrue, textTrue, timeout30 ) return json.loads(result.stdout) def compare(input_data: dict) - None: old run_legacy(input_data) new run_new(input_data) if old ! new: print(fDIFF input{input_data}) print(flegacy{old}) print(fnew{new}) # 讀取 golden fixtures 批量對拍 with open(golden/billing_fixtures.json, r, encodingutf-8) as f: fixtures json.load(f) for case in fixtures: compare(case)這里有一個關鍵細節(jié)float 精度、字段順序、大小寫、時區(qū)差異都可能導致“看起來一樣但比較失敗”。所以 compare 函數(shù)里建議先做規(guī)范化例如統(tǒng)一 dict 的 key 順序、統(tǒng)一時間格式、對浮點數(shù)做小數(shù)點后 10 位的近似比較。6.2 golden 回歸差分測試是“新舊對打”golden 回歸是“新打存檔”。把舊系統(tǒng)的輸出保存為 golden 文件遷移后新系統(tǒng)的輸出直接和 golden 文件比對。推薦兩者都做有舊環(huán)境時優(yōu)先做差分測試省事且覆蓋全舊環(huán)境下線后用 golden regression 繼續(xù)保護行為不被后續(xù)改動破壞。# 運行 golden 測試輸出差異 ./new_billing --input ./golden/billing_case_001.json --expected ./golden/billing_case_001.out6.3 邊界用例優(yōu)先級不要只測正常路徑。下面這些邊界條件必須出現(xiàn)在驗證清單里空對象、空字符串、空列表數(shù)值邊界0、負數(shù)、最大值、最小值、超精度值重復請求、并發(fā)請求、超時請求異常輸入錯誤格式、未知枚舉、指數(shù)級數(shù)值排序與分頁多條數(shù)據(jù)處理時順序是否一致環(huán)境相關行為時區(qū)、字符編碼、換行符、浮點舍入。這些用例數(shù)量不需要特別多但覆蓋面要廣。每一條邊界用例一旦通過都要提交進代碼庫里成為長期回歸資產。7. 批量遷移與進度管理20 萬行代碼不可能一次遷移完必須設計成批量任務。這里的批量不是讓模型一口氣處理整個倉庫而是讓模型一個模塊一個模塊完成再由工程腳本統(tǒng)一管理。7.1 任務隊列用一個簡單的任務清單來管理模塊遷移進度import time tasks [ {module: billing, status: done, verified: True}, {module: account, status: in_progress, verified: False}, {module: ledger, status: todo, depends_on: [billing, account]}, ] for task in tasks: if task[status] done and task[verified]: continue print(fprocessing: {task[module]}) # 這里調用模型 API 的代碼由外部腳本負責 # 之后執(zhí)行編譯、單測、差分測試 # 全部通過后再更新任務狀態(tài) time.sleep(1)任務隊列里至少要有模塊名、依賴、狀態(tài)、驗證結果、負責人、備注這幾列。批量遷移過程中最怕“卡在某個模塊不動”所以每個模塊都設置超時時間和失敗重試次數(shù)。7.2 依賴順序決定批次先遷移最底層、最穩(wěn)定的模塊比如工具庫、數(shù)據(jù)訪問層、日期計算、金額計算。這些模塊行為明確、測試容易寫適合讓模型先練手。上層業(yè)務模塊依賴下層模塊的新接口遷移時就不需要同時理解新舊兩套系統(tǒng)的接口差異。7.3 調用模型 API 的工程化設計如果用云端 Claude / GPT API 做批量輔助生成要注意這些問題接口調用有頻率限制批量任務要設計請求隊列避免瞬時請求過多超時和失敗要自動重試重試之間加退避間隔每一次請求的 prompt 和返回結果要落盤存檔方便追溯消費成本按 token 統(tǒng)計每個模塊處理前估算一次上下文規(guī)模避免把整個倉庫反復塞進對話。這里沒有統(tǒng)一的標準參數(shù)實際限流值和計費規(guī)則要以你使用的服務商文檔為準。穩(wěn)妥的做法是把模型 API 調用封裝成獨立服務和遷移流水線解耦單獨配置限流和重試。8. 成本、節(jié)奏與資源觀察遷移工程同樣需要觀察“資源消耗”只是這里觀察的不是顯存和帶寬而是 token 成本、耗時、人工審查時間。8.1 關鍵指標指標觀察方式用途單模塊 token 消耗調用 API 時記錄 input/output token 數(shù)預判成本、優(yōu)化 prompt單模塊生成耗時開始調用到返回完整代碼的時間評估批量任務總時長驗證耗時編譯、單測、差分測試的執(zhí)行時間找驗證瓶頸人工審查耗時每個模塊 review 花費的時間判斷模塊拆分粒度是否合理驗證失敗率首輪生成通過率、修復輪數(shù)評估 prompt 質量和模塊復雜度這些指標不需要一開始就精確統(tǒng)計但要從第一個模塊就記錄。有了第一批數(shù)據(jù)就能估算后續(xù) 20 萬行代碼的遷移總量和成本。8.2 降低成本的技巧只遷移活躍代碼用覆蓋率工具找出從未被調用的死代碼先標記不遷移合并重復實現(xiàn)同一個邏輯在舊系統(tǒng)里出現(xiàn)多次遷移前先歸并壓縮給模型的上下文只保留模塊接口和關鍵實現(xiàn)不要貼整個調用鏈把常見的錯誤修復信息整理成規(guī)范文檔減少模型反復試錯。9. 常見問題與排查方法遷移過程中會遇到一批典型問題下面這張表可以當作排查入口問題現(xiàn)象可能原因排查方式解決方案模型生成的代碼編譯不過依賴缺失、版本不匹配、接口簽名不一致查看編譯器報錯檢查模塊依賴清單把編譯錯誤作為 prompt 內容回投給模型或人工補齊依賴聲明接口行為不一致沒有先建立行為基線對比新舊系統(tǒng)輸出補充 golden fixture建立差分測試后再讓模型改代碼中文亂碼或字符異常字符編碼不一致檢查文件編碼、數(shù)據(jù)庫連接編碼統(tǒng)一使用 UTF-8并在測試用例里加入中文輸入樣本排序結果不同依賴數(shù)據(jù)庫默認排序或集合無序性對比排序列和穩(wěn)定排序規(guī)則顯式指定排序字段刪除依賴默認排序的代碼浮點結果差一位浮點精度、編譯器優(yōu)化、運算順序不同輸出末尾幾位數(shù)值檢查運算順序使用近似斷言必要時統(tǒng)一計算精度規(guī)則上下文窗口溢出模塊拆分不夠細檢查每次 prompt 的 token 數(shù)繼續(xù)拆分模塊把公共依賴抽成獨立接口文檔批量任務卡住限流、網絡超時、進程殘留查看任務日志和 API 調用記錄增加重試機制和退避間隔任務狀態(tài)落盤以便斷點恢復模型“自由發(fā)揮”改了接口prompt 沒有強調接口約束對比輸出接口和既定接口定義在 prompt 里寫明“接口簽名不可改動”并增加簽名校驗腳本排查時始終記住一個原則先確認是哪一層出了問題。是生成代碼本身錯了還是 prompt 給的邊界不夠還是驗證腳本比較邏輯寫錯了。很多“模型寫錯”的問題最后發(fā)現(xiàn)是 prompt 沒有把行為基線描述清楚。10. 最佳實踐與合規(guī)建議把遷移工程跑完一輪之后總結出的最佳實踐是下面這些。第一先小后大。第一次遷移不要選 20 萬行里的核心交易模塊而是選一個邊角模塊把 prompt 模板、驗證腳本、任務管理流程全部跑通再擴大范圍。最小可運行配置一定要保留任何一次 prompt 調整都不能破壞已驗證的模塊。第二新舊系統(tǒng)并行。新模塊沒有通過差分驗證之前舊系統(tǒng)不要下線。切換用灰度方式先放流量到新系統(tǒng)對比線上日志和指標確認行為一致后再逐步切量。第三留全套行為日志。遷移期間所有模塊的輸入、輸出、驗證結果、人工決策都要有記錄。行為一致性不只是“這次跑贏了”還要能讓后續(xù)維護者在三個月后依然知道為什么保留了這個錯誤碼。第四合規(guī)審查前置。涉及未公開業(yè)務邏輯、用戶數(shù)據(jù)、核心密鑰的代碼不能直接丟給外部模型。先做脫敏再生成再人工審查敏感字段。模型生成的第三方依賴也要做許可證檢查避免引入和公司規(guī)范沖突的開源協(xié)議。第五建立行為契約文檔。每個模塊遷移完成后把它的行為約束整理成一份契約包含接口定義、邊界條件、錯誤碼、日志格式。后續(xù)如果還要繼續(xù)改技術棧這份契約可以直接給模型用。11. 總結與下一步回到開頭那個 20 萬行代碼遷移的命題真正的難點不是“讓 Claude / GPT 寫代碼”而是如何給模型一個可驗證的行為邊界。整倉重寫會懵是因為任務超出了單次生成能夠可靠控制的粒度模塊級遷移、行為基線先行、差分驗證兜底這套流程能讓模型在它擅長的代碼生成環(huán)節(jié)發(fā)揮作用同時把風險控制在可檢查的范圍內。如果你準備在自己的項目里啟動類似遷移第一步不是打開模型對話而是先盤點代碼、建立行為基線、搭好新舊兩套環(huán)境。第一個模塊跑通之后再讓 Claude / GPT 參與生成和修復。最容易踩的坑也明確不建基線就讓模型自由發(fā)揮結果只能是編譯通過但行為對不上。后續(xù)可以繼續(xù)擴展的方向包括把 prompt 模板和驗證腳本做成統(tǒng)一的半自動遷移流水線接入 CI 后每次提交都自動跑差分測試也可以用大模型輔助生成邊界測試用例反向補充基線的覆蓋缺口。遷移本身是一次性的但留下的行為基線和驗證資產會一直保護這套系統(tǒng)。