主题
11.1 遗留代码库考古
接手一个陌生的百万行代码库，7 步建立可靠认知。
读完你能做什么：把"面对陌生代码的恐慌"变成一套可执行的探索流程。
核心原则
先建地图，再挖细节。 不要一上来就让 Claude 读一堆文件 —— 那会把关键内容埋进上下文的中段衰减区（见 03.2）。
用只读模式开始，避免它在你还没理解时就乱改：
bash
claude --permission-mode plan --model opus第 1 步：地形勘察（不读正文）
text
> 只看目录结构和配置文件，不要读任何源码正文。告诉我：
1. 这是什么类型的项目（语言、框架、单体还是微服务）
2. 顶层模块划分是什么
3. 入口点在哪
4. 依赖哪些外部服务（从配置和依赖清单推断）
输出一张模块地图。第 2 步：并行调查（子代理隔离噪音）
text
> 派子代理并行调查（互不依赖）：
1. Explore 子代理：梳理核心目录的职责
2. haiku 子代理：统计各模块代码量，找出最大的 10 个文件
3. 一个子代理：用 git log 分析近 6 个月改动最频繁的 5 个模块
4. 一个子代理：找出所有测试目录，报告测试怎么跑
汇总成一份概览。子代理让大量文件读取的噪音隔离在各自的上下文里（见 06.4）。
第 3 步：追踪核心数据流
text
> 选一个最核心的用户操作（比如"下单"），追踪它的完整代码路径：
从入口（API/路由）→ 业务逻辑 → 数据持久化。
用 grep 定位，只读路径上的关键函数，画一张时序图（mermaid）。第 4 步：定位"危险区"
text
> 找出这个代码库里的高风险区域：
1. 改动最频繁 + 最大的文件（既复杂又不稳定）
2. 没有测试覆盖的核心逻辑
3. 有大量 TODO/FIXME/HACK 注释的地方
4. 明显的技术债（超长函数、深层嵌套、重复代码）
按风险排序，说明每处的风险是什么。第 5 步：建立项目记忆
把探索成果固化，避免下次从头再来：
text
> 基于我们的探索，生成一份 CLAUDE.md，包含：
- 项目类型和技术栈
- 模块划分和各自职责
- 构建和测试命令
- 核心数据流
- 已知的危险区和坑
控制在 200 行内。之后每次会话，Claude 读这份 CLAUDE.md 就有了基础认知（见 05.6）。
第 6 步：验证理解
关键一步 —— 让它证明理解是对的，而不是编的。
text
> 你刚才说的架构理解，逐条给我证据：
每个关于模块职责的断言，指出对应的文件和关键代码行。
你不确定的地方，明确标出来，我们一起确认。这对抗了幻觉 —— 陌生代码库是幻觉高发区（见 04.3）。
第 7 步：小改动试水
text
> 找一个低风险的小改进（改个日志、补个注释、修个明显的小 bug），
完整走一遍：改动 → 跑测试 → 确认没破坏东西。
让我熟悉在这个项目里做改动的完整流程。完整流程速览
text
1. 地形勘察 只看结构，不读正文 → 模块地图
2. 并行调查 子代理隔离噪音 → 概览
3. 数据流追踪 追一个核心操作 → 时序图
4. 危险区定位 找高风险区域 → 风险清单
5. 建立记忆 固化成 CLAUDE.md → 持久认知
6. 验证理解 要证据，标不确定 → 可信的理解
7. 小改动试水 走通完整流程 → 上手信心常见错误
| 错误 | 后果 | 正确做法 |
|---|---|---|
| 一次读几十个文件 | 关键内容进衰减区 | 先索引后精读 |
| 不用 plan 模式 | 还没懂就被改乱 | 只读开始 |
| 全信它的架构描述 | 陌生代码幻觉高发 | 第 6 步要证据 |
| 不建 CLAUDE.md | 每次从头再来 | 固化认知 |
| 一上来就改大的 | 风险失控 | 小改动试水 |