我是怎么用 Codex 接手一个零文档老项目的(附可直接抄的agent指令)

大家好，我是尘光

关注我，每天一篇AI硬核解读，不吹水不画饼。

2026.08.25 阅读约 5 分钟

上个月，公司裁员，一个不挣钱、没人愿意要的烂摊子，辗转几手最后到了我手里，大型C++老项目，交接的人都走了，文档为零，只有一个git仓库。按以前的经验，光把代码读明白、把编译跑通，怎么也得两三周。

这次我直接把整个仓库丢给Codex（Windows 桌面端），没上什么 skill，纯靠把任务拆清楚 + 几段下得准的指令，几天就跑通了。这篇把流程拆开讲，指令附上可以直接抄。

为什么"接手老项目"最适合交给 agent

接手的本质是什么？我个人认为就是"理解结构 + 整理输出"：读代码、画依赖、补文档、配环境。这恰恰是大模型最擅长、人也最烦的活——大模型最不怕的就是枯燥，几千行代码扫一遍，比人眼看快多了，也不会喊累，眼睛疼，还能按你要的格式吐出来。

但更关键的是，这一步是低风险的。它写错一份架构图，你扫一眼就知道；它配错环境，跑不起来你马上就能发现。试错成本极低，所以放心交给它。

反过来说，有些活千万别在这一步让它碰：任何会"写进生产、改了业务逻辑"的动作，都先按住。读懂归读懂，动手是另一回事——下篇我会讲清楚为什么，这里先记住边界！！

我的四步工作流

1. 先"只读分析"，不动代码

第一件事不是让它改任何东西，而是输出一份架构说明，让你能先建立全局认知。

指令：「只阅读、不要改任何文件。输出 ARCHITECTURE.md，用 mermaid 画模块依赖图，并列出 3 个最可能影响上线稳定性的风险点。」

你会得到：项目由哪几块组成、谁调谁、数据从哪进从哪出，外加它标记的隐患。我一般花十分钟扫一遍，比自己读三天强，到此任谁都得感叹一句，有大模型真好。

这里有个防它胡编的小技巧：拿到架构图后，挑一两个它说的"模块依赖"去代码里抽样核对。比如它说"A 调 B"，你就搜一下 A 里有没有真的引用 B。这类老项目 agent 偶尔会把目录名当成调用关系，抽样两处就能发现，比全信更靠谱。

一段它常能给出的 mermaid 骨架长这样（你对着自己的项目改）：

graph TD  A[API 网关] --> B[订单服务]  B --> C[消息发送模块]  C --> D[(消息表)]  D --> E[消费者: 实际投递]  B --> F[(订单库)]

2. 补 onboarding 文档

没有文档，最大的痛就是"本地根本跑不起来"。让它把启动链路一次性列清。

指令：「写一份 ONBOARDING.md：列出启动所需的环境变量、依赖安装命令、本地起服务的步骤、以及你预期会踩的坑。」

这一步直接省掉"问前同事（已离职）+ 猜配置"的半天。我建议跑一遍它给的步骤，凡是它写"应该就行"的地方，都自己实际敲一遍命令——它能列全，但版本号、端口冲突这类细节经常会过时。

3. 编译跑通：最小化改动 + 给清单

让它能 build，但严格限制改动范围，并且每条改动都要解释。

指令：「只做让项目能编译通过的最小改动。改完给出清单：每条改动的文件、原因、属于依赖/配置还是业务逻辑。」

关键在后半句：让它区分"改了依赖/配置"和"改了业务代码"。前者基本安全，后者你要额外盯。

这块有个经验：agent 跑通编译时常踩三个坑，你 review 时直接照着查：

坑一：顺手升级依赖大版本。为了消一个弃用警告，把某个库从 v2 升到 v3，引入 breaking change。能用小版本修就别动大版本。
坑二：只验证了能 build，没真正起服务。编译过 ≠ 能跑。它常漏掉"需要连某个外部服务 / 某个环境变量"这一步。务必按 ONBOARDING 真正起一次服务。
坑三：为了跑通测试去改测试本身。删掉失败的用例、或把断言改松、或把警告不当错误，测试变绿了但问题没解决。这种"假绿"最害人，看到测试文件被改要格外警惕。

4. 分模块问，别一次甩全库

项目大，一次问全库它容易胡编。缩小范围，命中率高得多。

例：「先只讲消息发送这条链路，从触发到落库经过哪些模块、各自负责什么。」

一条链路问透，比"整个项目讲讲"得到的东西扎实。我通常按"用户请求 → 业务处理 → 落库 → 异步/对外"这样切，一次问一段。

一个少返工的小习惯：约定文件

在仓库根目录放一份约定文件（Codex / Claude Code 都认这类 instructions），写明"禁止改代码风格、改动先给清单、禁止升级大版本依赖"。Codex 不像 Claude Code 有现成的 slash skill 市场，但这种约定文件能补上缺口，少一堆返工。我自己放的是一份 AGENTS.md，每次新会话它都先读，省得每轮重复叮嘱。

真实耗时

预估两三周 → 实际几天跑通、能本地起服务。省下的不是一两小时，是一段本该用来"搞清楚这项目到底是啥"的耐心。

它能做 vs 别让它碰

说清楚边界：读代码、画架构、补 onboarding、配环境、跑编译——这些它又快又稳。但一旦进入"改有状态、有副作用的业务逻辑"（消息、钱、订单），它就不再那么可信了。读懂之后那一步，恰恰最容易翻车，我下篇用一次生产事故来说。

下篇讲：读懂之后改 bug，agent 没这么靠谱——我曾因信了它的修复，让客户替我测出了生产事故。

觉得有用的同学，请点赞❤️关注+收藏。你接手过没文档的烂摊子么？第一件事通常做啥？评论区聊聊。