交流群即將上線
案例 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」。 它會邊猜邊改，你得到一堆看起來對但沒走通的程式碼。 先探索，再動手，這兩步分開。
探索完直接進入開發，不換工作階段。 探索會在上下文裡堆很多檔案內容。 拿到結論之後開新工作階段，把結論作為輸入，比繼續在舊工作階段裡幹活清爽得多。
信它列的目錄職責表卻不抽查。 挑兩個目錄自己開啟看一眼，五分鐘的事。 對上了你就能放心用剩下的結論。