用 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 个问题，按重要性排序。

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

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

总耗时与产出

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

工具选择

• Claude Code：最适合这种"广撒网"任务，自己跑命令、读文件。首选。
• Cursor + @codebase：体验也很好，胜在便宜。中型项目（< 5 万行）够用。
• Aider：可以，但要手动 add 文件，节奏更慢。
• Trae：国内项目首选，中文 prompt 体验最佳。

踩坑

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

下一篇：大型重构工作流。