讓 Codex 快速讀懂大型程式碼庫

進入陌生 repo 或陌生功能區時，先讓 Codex 幫你建立可編輯的地圖，而不是隻要一段高層總結。目標是弄清 request flow、模組職責、資料驗證位置、容易踩坑的依賴，以及下一步應該讀哪些檔案。

官方頁面：https://developers.openai.com/codex/use-cases/codebase-onboarding

Understand large codebases

讓 Codex trace request flow，而不是隻寫概覽。

Codex app

在本地專案中用 Codex 讀程式碼、執行檢查和迭代任務。

Best practices

用小範圍任務、驗證和 checkpoint 控制真實程式碼庫風險。

適合什麼任務

場景	Codex 應該做什麼
新工程師進入新 repo 或新 service	解釋系統結構、模組職責和下一步閱讀路徑
修改已有功能前需要理解 flow	trace request flow，標出 business logic、transport、persistence 或 UI 所屬模組
不確定改動風險在哪	找出 validation、side effects、state transitions 和容易漏掉的相關檔案

推薦模型和強度：gpt-5.3-codex-spark，medium effort。

相關官方說明：

Codex app：https://developers.openai.com/codex/app
Codex best practices：https://developers.openai.com/codex/learn/best-practices

起始提示詞

请解释 request 是如何流经 codebase 中 <name of the system area> 的。

请包含：
- 哪些 modules 分别负责什么
- 数据在哪里被 validated
- 修改前最需要注意的 gotchas

最后列出我接下来应该阅读的 files。

如果你剛進入一個專案，可以先問整體結構；但如果你要改某個功能，最好直接限定 system area。scope 越具體，Codex 給出的解釋越能指導真實改動。

輸出格式

要求 Codex 產出一份可編輯地圖，而不是一次性講解：

请按这个结构回答：

1. Entry points
2. Request / event flow
3. Main modules and ownership
4. Validation and authorization
5. Persistence and side effects
6. Risky spots before editing
7. Files to read next
8. Checks to run after editing

這個格式能把“讀懂程式碼庫”轉成後續改動可用的材料。尤其是 validation、side effects 和 checks 三項，能直接決定改動是否安全。

操作步驟

給 Codex relevant files、directories 或 feature area。
要求它 trace request flow。
讓它說明哪些模組負責 business logic、transport、persistence 或 UI。
在編輯前問清 validation、side effects 和 state transitions。
最後要求它列出 next files to read 和 risky spots。

一個有用的 onboarding answer 不應該只是檔名清單。它應該解釋主流程、指出風險點，並告訴你修改前後需要看哪些檔案和檢查項。

後續問題

第一輪解釋後，繼續追問，直到你有信心做第一處改動：

哪個 module 負責真正的 business logic？哪些部分屬於 transport 或 UI layer？
validation 發生在哪裡？那裡強制了哪些 assumptions？
如果修改這個 flow，哪些 related files 或 background jobs 容易漏掉？
編輯這個區域後，我應該執行哪些 tests 或 checks？

驗收重點

Codex 的解釋至少要回答：

request 從哪裡進入，經過哪些層。
關鍵資料在哪裡被驗證。
核心業務邏輯屬於哪個模組。
哪些副作用、background jobs 或快取會受影響。
修改後應該跑哪些 tests 或 checks。
下一步值得人工閱讀的檔案是什麼。

如果回答裡只有“這是一個 React app / FastAPI service / monorepo”，說明還停留在摘要層，需要繼續追問 flow 和 ownership。

不要這樣問

帮我读懂这个项目。

這種問題太寬，容易得到一頁架構概覽。更好的寫法是：

请解释 checkout discount 是如何在这个 repo 中生效的。

请 trace：
- 前端入口
- API handler
- validation
- pricing / discount business logic
- database read/write
- cache or background job
- tests

最后告诉我如果要改 discount stacking rule，最小改动可能在哪里。

用 feature、flow 或業務物件切入，比按資料夾泛讀更快。大型程式碼庫的閱讀目標不是“知道所有檔案”，而是知道當前改動會穿過哪些邊界。

改動前二次確認

在真正編輯前，讓 Codex 再回答三件事：

這次改動的最小檔案集合是什麼。
哪些檔案是相關但不該碰的邊界。
哪個測試或手動流程能證明改動沒有破壞主路徑。

這一步能防止 Codex 從閱讀直接跳到大範圍重構。生產程式碼庫裡，理解任務和實現任務應該分開。