场景：来了个没人要的老项目，文档为零
公司裁员，一个烂摊子辗转几手到了你手里：大型 C++ 老项目，交接的人都走了，文档为零，只有一个 git 仓库。按以前的经验，光把代码读明白、把编译跑通，怎么也得两三周。
这次我把整个仓库丢给 Codex（Windows 桌面端），没上任何 skill，纯靠把任务拆清楚 + 几段下得准的指令，几天就跑通了。下面把流程拆开讲，指令附上可以直接抄。
为什么"接手老项目"最适合交给 Agent？
接手的本质是两件事：理解结构 + 整理输出。读代码、画依赖、补文档、配环境——这正是大模型最擅长、人也最烦的活。大模型不怕枯燥，几千行代码扫一遍比人眼看快，还不喊累。
更关键的是，这一步是低风险的：它写错一份架构图，你扫一眼就知道；它配错环境，跑不起来马上发现。试错成本极低，放心交给它。
⚠️ 但记住一个边界：任何会"写进生产、改业务逻辑"的动作，先按住。读懂归读懂，动手是另一回事。
第一步：先"只读分析"，不动代码
第一件事不是让它改任何东西，而是输出一份架构说明，让你建立全局认知。
直接抄这段指令：
只阅读、不要改任何文件。输出 ARCHITECTURE.md，用 mermaid 画模块依赖图，
并列出 3 个最可能影响上线稳定性的风险点。
你会得到：项目由哪几块组成、谁调谁、数据从哪进从哪出，外加它标记的隐患。
防它胡编的小技巧
拿到架构图后，挑一两个它说的"模块依赖"去代码里抽样核对。比如它说"A 调 B"，就去搜一下 A 里有没有真的引用 B。这类老项目 agent 偶尔会把目录名当成调用关系，抽样两处就能发现，比全信更靠谱。
一段常见的 mermaid 骨架长这样（你对照自己的项目改）：
graph TD
A[API 网关] --> B[订单服务]
B --> C[消息发送模块]
C --> D[(消息表)]
D --> E[消费者: 实际投递]
B --> F[(订单库)]
第二步：补 onboarding 文档
没有文档，最大的痛是"本地根本跑不起来"。让 Codex 把启动链路一次性列清。
直接抄这段指令：
写一份 ONBOARDING.md：列出启动所需的环境变量、依赖安装命令、
本地起服务的步骤、以及你预期会踩的坑。
这一步直接省掉"问前同事（已离职）+ 猜配置"的半天。
💡 跑一遍它给的步骤，凡是它写"应该就行"的地方，都自己实际敲一遍命令——它能列全，但版本号、端口冲突这类细节经常会过时。
第三步：编译跑通，但严格限制改动范围
让它能 build，但每条改动都要解释，区分"改了依赖/配置"和"改了业务代码"。
直接抄这段指令：
只做让项目能编译通过的最小改动。
改完给出清单：每条改动的文件、原因、属于依赖/配置还是业务逻辑。
三个高频坑，review 时直接照着查：
| 坑 | 现象 | 防法 |
|---|---|---|
| 顺手升级依赖大版本 | 为消弃用警告，把 v2 升到 v3，引入 breaking change | 能用小版本修就别动大版本 |
| 只验证了能 build，没真正起服务 | 编译过 ≠ 能跑，漏了"需要连外部服务 / 某个环境变量" | 按 ONBOARDING 真正起一次服务 |
| 为了跑通测试改测试本身 | 删失败用例、改断言、把警告不当错误，测试变绿但问题没解决 | 看到测试文件被改要格外警惕 |
第四步：分模块问，别一次甩全库
项目大，一次问全库它容易胡编。缩小范围，命中率高得多。
先只讲消息发送这条链路，从触发到落库经过哪些模块、各自负责什么。
一条链路问透，比"整个项目讲讲"得到的东西扎实。建议按"用户请求 → 业务处理 → 落库 → 异步/对外"这样切，一次问一段。
一个少返工的小习惯：约定文件
在仓库根目录放一份 AGENTS.md（Codex / Claude Code 都认这类 instructions），写明：
# AGENTS.md
## 禁止事项
- 禁止改代码风格
- 禁止升级大版本依赖（除非明确说明）
- 禁止直接 git push
- 改动前先给清单，等我确认
## 工作原则
- 每次改动解释原因
- 先建分支，在独立分支上操作
- 改完先 git commit，让我 review diff 后再继续
每次新会话 Codex 会先读这个文件，省得每轮重复叮嘱。
真实耗时对比
预估两三周 → 实际几天跑通、能本地起服务。省下的不是一两小时，是一段本该用来"搞清楚这项目到底是啥"的耐心。
它能做 vs 别让它碰
| ✅ 放心交给它 | ❌ 别让它碰 |
|---|---|
| 读代码、画架构 | 改有状态的业务逻辑 |
| 补 onboarding 文档 | 操作生产数据库 |
| 配环境、跑编译 | 直接 git push 到主分支 |
| 列改动清单供人审核 | 自动接受所有 diff |
读懂之后那一步（改 bug、动业务），agent 就不再那么可信了——那篇讲一次因轻信它的修复导致的生产事故。
来源：尘光（夜雨聆风公众号）《我是怎么用 Codex 接手一个零文档老项目的(附可直接抄的agent指令)》，原文 2026-08-25 发布，经本教程改写与结构化。
资料最后核对日期：2026-09-02 · 内容整理自 CodexGuide 社区公开教程