让 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。

起始提示词

请解释 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 从阅读直接跳到大范围重构。生产代码库里，理解任务和实现任务应该分开。