编程开发 编辑复核

陌生代码库上手阅读路径

从目录结构和运行方式出发排出阅读顺序,先跑通再沿真实链路读代码,尽快做出第一个安全改动。

场景:接手遗留项目或加入新团队的头两周输出:项目地图 + 阅读顺序 + 关键链路追踪 + 练手任务更新于 2026-09-01

复制后替换变量

保留结构,先填真实信息,再把结果交给模型运行。

你是一名代码库上手向导。请根据目录结构和运行方式排出一条从跑通到动手改动的阅读路径。

先把已知事实、合理假设和待核验信息分开;资料不足时写“待验证”,不要为了完整而猜测。

请按以下结构输出:
1. 先列出让项目跑起来所需的步骤和验证方式
2. 画出项目地图,说明每个顶层目录的职责和相互依赖
3. 挑一条核心用户链路,按入口、路由、业务逻辑、数据访问的顺序列出要读的文件
4. 标出可以先跳过的目录,说明为什么现在不用读
5. 给出三个由浅入深的练手任务,每个都写清验证方式
6. 列出必须找人确认的问题,例如没有文档的历史约定

输入变量:
- 仓库结构({{repo_structure}}):粘贴顶层目录树和主要配置文件名。
- 运行方式({{run_commands}}):说明安装、启动和测试命令及依赖服务。
- 上手目标({{learning_goal}}):说明多久内要能做什么改动。

约束:保留原始上下文和限定条件;每个结论都说明依据;涉及个人资料、合同、财务、医疗或安全信息时先提示脱敏和人工复核。

使用说明

  1. 先把项目跑起来再读代码,跑不起来时优先解决环境问题。
  2. 带着一个具体问题读代码,比通读目录记得住。

适用判断

适合这些情况

  • 刚接手项目且没有可用的交接文档。
  • 目录很多但不知道从哪个文件开始读。
  • 想尽快做出第一个不会闯祸的小改动。

换个做法更好

  • 要重新划分模块边界:走重构边界与依赖地图。
  • 要给别人写文档:走 README 与交接文档草稿。
  • 项目根本跑不起来:先排查本地环境报错。

常见翻车与修正

  • 给出的阅读顺序像目录说明,读完还是不知道功能怎么串起来。

    改成沿一条真实用户请求追踪,按调用顺序列出文件和函数,并标出每一跳的输入输出。

  • 模型凭目录名猜测职责而且猜错了。

    要求标注每条判断依据的文件位置,没有依据的写待确认,并用搜索引用关系逐个验证。

怎么判断输出合格

  1. 跑通步骤可以直接执行。
  2. 阅读顺序沿真实调用链路展开。
  3. 被跳过的目录说明了原因。
  4. 练手任务有明确验证方式。

使用边界

  • 目录树和配置文件名可以粘贴,代码正文和连接串不要外发。
  • 模型对目录职责的推断要用实际调用关系核对,不要直接写进交接文档。