借助 AI 梳理陌生代码库：一套分阶段项目导览流程

接手陌生代码库时，最危险的往往不是找不到文件，而是在缺少整体认识的情况下过早修改局部实现。目录名、搜索结果和 AI 推测都只能提供线索，无法替代对启动入口、模块边界与真实调用关系的验证。下面将按固定顺序建立项目地图，并逐步缩小到当前任务的最小影响范围。

开篇

接手一个陌生项目时，你通常会先做什么？

很多开发者的第一反应是：

打开项目
  ↓
搜索需求关键词
  ↓
找到一个看起来相关的文件
  ↓
直接开始修改
  ↓
在启动失败、测试失败和联调失败中补上下文

这种方式偶尔也能完成任务。

但如果项目比较大，或者需求涉及多个模块，直接搜索关键词很容易遇到这些问题：

• 找到的是 DTO、测试桩或历史代码，不是真正的业务入口。
• 只看到了一个方法，没有理解它上下游的调用关系。
• 修改了局部实现，却破坏了项目原有的分层和约定。
• 忽略了配置、权限、消息、缓存或数据库迁移等关联部分。
• AI 根据文件名猜测项目结构，生成了一份看似完整但无法落地的方案。

上一篇文章，我们讨论了让 AI 在写代码前先回答 6 个问题。

但在它回答这些问题之前，开发者还需要先把项目本身讲清楚一些。

这篇文章分享一套我会反复使用的代码库导览工作流：

项目概览
  ↓
启动入口
  ↓
模块边界
  ↓
请求与数据流
  ↓
任务相关代码
  ↓
最小修改范围

目标不是让 AI 一次性读完整个仓库，而是让它像一名新加入项目的开发者一样，先建立地图，再进入具体房间。

本文不会讨论什么

代码库导览不是把整个仓库压缩后丢给 AI，也不是让 AI 代替开发者完成所有架构判断。

本文不会：

• 建议把所有源代码、配置文件和日志一次性发送给 AI。
• 认为 AI 生成的项目总结天然准确。
• 用一张目录树代替对真实调用链的验证。
• 在没有确认项目边界前直接让 AI 修改多个模块。
• 讨论特定 IDE 或模型的唯一使用方式。

本文关注的是一套通用方法：

让 AI 分阶段阅读有限上下文，并且每一阶段都留下可以人工核对的产物。

一、为什么读陌生项目要先建立地图

一个项目真正的结构，通常不等于文件夹结构。

例如，一个“新增订单状态”的需求，可能同时涉及：

HTTP 接口
  ↓
参数校验
  ↓
应用服务
  ↓
领域规则
  ↓
数据库更新
  ↓
消息通知
  ↓
查询接口和前端展示

如果只搜索 status，你可能会得到几十个结果，却不知道哪个结果处于真正的业务路径上。

AI 的优势是可以快速归纳大量结构化信息，但它需要开发者提供清晰的阅读顺序。

我通常会先要求 AI 回答三个问题：

1. 这个项目从哪里启动？
2. 一个请求是怎样流经系统的？
3. 当前任务最可能影响哪些模块？

当这三个问题有了初步答案后，再去阅读具体代码，效率会高很多。

可以把代码库导览理解成一张逐渐放大的地图：

导览层级	主要目标	产物
项目级	了解技术栈、启动方式和模块组成	项目概览
模块级	确认各模块职责和依赖关系	模块地图
流程级	理解请求、数据和异常如何流转	调用链
任务级	定位本次需求的最小影响范围	修改清单

每一层都不要急着写代码。

二、先准备一份安全、有限的项目上下文

AI 导览的质量，很大程度取决于你提供的上下文是否合适。

1. 第一轮优先提供什么

第一轮通常只需要提供这些信息：

- 项目目录树，排除依赖目录和构建产物
- README 或项目说明
- 构建文件和依赖清单
- 应用启动入口
- 配置文件的脱敏版本
- 当前要处理的需求

例如，Java 项目可以先提供：

src/main
src/test
pom.xml
README.md
application.yml（已脱敏）

Node.js、Go、Python 项目也可以使用相同思路，替换为对应的依赖和启动文件。

2. 第一轮不要提供什么

以下内容通常不适合直接发送：

• .env、私钥、访问令牌和生产配置。
• 未脱敏的用户信息、订单信息和业务日志。
• node_modules、target、dist 等依赖或构建目录。
• 与当前任务完全无关的大量历史文件。
• 无法确认来源的数据库导出文件。

可以先让 AI 告诉你“还需要哪些文件”，再按任务范围补充。

3. 先生成目录树，不要先上传整个仓库

目录树是很好的第一份上下文，因为它能帮助 AI 先判断项目边界。

可以使用类似命令生成基础目录信息：

tree -L 3 -I 'node_modules|target|dist|.git|build'

如果环境没有 tree，也可以使用 IDE 的项目视图或其他目录列表工具。

目录树不是最终答案，它只是导览的起点。

三、第一站：让 AI 生成项目级地图

第一轮不要问“请解释这个项目”，这个问题太宽泛，容易得到一段没有行动价值的介绍。

建议把任务限定为“项目导览”：

你现在是一名刚加入团队的高级开发者，请先为这个项目建立一张导览地图。

请基于我提供的目录树、README、构建文件和启动配置，回答：
1. 项目使用了哪些主要技术和运行方式？
2. 应用从哪个入口启动？
3. 顶层目录或模块分别负责什么？
4. 哪些目录是业务代码，哪些是基础设施、脚本或测试？
5. 目前还不能确定的内容有哪些？

要求：
- 只基于已提供的信息判断。
- 已确认、推测、待验证内容分开列出。
- 不要修改代码。
- 不要对没有阅读过的文件做确定性结论。

这一轮的重点不是让 AI 讲得多，而是观察它能否区分事实和推测。

可以要求它使用这样的格式：

内容	当前判断	证据	置信度
启动入口	Application 类	启动类注解	高
用户模块位置	可能位于 user 包	目录名称	中
登录流程	尚未确认	缺少 Controller 文件	低

这种输出比“这是一个典型的管理系统”更有用，因为你知道下一步应该验证什么。

四、第二站：让 AI 找到真实启动路径

目录结构只能告诉你文件在哪里，不能告诉你程序是怎样运行起来的。

接下来需要确认启动入口、配置加载和请求入口。

可以继续使用下面的 Prompt：

请继续分析项目的启动路径，不要写代码。

请说明：
1. 应用启动类或主函数在哪里？
2. 启动时会加载哪些配置？
3. Web 服务、定时任务、消息消费者或其他运行入口在哪里注册？
4. 本地启动需要哪些依赖服务？
5. 从启动到第一个业务请求，关键经过哪些组件？

请为每个结论标注对应文件和代码位置。
无法确认的内容列入“待验证项”。

这一轮尤其适合发现“项目不只有一个入口”。

一个后端系统可能同时包含：

• HTTP API。
• 定时任务。
• 消息队列消费者。
• CLI 管理命令。
• 数据同步脚本。
• 测试启动配置。

如果当前需求和订单同步有关，真正的入口可能不是 Controller，而是消息消费者或定时任务。

因此，先确认运行入口，可以避免沿着错误的方向阅读代码。

五、第三站：沿着一个真实请求走通调用链

项目地图建立后，不要继续要求 AI 泛读所有模块。

最有效的方式是选择一个真实功能，沿着调用链走一遍。

例如，你要理解“查询用户详情”，可以提供：

请沿着“查询用户详情”这个功能，分析一条完整的请求链路。

请按以下顺序输出：
1. 请求入口和路由。
2. Controller 或 Handler 的参数处理。
3. Service 或 UseCase 的业务编排。
4. Repository、DAO 或外部服务调用。
5. 返回对象和字段转换。
6. 异常如何产生和返回。
7. 相关日志、权限、缓存和测试位置。

请用“文件路径 + 类名/函数名 + 作用”的形式说明。
如果某一步无法从已提供代码确认，请明确标记。

建议让 AI 同时输出一份简化流程：

请求
  ↓
UserController.getDetail()
  ↓
UserService.findDetail()
  ↓
UserRepository.findById()
  ↓
UserDetailAssembler.toResponse()
  ↓
统一异常和响应处理

这张调用链比单独阅读十几个文件更容易建立整体理解。

重点看哪些信号

在调用链中，我通常会重点检查以下内容：

信号	需要确认的问题
参数校验	校验是在入口层、业务层还是公共组件中完成？
权限判断	是注解、拦截器还是业务代码判断？
事务边界	哪一层负责事务，是否包含外部调用？
数据转换	领域对象、数据库对象和响应对象如何转换？
异常处理	业务异常和系统异常如何区分？
测试方式	测试的是接口、Service 还是 Repository？

这些项目约定往往比某个具体类的写法更值得保存。

六、第四站：让 AI 总结项目的编码约定

读懂陌生项目，不只是知道“代码在哪”，还要知道“为什么这样写”。

可以从已经确认的代码中提炼项目约定：

请基于以下已阅读文件，总结项目中已经存在的编码约定。

请分别分析：
1. 模块和包的职责边界。
2. 类、方法和变量的命名方式。
3. Controller、Service、Repository 的分层方式。
4. 参数校验、异常、日志和事务的处理方式。
5. DTO、Entity、VO 或响应对象的转换方式。
6. 单元测试和集成测试的组织方式。

每条约定都请附上：
- 约定内容
- 参考文件
- 是否属于强约束
- 新代码是否应该复用

不要把个人建议写成项目现有规范。

AI 很容易把“常见最佳实践”误写成“当前项目规范”。

因此要特别强调：

项目已有事实、AI 的推测和 AI 的建议必须分开。

例如：

项目事实：现有 Service 方法都返回领域对象。
AI 建议：新接口可以统一改为返回 DTO。

这两句话不能混在一起，否则你很可能在一次小需求中顺便引入一套未经评审的新风格。

七、第五站：从项目地图收敛到本次任务

当你已经知道项目如何启动、请求如何流转、模块如何协作后，才进入当前需求。

可以这样要求 AI 定位任务影响范围：

需求：为用户中心增加“导出用户列表”功能。

请基于前面已经确认的项目地图，定位本次需求的最小影响范围。

请输出：
1. 最可能的入口文件。
2. 需要阅读的核心文件。
3. 可能需要新增或修改的文件。
4. 不应该修改的模块。
5. 需要确认的权限、数据量、异步和导出格式问题。
6. 建议的阅读顺序。

暂时不要写代码，也不要直接给出最终实现。

这一步的产物应该是一份“阅读和修改清单”，而不是一份大而全的改造方案。

示例：

类型	文件或模块	目的
必读	用户列表 Controller	确认入口和权限
必读	用户查询 Service	复用现有筛选规则
必读	用户 Repository	判断分页和查询能力
待确认	导出任务模块	判断是否需要异步导出
暂不修改	登录模块	与本次需求无直接关系

当 AI 能明确说出“哪些不应该改”时，说明导览已经开始收敛。

八、实战：一套可以直接复用的代码库导览 Prompt

下面这套 Prompt 适合第一次接触一个中等规模项目时使用。

你现在是一名协助我熟悉陌生代码库的高级开发者。

当前任务：
<填写本次需求，尽量使用业务语言描述>

我会分批提供项目上下文：
1. 目录树
2. README 和构建文件
3. 启动入口与配置
4. 与需求相关的代码

请严格按照以下阶段工作，不要跳到写代码：

阶段一：项目地图
- 技术栈、启动方式、顶层模块和主要运行入口

阶段二：真实调用链
- 从一个相关功能出发，说明请求、业务、数据和异常如何流转

阶段三：项目约定
- 总结已经存在的分层、命名、校验、异常、日志、事务和测试规范

阶段四：任务范围
- 定位本次需求的最小影响范围
- 列出必读文件、可能修改文件和明确不应修改的文件

每个阶段都请区分：
- 已确认事实
- 基于代码的推测
- 待人工验证项

输出要求：
- 引用文件路径、类名和函数名
- 不阅读的文件不要猜测
- 不要把通用最佳实践冒充项目现有规范
- 每个阶段结束时，给出我下一步应该提供的最小上下文
- 未收到我确认前，不生成代码

这套 Prompt 的关键不在于字数，而在于把“阅读顺序”和“停止条件”写清楚。

九、导览过程中最容易犯的 5 个错误

1. 一开始就让 AI 总结整个仓库

仓库越大，越应该分批阅读。

一次性输入太多内容，会让重点被目录、重复代码和无关配置淹没。

2. 只给文件名，不给文件内容和任务背景

文件名只能提供线索，不能证明职责。

UserService 可能是业务服务，也可能只是远程调用封装。必须结合调用方、实现和测试判断。

3. 把 AI 的推测当成项目事实

看到“应该”“通常”“可能”时，要把它们单独记录为待验证项。

尤其是权限、事务、数据一致性和异常策略，不能仅凭命名推断。

4. 只看主流程，不看测试和配置

测试通常能说明真实边界，配置通常能说明运行依赖。

只阅读主流程，容易得到“代码能走通”的假象，却不知道项目如何验证和部署。

5. 导览结束后没有形成可保存的产物

如果每次都从头问 AI，前面的理解很快会丢失。

建议至少保存以下内容：

docs/
  project-map.md
  request-flow.md
  coding-conventions.md
  task-scope.md

不一定要真的创建这 4 个文件，但应该把结论整理成可以复用的项目知识。

十、我的代码库导览检查卡

在开始修改陌生项目之前，我会快速确认下面这些问题：

[ ] 我知道项目如何启动
[ ] 我知道本次需求对应的真实运行入口
[ ] 我走通了一条相关功能的调用链
[ ] 我知道关键模块的职责边界
[ ] 我区分了项目事实、AI 推测和待确认项
[ ] 我看过相关测试和配置
[ ] 我知道本次需求的最小影响范围
[ ] 我列出了明确不应修改的模块
[ ] 我已经保存了项目地图和任务清单
[ ] 我还没有在上下文不完整时让 AI 直接写代码

如果最后一项没有做到，说明导览还没有真正完成。

十一、总结

用 AI 读懂陌生项目，最有效的方式不是让它一次性解释整个仓库，而是按照固定顺序逐步建立上下文：

1. 先生成项目级地图。
2. 再确认启动入口和运行方式。
3. 沿着一个真实功能走通调用链。
4. 从现有代码中提炼项目约定。
5. 最后收敛到本次需求的最小影响范围。

在这个过程中，要始终保留三个标签：

已确认事实
  ≠
基于代码的推测
  ≠
待人工验证项

AI 可以帮助你更快建立项目认知，但不能替你承担未经验证的判断。

请记住：

读懂代码库的第一步，不是找到要改的文件，而是知道这段代码在整个系统里为什么存在。

下一篇文章，我们继续沿着这条工作流深入：

让 AI 画出真实调用链：从入口、服务到数据库和外部依赖。