用 Claude Code 给陌生仓库建索引
让 Claude Code 在仓库里生成 CODEBASE.md,记录模块职责、数据流、变更热点、测试入口和高风险区域。后续提问时要求附上文件及行号,便于回到源码验证。
AI 深度解读
接手陌生仓库时,作者建议先让 Claude Code 生成一份 CODEBASE.md,再带着具体问题读代码。地图帮你找到入口、状态和模块边界,回答则要回到源码核实,给出文件路径和行号。
这套方法最适合回答接手当天就会遇到的问题,比如一个组件被哪些页面用到,或者支付失败会走哪条分支。改代码之前,还可以用同一份地图找出改动频繁、依赖面广、又缺少测试的文件。
一份 CODEBASE.md 要写什么
作者把地图分成七块。每块只要写到能指引下一次查找的程度。
- 项目用途从
README、包配置文件和应用入口里核对。 - 顶层目录各用一行说明负责什么,以及模块之间怎么交互。
- 数据部分写清状态存在哪里,以及主要数据流经过哪些模块。
- 热点部分找出过去 90 天改动最多、体积最大、被其他文件导入最多的文件。
- 测试部分列出测试位置、运行方式,以及哪些模块没有测试。
- 规则从贡献指南、AI 指令文件、Lint 配置和 CI 里提取。
- 高风险区域标出认证、支付、迁移、生成代码和明确标记「不要编辑」的文件。
作者称生成地图只需几分钟,团队可以把它留在仓库里,作为共同的阅读起点。他们团队使用的免费 starter kit 支持 Claude Code 和 Codex,并在 GitHub 提供。
问到具体行为,就让 AI 给出源码位置
可以像问同事一样问 Claude Code:「新用户在哪里创建?」「支付失败后会发生什么?」「哪些页面用了这个组件?」先让它用地图缩小查找范围,再打开相关代码确认,每条关键结论都附上文件路径和行号。如果源码和地图对不上,就修正地图。
行号的价值在于方便复核。比如,找到创建用户的函数,只能说明创建逻辑写在哪里。要回答注册时何时真正创建用户,还得沿着调用链看是谁调用它、调用前经过哪些判断。
改动之前,先估一下影响面
作者举了一个例子。某文件一季度内改了 30 次,被 40 个其他文件导入,而且没有测试。这三个信号叠在一起,足以让人先花时间查清调用方,再决定怎么改。
三个指标回答的是不同的问题。改动次数反映近期变动有多频繁,文件体积提示阅读和理解成本,导入数量则提供了影响面的线索。地图里标过的认证、支付和迁移也要单独看,因为它们即使改动很少,出错的代价也可能很高。
我的判断
这套方法最实用的是「先定位,再核实」。临时查一个组件,直接搜符号和引用通常更省事。多人陆续接手同一仓库,或者同一类问题反复出现,才更容易摊薄建图和维护的成本。
原文没有给出仓库规模、实测耗时、回答准确率,也没有和直接搜索做对照。「几分钟出图」和「提前看出改动会破坏什么」是作者的经验和工具主张。尤其在前端,静态导入数只能反映能查到的引用,配置驱动的路由和运行时依赖还得继续追。文件路径和行号让答案可查,最后仍要看引用的代码能否支撑结论。
能拿来做什么
- 接手前端仓库时,让 AI 从包配置和应用入口生成
CODEBASE.md,自己抽查路由入口、共享状态和测试命令。 - 要改共享组件时,先让 AI 列出引用它的页面、各处传入的参数和相关测试,并给出文件路径和行号。
- 排查 Node 服务里的支付失败时,让 AI 从请求入口追到错误分支和状态写入点,逐处给出源码位置,发现地图过时就顺手修正。