交流群即将上线
案例 02 · 摸清一个陌生代码库
什么场景
接手一个别人写的项目，或者被派去修一个你从没碰过的模块。 以前的做法是花两天读代码 + 问人；现在可以先让它替你跑一遍， 把「这个仓库长什么样」变成一份能核对的笔记。
在什么权限下跑
只读，而且要显式指定。
bash
cd ~/some-unfamiliar-repo
codex --sandbox read-only理由有两个：
- 你还不知道这个仓库里哪些脚本有副作用。
npm run setup可能会往你的数据库里灌数据。 - 探索阶段本来就不该产生改动。一旦它改了东西，你就分不清「这行本来就这样」和「它改成这样」。
另外，Codex 启动时会检测目录是否纳入版本控制： 已纳入版本控制建议 Auto，未纳入建议 read-only。 clone 下来的仓库当然有 Git，所以它默认会建议 Auto——这里我们主动往回收一格。
第一轮：让它给你一张地图
text
我第一次接触这个仓库。请只读地探索，不要改任何文件。
给我：
1. 这个项目是干什么的，用一段话说清楚
2. 入口在哪：可执行文件 / 服务启动点 / 主要的 CLI 命令
3. 目录职责表：每个顶层目录一行，说明它放什么
4. 数据从哪进来、到哪去（外部依赖、数据库、消息队列、第三方 API）
5. 怎么跑测试，怎么本地起服务
6. 你觉得最容易出问题的三个地方，以及为什么
每条结论都带上文件路径。不确定的地方明确说"没找到"，不要猜。最后那句「不确定就说没找到」值得每次都加。 没有它，模型倾向于给一个听起来合理的答案，而你没法一眼分辨。
第二轮：并行拆开细看
地图有了之后，具体问题就适合并行。这正是子智能体 最擅长的场景——以读为主、彼此独立、只要结论：
text
用并行子智能体深入这三条线，每条一个智能体，跑完汇总：
1. 认证与鉴权：请求从入口到拿到用户身份，完整走一遍，列出每一层做了什么
2. 数据库访问：用了什么 ORM/驱动，事务边界在哪，有没有裸 SQL
3. 测试：测试怎么组织的，哪些模块覆盖得好，哪些几乎没有
每个智能体只返回结论和文件引用，不要贴大段代码。主线程拿到的是三份提炼过的笔记，而不是三轮翻文件的原始输出。 这样第三轮提问时，上下文还是干净的。
并行是要花钱的
每个子智能体独立用模型和工具，比同等的单智能体运行更费 Token。 探索一个大仓库时这笔开销通常值，但先用 agents.max_concurrent_threads_per_session 把并发框住，别让一句「并行处理」开出十几个线程。
第三轮：带着具体问题问
地图和线索都有了，现在问真正要解决的问题：
text
我要在 services/billing 里加一个"订单退款后自动作废关联发票"的逻辑。
先不要写代码。告诉我：
1. 现有的退款流程走哪几个文件，从哪个函数进入
2. 发票是在哪里创建的，有没有现成的作废接口
3. 这两条流程之间现在有没有耦合
4. 如果要加这个逻辑，你会改哪几个文件，为什么是这几个
5. 有什么是我应该先问原作者、代码里看不出来的第 5 点经常能问出最有价值的东西——比如「这段代码有个 TODO: 等 X 上线后删掉， 但没说 X 是什么」，这就是你该去问人的地方。
把结论存下来
探索完别让结果留在会话里。至少做一件事：把它写成仓库里的 AGENTS.md。
text
根据刚才的探索，帮我起草一份 AGENTS.md，放在仓库根目录。
包括：怎么跑测试、怎么起本地服务、目录职责、以及三条最容易踩的坑。
简洁一点，控制在 60 行以内。不要写架构介绍，代码能看出来的不用写。这样下一次（不管是你还是同事）打开这个仓库，Codex 一进来就知道该怎么干活。 详见 快速上手 05。
容易翻车的地方
一上来就问「帮我改 X」。 它会边猜边改，你得到一堆看起来对但没走通的代码。 先探索，再动手，这两步分开。
探索完直接进入开发，不换会话。 探索会在上下文里堆很多文件内容。 拿到结论之后开新会话，把结论作为输入，比继续在旧会话里干活清爽得多。
信它列的目录职责表却不抽查。 挑两个目录自己打开看一眼，五分钟的事。 对上了你就能放心用剩下的结论。