Appearance
用 Codex 读懂陌生代码库
嗨，朋友！你有没有接过一个项目，打开一看几十个目录几百个文件，脑子直接嗡嗡的？我刚入职那会儿就是这么过来的，对着屏幕发呆了整整一个上午，最后憋出来一句"这项目…挺大的哈"。后来踩的坑多了，我发现一个特别管用的办法：别让 AI 给你讲整个仓库，而是让它追着一条真实业务线跑一遍。
这篇文章跟你聊聊我是怎么用 Codex 啃下一个陌生代码库的，全程可操作，每条结论你都能自己打开文件核对。
本章交付物
走完这套流程，你应该拿到一份实打实的项目地图，里面至少有这些内容：
- 项目干什么用、主要跑哪些单元；
- 启动、测试、构建和部署的入口在哪；
- 挑一条真实请求或用户操作，从头到尾走通；
- 关键数据结构长什么样、在哪儿读写的；
- 配置、外部服务和环境变量的边界；
- 改这条链路时最容易翻车的地方；
- 哪些是已确认的、哪些是推断的、哪些还没验证，清楚标出来。
第一步：建立仓库基线
进项目第一件事，别急着问 AI "这个项目是干啥的"——相信我，我干过，它回了我一堆 Spring Boot 的通用介绍，屁用没有。先自己摸一圈 git 状态：
bash
cd /path/to/project
git status --short --branch
git log -5 --oneline心里有个大概之后，用只读模式启动 Codex：
bash
codex --sandbox read-only -C /path/to/project第一轮提示我建议你这样写，别问业务，先要地图：
text
只读盘点当前仓库，不修改文件、不安装依赖。
请找出：
1. 仓库包含哪些可独立运行的应用或包；
2. 每个应用的入口、启动、测试和构建命令；
3. 主要配置文件、数据存储和外部服务；
4. 哪些目录是生成物、第三方代码或不应直接修改的内容；
5. 结论对应的文件路径。
把明确事实、合理推断和未验证项分开。这一步做完，你手里就有了一张"仓库户口本"，至少知道谁是谁、住哪儿。
第二步：只追一条真实链路
地图有了，接下来挑一条具体的业务线往下追。我习惯选那种一眼就能描述清楚的动作，比如：
- 用户提交登录表单；
- API 请求
/orders/{id}； - 定时任务结算账单；
- 点击"保存"后数据落库；
- 消费一条消息并更新状态。
选好之后丢给 Codex：
text
追踪"[用户动作或请求]"的真实执行链路。
从入口开始，按执行顺序列出：
- 路由或事件入口；
- 参数解析与校验；
- 业务服务；
- 数据查询/写入；
- 外部调用；
- 响应或状态变化；
- 错误处理和日志。
每一步给出文件路径、函数/类名和关键数据形状。找不到时停在已确认位置，不要按框架习惯补全。有个关键点：最后那句"找不到时停在已确认位置"特别重要。我有次追一条支付回调链路，Codex 在中间凭空"脑补"了一个订单状态机，看着特别合理，结果代码里根本没有，是它按电商框架惯例编的。所以一定让它卡住就承认卡住，别帮你"圆"。
第三步：让代码地图接受反向验证
正向追完链路还不够，我踩过一个坑：顺着路由一路往下看，自以为全搞懂了，结果上线后发现还有一个定时任务也在写同一张表，数据老是被莫名覆盖。
所以追完链路后，我会对 Codex 连问三个问题：
text
这条链路里，哪个结论最可能因为动态路由、依赖注入或配置覆盖而判断错误？请重新检查证据。text
从最终数据库写入或响应构造位置反向追踪到入口，看看是否存在另一条分支。text
搜索同一字段名、路由名和事件名的所有引用，区分生产代码、测试、迁移和废弃实现。正向阅读就像沿着主干道走，旁边的岔路、后门你根本看不见。反向追踪和全局搜索能帮你揪出第二个入口、遗留的老实现、还有藏在角落里的异步分支。这一步别省，省了后面 debug 的时候加倍还回来。
第四步：运行最小验证
光看代码不跑，就像看菜谱不下厨——你以为会了，一上手就翻车。如果项目能启动，让 Codex 先解释命令从哪个配置文件来的，再在可写权限下跑最小验证：
text
先说明你建议的启动或测试命令来自哪个配置文件。然后只运行与这条请求链路直接相关的最小测试，不修改文件。报告命令、退出码和关键输出。有些项目就是跑不起来——缺依赖、缺环境变量、某个服务挂了、平台不对付，或者命令本身就是错的。这种情况也别慌，至少让 Codex 告诉你具体卡在哪了，把问题暴露出来比假装能跑强一百倍。
第五步：输出一份可交接的地图
前面几步走完，信息已经攒够了。最后让 Codex 按一个固定的结构帮你整理，别追求文采，清晰就行：
text
请生成项目链路交接说明：
1. 一句话用途
2. 运行单元与入口表
3. [目标行为] 的编号调用链
4. 关键数据结构与生命周期
5. 配置和外部依赖
6. 最小验证命令
7. 修改风险清单
8. 未验证项
9. 关键文件索引这份地图的质量标准很简单：你随便挑索引里的一个文件打开，能说清楚它为什么出现在这里，就算合格。
多仓库项目怎么处理
碰到微服务那种好几个仓库的项目，千万别让 Codex 一口气扫完所有代码然后猜关系——会猜得特别离谱。我吃过这个亏，它把 A 服务调 B 服务的接口都编出来了，结果两个服务之间走的是消息队列，根本没有 HTTP 调用。
老老实实逐个仓库来：
- 请求最先到哪个仓库；
- 通过 HTTP、消息、数据库还是文件跨仓库；
- 每个边界的真实 URL、Topic、表或配置字段；
- 哪个仓库负责鉴权、计费和最终响应；
- 本地分支与线上部署版本是否一致。
每跨一个仓库，都建立一个能搜得到的"连接点"——环境变量名、路由前缀、Header 或者消息 Topic，之后回头查的时候一搜就定位到。
常见失败模式
只生成目录树
目录树告诉你文件怎么摆的，但运行时行为它一个字都说不出来。解法简单：要求追一个具体请求或事件。
把测试实现当生产实现
测试里的 mock 和 fixture 跟生产逻辑经常是两码事。让 Codex 给每个引用标明来源类型，优先验证生产的入口代码。
忽略配置覆盖
同一个字段，可能被环境变量盖一层、项目配置盖一层、用户配置再盖一层、部署平台再来一层。要求 Codex 列出优先级和你当前环境的实际取值来源，当然敏感值别让它打印出来。
看到接口就假设前端在用
定义了一个 API 不代表有人调它。让 Codex 搜真实的调用方、网络请求封装和路由匹配。找不到调用证据就老老实实写"未确认"，别硬凑。
完成门槛
- [ ] 至少追踪一条端到端链路。
- [ ] 每个关键结论都能定位到文件或运行结果。
- [ ] 区分了同步、异步和替代分支。
- [ ] 找到了最小验证命令。
- [ ] 列出了未验证信息，而不是补全猜测。
下一步
调用链搞熟了，去看看怎么 复现并修复 Bug，把那套踩坑经验也分享给你。