結論先說
- 老代碼重構的第一步不是改業務代碼,而是補特徵測試(Characterization Test)。特徵測試不評判舊邏輯「對不對」,而是忠實記錄當前代碼在各類輸入下的真實返回值、拋錯類型和副作用,為後續改動拉起安全網。
- 嚴格區分「補測試提交」與「純結構重構提交」。先在零業務改動的基線上讓特徵測試全部通過並提交到 Git,再要求 Codex 在不修改測試斷言的前提下分步抽離函數或模組。
- 盤點階段優先開只讀沙箱。用
codex --sandbox read-only讓模型先通讀調用鏈、全局變量與隱藏副作用,輸出依賴地圖後再進入編輯模式(權限邊界詳見 /guides/codex-permissions-sandbox)。 - 每次只做一種結構變換,小步提交配合
/review。把「提取純函數」「替換魔法值」「解耦外部接口調用」拆成獨立步驟,每步跑通測試再用本地審查確認未混入行為改動。 - 長上下文多輪重構消耗較高額度。若國內缺少外幣卡或現有檔位配額吃緊,可在本站自助選購 ChatGPT Plus 充值 或配額更高的 ChatGPT Pro 充值,團隊多人協作可了解 ChatGPT Business 團隊定製。

圖:本站根據 OpenAI Codex 官方文檔:Codex CLI 及工程實踐整理的示意圖
本文根據 OpenAI Codex 官方文檔《Codex CLI》《Command line options》《Custom instructions with AGENTS.md》及遺留代碼重構工程實踐整理,資料核對於 2026-11-19。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 OpenAI 官方網站。
適用於誰
- 接手缺少文檔與單元測試的祖傳模組,既要拆解千行大函數、又擔心破壞線上隱性分支的後端與前端開發者;
- 曾讓 Codex 一次性重構整個文件,結果出現邊緣場景迴歸、差異過大難以代碼審查的工程師;
- 希望建立可復現、可隨時回滾的 AI 輔助重構標準流程的研發團隊。
一、為什麼直接讓 Codex 重寫老代碼容易改壞線上
許多老舊核心文件(如訂單結算、權限判定、報表彙總)歷經多年熱修,表面充滿重複判斷和過深嵌套,但內部往往埋着兼容歷史數據的隱性分支——例如把 null 和空字符串視為不同含義、依賴特定字段的校驗順序、或順手修改了入參對象本身。
如果直接對 Codex 說「幫我把 orderService.ts 重構得更簡潔」,模型通常會出於代碼審美做出三類危險操作:一是合併它認為多餘的條件判斷,悄悄改變了極端輸入的返回結果;二是順手升級接口簽名或重命名導出符號,導致未在上下文裏的外部調用方報錯;三是一次生成數百行差異,代碼審查者根本無法逐行核驗等價性。
因此,安全使用 Codex 重構老代碼的核心思路,是把「探索與鎖定現狀」和「調整代碼結構」徹底拆開。

圖:本站結合工程維護經驗整理的對比示意圖
二、階段一:只讀盤點依賴並補齊特徵測試
在動任何一行生產代碼之前,先保證 Git 工作區乾淨,並新建獨立分支。如果不熟悉整個倉庫結構,可先參考 /guides/codex-onboard-unfamiliar-project-agents-md 完成項目規則摸底。
1. 用只讀模式繪製行為與副作用清單
在項目根目錄啟動只讀會話(避免模型順手改動文件):
bash
codex --sandbox read-only
在會話中發送第一段提示詞,鎖定被重構模組的外部邊界:
text
請只讀取 src/billing/calcDiscount.ts 及其直接調用方,不要修改任何文件。
請整理一份行為與副作用清單,包含:
1. 所有外部調用入口和參數類型(含可空、缺省與異常入參);
2. 函數內部的全部條件分支、邊界閾值與拋錯條件;
3. 是否讀寫全局變量、環境變量、系統時間、數據庫或修改入參對象本身。
2. 讓 Codex 生成特徵測試並鎖定當前行為
拿到清單後,回到常規工作區模式(建議保留審批確認),按「只新增測試文件、不碰生產源碼」的原則補齊特徵測試。更多測試生成細節也可參考 /guides/codex-write-tests-and-run。
text
請為 src/billing/calcDiscount.ts 編寫特徵測試(tests/billing/calcDiscount.char.test.ts)。
硬性要求:
1. 禁止修改 src/ 下的任何生產代碼,即使發現疑似歷史缺陷也先按當前真實輸出斷言,並在註釋中標註「疑似歷史行為待確認」;
2. 覆蓋正常路徑、空值與零值邊界、疊加折扣優先級、異常拋錯類型及入參是否被原地修改;
3. 如果依賴系統時間或外部客戶端,僅對外部 I/O 邊界做最小隔離;
4. 編寫完成後運行測試命令,確認所有用例在未改動源碼時 100% 通過。
核對要點:人工逐條檢查測試斷言,確認用例真正觸發了源碼中的複雜分支,而不是簡單模擬返回值。確認全部綠燈後,立即執行一次獨立提交,例如 test(billing): add characterization tests for calcDiscount。
訂閱與帳號準備提示:對千行老代碼做依賴分析、補測與多輪重構會持續讀取多文件上下文,容易觸發額度上限(計算規則見 /guides/codex-usage-limits)。重度開發建議升級 ChatGPT Pro 5x iOS 可覆蓋檔 或 ChatGPT Pro 5x 信用卡不可覆蓋檔;新註冊帳號若在手機號環節遇到阻礙,可參考 Codex 註冊手機驗證服務。
三、階段二:單步結構抽離與檢查點驗證
特徵測試提交入庫後,每一輪重構都遵循「單目標 → 跑測試 → 看差異 → 小步提交」的固定閉環。本站建議單次重構提交的有效業務變更控制在 150 行以內,方便逐行核對。
推薦的拆解順序(由安全到複雜)
- 隔離外部依賴(引入接縫):先把時間獲取、配置讀取、日誌寫入等隱式依賴改成可選參數注入,保持舊簽名兼容。
- 提取無副作用純函數:把深層嵌套的折扣計算、金額舍入、狀態映射抽成獨立純函數,主流程只留清晰編排。
- 收斂重複判斷與魔法數字:替換為語義化常量和衛語句(Early Return),降低圈複雜度。
- 驗證並清理:確認所有特徵測試及原有集成測試綠燈後,再單獨開一次任務討論是否修復之前標註的「疑似歷史缺陷」。
單步重構提示詞模板
text
基於已通過的特徵測試 tests/billing/calcDiscount.char.test.ts,對 src/billing/calcDiscount.ts 執行第一步重構:
目標僅限:將「會員等級折算」和「滿減階梯計算」提取為同文件內的兩個純函數。
嚴格約束:
1. 禁止修改任何已有測試文件與測試斷言;
2. 禁止改變導出函數簽名、返回字段名與異常類型;
3. 不要順手重構文件其餘部分或修改無關文件;
4. 修改完成後自動運行全部相關測試並展示 git diff --stat。
每次測試通過後,在 Codex CLI 中運行 /review 做一次自動代碼覆核(用法詳見 /guides/codex-code-review),確認沒有夾帶邏輯語義變化再執行 git commit。若某一步把測試改紅且定位困難,直接 git checkout -- . 回到上一個乾淨提交,比在改亂的現場繼續讓 AI 補救省時得多。
常見問題
問:老代碼本身確實有 Bug,特徵測試階段要不要順手一起修了?
答:不建議在結構重構中夾帶 Bug 修復。特徵測試階段應忠實鎖定線上現行行為,把可疑點記錄成註釋或工單;等結構拆清、所有測試穩定通過後,再另開獨立提交專門修 Bug 並更新對應預期斷言,這樣上線後若出現問題能立刻區分是重構引入還是業務改動導致。
問:如果老代碼強依賴全局單例或靜態數據庫連接,特徵測試跑不起來怎麼辦?
答:先做最小「接縫改造」(如在文件末尾增加可選依賴注入參數,預設仍指向原有單例),保證老調用方零修改即可編譯運行,再用測試傳入輕量內存替身跑通特徵測試,之後再逐步抽離核心邏輯。
問:國內沒有外幣信用卡,或者公司研發團隊需要開票報銷,怎麼開通高配額 ChatGPT / Codex 訂閱?
答:可通過本站 AI 會員充值總覽 按需選擇 ChatGPT Plus、ChatGPT Plus 自助卡密 或更高額度的 ChatGPT Pro,支持支付寶、微信支付與 AlipayHK,採用卡密自助兌換(無需提供帳號密碼)或客服協助,支持開具增值稅發票;多人團隊可直接在站內諮詢 Business 團隊定製方案。實時價格以頁面顯示為準,售後遵循掉訂閱按剩餘天數折退、封號不在質保範圍的規則。
相關教學
- 用 Codex 寫測試並跑通:指定函數、覆蓋正常和邊界並報告結果
- 用 Codex 接手陌生項目:先解釋代碼再用 /init 起草 AGENTS.md
- Codex 代碼審查(codex review)怎麼用
- Codex 權限與沙箱設定:審批模式怎麼選與安全邊界
參考資料
- OpenAI Codex 官方文檔:Codex CLI — https://learn.chatgpt.com/docs/codex/cli
- OpenAI Codex 官方文檔:Command line options — https://learn.chatgpt.com/docs/developer-commands
- OpenAI Codex 官方文檔:Custom instructions with AGENTS.md — https://learn.chatgpt.com/docs/agent-configuration/agents-md
- OpenAI Codex 官方文檔:Non-interactive mode — https://learn.chatgpt.com/docs/non-interactive-mode
0 條評論
還沒有評論,來搶沙發~