适合刚接手遗留项目、跨模块需求，或面对“能运行但没人说得清”的业务代码。核心结论：不要先让 Codex 改代码，先让它交付一张能核对的请求链路图。
为什么“解释这个仓库”通常不够
一句“解释这个仓库”很容易得到目录树、框架名称和几个核心文件。这些信息适合快速浏览，却不足以支撑一次安全修改。真正决定改动风险的，通常是一个请求从哪里进入、在哪一层做校验、谁写数据库、谁触发异步任务，以及失败后如何回滚。
OpenAI 的官方 Codex 用例也把重点放在“编辑之前”：先追踪请求流，区分业务逻辑、传输、持久化与 UI 的职责，再找出校验、副作用和状态转换。换句话说，代码库导读的产物不应是文件清单，而应是一张带证据的系统地图。
第一步：先限定一条业务链路
不要一次分析整个大型仓库。选择一个真实动作，例如“用户提交订单”“审批人确认合同”或“定时任务同步库存”，并明确这次只读分析，不修改文件。
可以直接使用下面的提示词：
``text 只读分析“用户提交订单”这条链路，暂时不要修改代码。 请从页面或 API 入口开始，追踪到业务服务、数据访问、数据库写入和异步副作用。 对每一跳给出文件路径、关键函数以及判断依据。 最后列出仍未确认的假设、风险点和下一批应阅读的文件。 ``
“只读”“具体业务动作”“证据位置”是三个关键约束。它们能避免任务过早滑向实现，也让你可以逐项复核结果。
第二步：要求四层证据，而不是只要结论
一份可用的链路图至少要覆盖四层。
- 入口层：页面事件、路由、控制器或消息消费者在哪里接收输入。
- 业务层：权限、业务条件、金额计算和状态转换由谁负责。
- 持久化层：查询与写入涉及哪些表、事务边界和并发条件。
- 副作用层：是否发送消息、生成文件、调用外部接口或启动工作流。
让 Codex 为每个判断附上文件路径和函数名，并把“代码明确证明”与“根据命名推测”分开。如果某个状态码只有数字、某个 SQL 由字符串动态拼接，或者调用发生在反射框架中，应明确标为待确认，而不是补全一个听起来合理的故事。
第三步：画出职责矩阵
链路追完后，再要求一张简短的职责矩阵：谁负责输入校验，谁负责业务规则，谁真正落库，谁对外部副作用负责。这样能及时发现常见误区，例如页面禁用了按钮，但服务端仍允许重复提交；控制器看似完成审批，真正的状态变更却在工作流回调里；列表页显示的是汇总值，保存接口写回的却是明细表。
对于多仓库或多模块项目，还要先确认版本库边界。构建命令、变更范围和提交位置都应落在实际模块中，不能把聚合工作区误当成单一仓库。
第四步：用反向问题找隐藏路径
正向链路只能说明“通常怎样成功”。在开始编辑前，至少再问四类反向问题：
- 校验失败时，响应从哪一层返回？
- 数据库写入成功、外部调用失败时，会不会出现半完成状态？
- 同一请求重复到达时，靠唯一约束、状态判断还是锁来防重？
- 是否存在定时任务、后台回调或另一个页面也能改变同一状态？
这一步经常能找到主流程之外真正危险的入口。若答案仍依赖猜测，可以让 Codex 继续搜索状态码、表名、事件名称和调用方，直到每个高风险结论都有代码证据。
第五步：把地图转换成最小改动方案
完成导读后，再开启新的实现阶段。让 Codex 先复述成功标准和改动边界，然后说明计划修改哪些文件、为什么不需要改其他层、准备运行哪些检查。推荐的顺序是：
- 记录当前行为和可复现步骤；
- 选择真正拥有该规则的层；
- 做最小范围修改；
- 运行针对性测试、静态检查或构建；
- 检查 diff，确认没有顺手重构无关代码；
- 明确哪些结论只经过静态验证，哪些已经过运行时回归。
如果链路图显示页面和服务端各有职责，不要用一处改动代替另一处。界面限制改善用户体验，服务端约束负责数据正确性，两者的证据和验收方式不同。
一份可复用的验收清单
在允许 Codex 动手前，用下面六项检查导读结果：
- 是否从真实入口追踪到最终写入或外部副作用；
- 是否区分 UI、传输、业务、持久化职责；
- 是否标出校验、事务、状态转换和重复请求；
- 每个关键结论是否有文件与函数依据；
- 是否列出未确认假设，而非把推测写成事实；
- 是否给出下一步最小修改范围和验证方法。
当这六项齐全时，Codex 才真正从“会搜索文件”变成了可协作的代码库向导。先建立地图看似多花几分钟，实际能减少改错层、漏副作用和无效回归的成本，尤其适合业务规则分散、模块边界复杂的遗留系统。