用 AI 接手老代码：陌生项目 onboarding 工作流

适用场景

• 新人入职，被丢给一个 5 年老项目
• 接手前同事跑路留下的代码
• 评估一个开源项目能否用作技术选型
• 给客户做代码 audit / 接手报价

用人脑读两周做的事，AI 协助下 2-4 小时完成 80%。

总览：六步法

1. clone & 准备 → 2. 项目体检 → 3. 架构图 → 4. 核心路径 →
5. 风险与债务 → 6. 关键问题清单

每一步都有具体 Prompt + 验收标准。

Step 1 — clone 与环境准备（10 分钟）

git clone <repo>
cd <repo>
# 关键：先让 AI 看 git 历史活跃度
git log --since='1 year ago' --pretty=format:'%h %s' | wc -l

打开 Claude Code 或 Cursor，进入项目目录。

第一条 Prompt：

"请扫描当前目录，告诉我：(1) 这是什么类型的项目；(2) 主要技术栈；(3) 入口文件在哪；(4) 有没有 README / docs。先不要读源码，只看 package.json / pyproject.toml / Cargo.toml / go.mod 这类元文件。"

为什么：先让 AI 建立宏观认知，避免它一上来就被某个文件带偏。

Step 2 — 项目体检（20 分钟）

让 AI 出一份"健康报告"：

请生成一份项目体检报告，包含：

1. 代码量：按语言/目录分布
2. 测试覆盖：有没有测试，跑得起来吗，覆盖率多少
3. 依赖健康：有几个依赖、最旧的几个分别多久没更新
4. 文档完整度：README / CHANGELOG / CONTRIBUTING / docs/
5. CI 状态：有 CI 吗，最近一次跑成功了吗
6. 死代码迹象：明显未使用的文件 / 函数

不要猜测，只报告确凿能看到的事实。每条结论给出依据。

Claude Code 做这事最强——它会自己跑 find、git log、npm outdated 这类命令，给出真凭实据。

Step 3 — 架构图（30 分钟）

基于刚才的体检，画一张项目架构图（Mermaid 格式）。
要求：
- 顶层模块用方框
- 数据流向用箭头
- 外部依赖（DB / 第三方 API / 队列）单独标出
- **如果某个边界你不确定，标 "?" 而不是猜**

画完后，用 5-10 句话解释这个架构的核心思路。

关键技巧：明确告诉 AI "不确定就标 ?"，否则它会编。

把生成的 Mermaid 复制到 mermaid.live 验证可视化效果。

Step 4 — 找到"核心路径"（30 分钟）

这是 onboarding 最关键的一步。每个项目都有 1-3 条核心业务路径——用户最常用的功能链路。把它走通，整个项目就懂一半了。

请找出本项目的 3 条核心业务路径（按重要性排序）：

每条路径需要回答：
1. 用户从哪触发（URL / API endpoint / CLI 命令）
2. 经过哪些关键文件 / 函数
3. 数据如何流动（DB 读什么、写什么）
4. 在哪里返回结果

用编号列表给出，每个文件名 + 行号都要确凿。

验收标准：你能照着这份路径，自己手动 trace 一遍而不卡壳。如果哪一步看不懂，回去问 AI 那一段具体是什么。

Step 5 — 风险 + 技术债清单（30 分钟）

请审视代码库，列出：

A. 高风险代码（运行时容易出问题）
   - 没有错误处理的 IO / 网络调用
   - 明显的 race condition / 并发问题
   - 写死的 secret / API key
   - SQL 注入 / XSS 风险

B. 技术债（影响开发效率）
   - 重复的代码 (DRY 违反)
   - 函数过长（>200 行）
   - 圈复杂度过高的函数
   - 循环依赖

C. 维护性差的部分
   - 完全没注释的关键算法
   - "magic number"
   - 命名混乱的模块

每条给出文件路径 + 行号，并用 1 句话解释为什么是问题。

这一步的输出可以直接交给客户/老板——如果你是接外包、做 audit，这就是付费报告的核心内容。

Step 6 — 关键问题清单（20 分钟）

最后一步，让 AI 列出"作为新人接手，你最该问原作者的 10 个问题"：

假设你即将接手这个项目，原作者今天最后一天上班，
你只能问他 10 个问题。请列出这 10 个问题，按重要性排序。

每个问题要：
- 具体（不能是"这个项目怎么部署"这种宽泛问题）
- 可被一句话回答
- 解决之后你能独立运行/修改这个项目

这份清单极其有价值——它把"未知的未知"转化成"已知的未知"。你可以拿着它去问前同事 / 客户 / 文档 / 社区。

一个真实案例

接手一个 4 年的 Django + Vue 老项目（约 18 万行），原作者已离职、文档只有半页 README。按这套六步法实操：

• Step 1-2（35 分钟）：体检发现测试覆盖率仅 12%、有 3 个依赖超过 2 年没更新、CI 早已失效。
• Step 3（30 分钟）：架构图暴露出一个隐藏的"上帝模块"——一个 2400 行的 utils.py 被几乎所有模块导入，是后续重构的最大障碍。
• Step 4（40 分钟）：3 条核心路径里，"下单"路径穿过 11 个文件，其中一处用未文档化的 Django signals 做副作用，这正是新人最容易踩的雷。
• Step 5-6（45 分钟）：风险清单揪出 2 处字符串拼接 SQL，关键问题清单第一条就是"那个上帝模块能不能拆"。

整个过程约 2.5 小时，产出的文档让第二个新人当天就能跑起项目并改第一个 bug——对比之前"靠自己读两周还摸不清下单流程"，是数量级的差距。最关键的发现（上帝模块、未文档化的信号）都不是 AI 猜出来的，而是它跑命令、读真实代码后给出 file:line 依据的。

总耗时与产出

把这 5 份文档存进项目 docs/onboarding/，下一个新人来直接读，再省 2 小时。

工具选择

• Claude Code：最适合这种"广撒网"任务，自己跑 find/git log/npm outdated 等命令、读文件、给 file:line 依据。大项目首选。深度评测见 Claude Code 深度评测。
• Cursor + @codebase：体验也很好，胜在便宜、有 IDE 可视化。中型项目（< 5 万行）够用。
• Aider：可以，但要手动 add 文件，节奏更慢，适合你已经知道要看哪些文件的情况。
• Trae：国内项目首选，中文 prompt 体验最佳，访问无需代理。

三家 IDE 的横向对比见 Cursor vs Windsurf vs Trae 实测。无论用哪个，这套六步法的 prompt 都通用。

踩坑

• 不要让 AI 一次读完整个项目——它会丢上下文。分模块 + 每模块独立提问。
• 关键结论要让它给出文件:行号 作为依据，否则容易编。
• 不要过度依赖 AI 的"我觉得"——遇到不确定的地方，强制让它标记不确定，然后人工 verify。

常见反模式

• 一次性把整个仓库丢给 AI 让它"全读一遍"——必然丢上下文，输出泛泛而谈。永远分模块、分步骤。
• 接受没有 file:line 依据的结论——"这个项目用了观察者模式"如果没有具体文件佐证，很可能是 AI 顺嘴编的。要求每条结论可追溯。
• 跳过 Step 4 直接改代码——没走通核心路径就动手，等于盲改。核心路径是理解项目的脊椎，省不得。
• 不保存产出——5 份文档不存进 docs/onboarding/，下一个新人又得重来一遍，白白浪费这 2.5 小时的价值。

延伸阅读

• Claude Code 深度评测 — 本流程的首选工具
• Cursor vs Windsurf vs Trae 实测 — IDE 选型
• 大型重构的 AI Agent 工作流 — 读懂之后怎么改