📘 OpenAI Codex📚 官方教程中文版实战场景
让 Codex 快速读懂大型代码库
进入陌生 repo 或陌生功能区时，先让 Codex 帮你建立可编辑的地图，而不是只要一段高层总结。目标是弄清 request flow、模块职责、数据验证位置
进入陌生 repo 或陌生功能区时，先让 Codex 帮你建立可编辑的地图，而不是只要一段高层总结。目标是弄清 request flow、模块职责、数据验证位置、容易踩坑的依赖，以及下一步应该读哪些文件。
官方页面：https://developers.openai.com/codex/use-cases/codebase-onboarding
适合什么任务
| 场景 | 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
起始提示词
请解释 request 是如何流经 codebase 中 <name of the system area> 的。
请包含：
- 哪些 modules 分别负责什么
- 数据在哪里被 validated
- 修改前最需要注意的 gotchas
最后列出我接下来应该阅读的 files。如果你刚进入一个项目，可以先问整体结构；但如果你要改某个功能，最好直接限定 system area。scope 越具体，Codex 给出的解释越能指导真实改动。
操作步骤
- 给 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。