大代码库探索策略

一句话定义

面对陌生代码库，正确策略是「先问地图、再问路线、后问点位」——用递进的提问序列建立结构认知，再定位最小改动点，而不是上来就把任务砸给 AI。

为什么重要

在陌生仓库直接派任务，AI 只能基于目录名与泛化经验「编」一套实现，产出一看就不属于这个代码库。先花 15 分钟让 AI（配合你自己）建立结构地图，后续每次生成的代码都会贴着仓库的真实惯例——这是「AI 产出像不像本仓库代码」的分水岭，也直接决定评审成本。

前置知识

kp-005（代码库理解的三条取材路径）。

核心概念

• 地图层：目录结构、模块职责、入口文件、构建与测试方式。产出物是一张「导览图」。
• 路线层：目标功能的数据流——从入口到存储经过哪些模块、关键接口在哪。
• 点位层：要改动的具体函数/文件，即上下文包（kp-008）的取材范围。
• 小步假设：每层结论都用一个可验证的问题确认（「X 真的调用 Y 吗」），而不是接受叙述。

提问序列模板（代理层可直接派发，对话层配合手动检索）：

第 1 问（地图）：读 README 与目录树，用 10 行总结本仓库的模块划分与构建/测试命令。
第 2 问（路线）：「订单状态流转」功能的数据流经过哪些文件？给出文件路径与关键函数名。
第 3 问（点位）：修改该功能的最小改动点是什么？列出文件:行号并说明为什么是它。
第 4 问（验证）：改动会影响哪些现有测试？

原理与机制

递进序列与 kp-005 的取材路径对齐：地图层让语义检索有「锚点词」（模块名），路线层用关键词检索锁定真实调用链，点位层才值得投入显式上下文预算。跳层直接派任务的失败机制是：模型缺少锚点，只能用「训练数据里的典型项目结构」填空——这就是「通用模板味」的来源。每层的验证性提问则是把幻觉拦截在投入代码之前：叙述可以被 confidently 编造，但「给出文件路径与行号」可以被抽查。

实例或案例

操作步骤（30 分钟陌生仓库开工流程）：

1. 跑第 1 问得到导览图，用 ls/目录树抽查它没编造目录。
2. 跑第 2 问，挑 2 个关键函数用 grep 验证调用关系属实。
3. 跑第 3 问得到点位清单，人工确认改动范围合理性。
4. 跑第 4 问，把受影响测试记入任务验收。
5. 按点位打包上下文包（kp-008），开始正式任务。
6. 把确认过的导览图存入 docs/ai-notes.md，团队复用。

排错清单：

• 导览图出现不存在的模块 → 要求「只依据实际文件列举」，并抽查两个条目。
• 路线层给出含糊调用链 → 换关键词检索：让 AI 输出 grep 命令清单，你本地跑。
• 点位层遗漏副作用 → 追问「谁还调用了这个函数」，要求列出全部调用方。
• 仓库过大第 1 问就超时 → 缩小范围到目标子目录再问地图。

公式或模型

本节不适用：探索是定性流程，无量化模型。

图示

地图层(结构) ──锚点──▶ 路线层(数据流) ──验证──▶ 点位层(最小改动点)
   10 行导览图            文件路径+函数名            文件:行号 清单
        └──────── 每层结论抽查验证后再深入 ────────┘

直观类比

像陌生城市找路：先看地图认区域，再规划经过哪些主干道，最后才定导航到哪个门牌。跳过前两步直接导航，常被带进单行道。

常见误区

• 把探索当浪费：15 分钟地图换来的是全程贴合惯例的产出。
• 接受叙述不验证：对「文件路径与行号」做抽查是防幻觉的最廉价手段。
• 导览图用完即弃：存档复用，它是团队的增量资产。

与其他知识点的关系

本节产出物直接喂给 kp-008 的上下文包；发现 bug 后转入 kp-014 调试协作。

自测题

要点：地图（导览图）→ 路线（数据流文件清单）→ 点位（文件:行号改动点）。

要点：叙述可被自信地编造，路径与行号可被廉价核实，把幻觉拦截在投入成本之前。

1. 三层提问序列是什么？各层产出物？
2. 为什么每层都要「抽查验证」？

延伸阅读

《代码整洁之道》之外的探索类经典较少——本节不适用为：探索策略属实践归纳，建议以第 1 节流程在真实仓库演练。