这篇文档不讲太多概念，重点是给你一套马上能用的做法：用 Codex 学项目时，不要把所有问题都塞进一个任务里。正确做法是：一个“主线任务”负责整体学习，多个“分支任务”负责具体问题，最后把分支结论回填到主线里。
1. 为什么接手新项目容易混乱
刚接手一个陌生项目时，最容易遇到这些问题：
- README 写得不完整，不知道项目到底怎么启动。
- 目录很多，不知道哪些文件重要。
- 配置文件一堆，不知道哪些影响本地环境。
- 业务链路很长，看着看着就迷路。
- 一个报错查半天，查完又忘了最开始想学什么。
- 和 Codex 聊太久后，任务里混杂了启动、业务、配置、报错、接口、数据库等内容，后面很难翻。
新手常见错误是：开一个 Codex 任务，然后一直问所有问题。刚开始还可以，后面任务会变得又长又乱。Codex 也会被大量上下文拖住，你自己也很难从里面提炼学习笔记。
所以，接手项目时要把“学习”和“排查”分开。
2. 核心方法：主线任务 + 分支任务
推荐把 Codex 任务分成两类：
主线任务
主线任务只负责理解整个项目。它像你的项目学习笔记，记录这些内容：
- 项目是做什么的
- 技术栈是什么
- 怎么启动
- 目录结构
- 核心模块
- 当前学习进度
- 阶段总结
- 待确认问题清单
主线任务不要深入排查复杂问题。比如本地启动报错、某个接口逻辑很绕、某个配置含义不清楚，这些都应该拆出去。
主线任务命名：
【学习主线】项目名 - 项目入门示例：
【学习主线】OrderSystem - 项目入门分支任务
分支任务只解决一个具体问题。它像专项排查记录，目标要小，边界要清楚。
适合开分支任务的问题包括：
- 某个模块的作用
- 某条业务链路
- 某个启动报错
- 某个配置文件
- 某个接口逻辑
- 某个数据库表和代码的关系
- 某个测试失败原因
分支任务命名：
【Q-阶段编号-序号】项目名 - 问题关键词示例：
【Q-03-001】OrderSystem - 启动报错排查 【Q-04-002】OrderSystem - 下单链路分析为什么要这样分
这样做有三个好处。
第一，主线不会乱。主线任务始终只记录项目学习进度，后面回看很清楚。
第二，分支更聚焦。每个分支只解决一个问题，Codex 不容易发散，你也更容易判断问题是否解决。
第三，方便沉淀。分支任务结束后，把结论整理成几段话回填到主线，主线就会越来越像一份完整的项目入门文档。
3. 第一步：让 Codex 快速扫项目
新手第一天不要一上来就读业务代码，也不要直接问“这个项目怎么回事”。更好的做法是让 Codex 先扫一遍项目入口信息。
你可以让 Codex 先看：
- README
- package.json / pom.xml / build.gradle / requirements.txt / go.mod 等依赖文件
- docker-compose.yml / Dockerfile
- 启动脚本
- 配置文件
- 目录结构
- 路由、入口文件、主应用文件
目标不是马上完全理解项目，而是先得到一张“地图”。
你要让 Codex 输出这些内容：
- 项目用途
- 技术栈
- 本地启动方式
- 核心目录说明
- 最应该先看的文件
- 暂时不需要看的内容
- 初步问题清单
这样你不会被细节淹没。
4. 第二步：生成分阶段学习计划
项目初扫完成后，不要马上到处乱看。让 Codex 根据项目情况生成 3 到 5 个学习阶段。
推荐阶段如下：
【阶段01】项目名 - 项目概览 【阶段02】项目名 - 目录结构 【阶段03】项目名 - 本地启动 【阶段04】项目名 - 核心业务链路如果项目更复杂，可以增加：
【阶段05】项目名 - 数据模型 【阶段06】项目名 - 测试与发布流程每个阶段都要写清楚三件事：
- 这个阶段的目标是什么
- 需要看的文件有哪些
- 到什么程度算完成
比如“本地启动”阶段，完成标准不是“看完启动命令”，而是：
- 能说清楚启动依赖哪些环境变量
- 能跑起本地服务
- 知道常见启动失败原因
- 知道服务启动后访问哪个地址
- 知道日志在哪里看
阶段计划越清楚，后面越不容易跑偏。
5. 第三步：按阶段学习，复杂问题开分支
学习时按阶段推进，不要同时看所有东西。
比如你正在做：
【阶段03】OrderSystem - 本地启动你可以让 Codex 带着你看启动脚本、环境变量、配置文件、依赖服务。过程中如果发现复杂问题，不要在当前任务里深挖太久。
例如发现启动时报错：
Database connection refused这时候不要在主线里连续排查半小时。你应该新开一个分支任务：
【Q-03-001】OrderSystem - 启动报错排查在分支任务里只处理这个问题，不分析其他业务代码，不顺手重构，不扩大范围。分支最后输出：
- 问题是什么
- 原因是什么
- 涉及哪些文件
- 怎么解决或绕过
- 可以回填到主线的总结
如果你正在看核心业务链路，发现“下单接口为什么会触发库存锁定”不清楚，也可以开：
【Q-04-002】OrderSystem - 下单链路分析分支任务的关键是：小、短、明确。
6. 第四步：分支结论回填主线
分支任务解决后，一定要回到主线任务整理结论。否则分支只是临时聊天记录，时间久了还是会丢。
回填时不要把分支里的所有过程复制过去。主线只需要结论，不需要完整排查过程。
推荐回填格式：
问题： 结论： 相关文件： 我对项目新增的理解： 后续待确认：示例：
问题： 本地启动时报 Database connection refused。 结论： 项目启动时会读取 .env.local 中的 DB_HOST 和 DB_PORT。默认配置指向本机 5432，但本地没有启动 PostgreSQL，所以连接失败。使用 docker-compose up -d postgres 后可以继续启动服务。 相关文件： .env.example docker-compose.yml src/config/database.ts 我对项目新增的理解： 这个项目本地开发依赖 PostgreSQL，数据库配置集中在 src/config/database.ts，环境变量优先级高于默认配置。 后续待确认： 测试环境和生产环境的数据库配置是否使用同一套配置加载逻辑。这样主线任务会持续变厚，但不会变乱。
7. 推荐命名规范
请坚持简单、固定、可搜索的命名规范。不要今天叫“项目学习”，明天叫“熟悉代码”，后天叫“看一下后端”。
主线任务
【学习主线】项目名 - 项目入门示例：
【学习主线】OrderSystem - 项目入门阶段推进
【阶段01】项目名 - 项目概览 【阶段02】项目名 - 目录结构 【阶段03】项目名 - 本地启动 【阶段04】项目名 - 核心业务链路示例：
【阶段01】OrderSystem - 项目概览 【阶段02】OrderSystem - 目录结构 【阶段03】OrderSystem - 本地启动 【阶段04】OrderSystem - 核心业务链路分支任务
【Q-阶段编号-序号】项目名 - 问题关键词示例：
【Q-03-001】OrderSystem - 启动报错排查 【Q-04-002】OrderSystem - 下单链路分析编号建议：
03表示来自阶段 03。001表示这个阶段的第 1 个问题。- 问题关键词尽量短，比如“启动报错排查”“支付回调分析”“权限配置说明”。
这样以后搜索Q-03，就能看到本地启动阶段遇到的所有问题。
8. 可复制提示词模板
下面这些提示词可以直接复制使用，把“项目名”和具体信息替换掉即可。
1. 项目初扫提示词
你现在帮我快速接手这个项目。请先阅读 README、依赖配置、目录结构、启动脚本、主要配置文件，不要急着深入业务细节。 请输出： 1. 这个项目是做什么的 2. 主要技术栈 3. 本地启动方式 4. 核心目录和文件说明 5. 我应该优先学习哪些文件 6. 暂时可以先不用看的内容 7. 初步发现的问题或风险 要求： - 实用为主，不要写成官方文档 - 如果有不确定的地方，请明确标注“待确认” - 最后给我一个适合新手的下一步建议2. 生成学习计划提示词
请根据你刚才对项目的初步了解，帮我生成一个 3 到 5 个阶段的学习计划。 每个阶段请包含： 1. 阶段名称 2. 学习目标 3. 建议查看的文件或目录 4. 完成标准 5. 可能需要开分支任务的问题类型 请使用这个命名格式： 【阶段01】项目名 - 项目概览 【阶段02】项目名 - 目录结构 【阶段03】项目名 - 本地启动 【阶段04】项目名 - 核心业务链路 要求： - 阶段不要太多 - 每个阶段都要能落地执行 - 优先帮助新手建立项目地图3. 阶段推进提示词
现在请带我推进当前阶段：【阶段编号】项目名 - 阶段名称。 请你按下面方式工作： 1. 先说明这个阶段要解决什么问题 2. 列出本阶段要看的文件 3. 按顺序带我阅读和总结 4. 每看完一部分，输出简短结论 5. 遇到复杂问题时，不要在当前任务里深挖，请列为“建议开分支任务” 输出格式： - 当前阶段目标 - 本次查看的文件 - 已确认结论 - 建议开分支任务的问题 - 下一步建议 要求： - 不要发散到其他阶段 - 结论要适合回填到主线学习笔记4. 开分支任务提示词
这是一个分支任务，只解决一个具体问题，不要发散。 任务名称： 【Q-阶段编号-序号】项目名 - 问题关键词 我要解决的问题是： 在这里写清楚具体问题。 请你： 1. 只围绕这个问题分析 2. 找出相关文件和关键代码 3. 说明问题原因或业务逻辑 4. 如果需要修改或操作，请先说明影响 5. 最后输出可回填到主线任务的总结 最终输出格式： - 问题 - 结论 - 相关文件 - 关键依据 - 可回填到主线的总结 - 后续待确认5. 回填主线提示词
请把下面这个分支任务的结论整理成主线学习笔记，不要复制完整过程，只保留对理解项目有价值的内容。 分支任务名称： 【Q-阶段编号-序号】项目名 - 问题关键词 分支结论： 在这里粘贴分支任务的最终结论。 请按这个格式输出： 1. 问题 2. 结论 3. 相关文件 4. 我对项目新增的理解 5. 后续待确认 要求： - 语言简洁 - 适合放回【学习主线】项目名 - 项目入门 - 不要写排查流水账9. 30 分钟快速实践流程
如果你第一天刚拿到项目，可以按这个 30 分钟流程开始。
0-5 分钟：创建主线任务
新建一个 Codex 任务，命名为：
【学习主线】OrderSystem - 项目入门在任务开头写清楚目标：
这个任务作为我学习 OrderSystem 的主线任务，只记录项目整体理解、学习阶段、阶段总结和待确认问题。遇到具体问题时，我会开分支任务解决，然后把结论回填到这里。5-10 分钟：让 Codex 初扫项目
复制“项目初扫提示词”，让 Codex 先看 README、依赖配置、目录结构和启动脚本。
这一步的目标不是学懂全部代码，而是知道项目大概是什么、从哪里开始。
10-15 分钟：生成学习阶段
复制“生成学习计划提示词”，让 Codex 生成 3 到 5 个阶段。
建议至少包含：
【阶段01】OrderSystem - 项目概览 【阶段02】OrderSystem - 目录结构 【阶段03】OrderSystem - 本地启动 【阶段04】OrderSystem - 核心业务链路把阶段计划保存在主线任务里。
15-25 分钟：推进第一个阶段
从阶段 01 开始，不要跳到复杂业务。
复制“阶段推进提示词”，让 Codex 带你看项目概览。重点确认：
- 项目服务的用户是谁
- 项目解决什么业务问题
- 前端、后端、数据库、外部服务分别在哪里
- 哪些目录最重要
- 哪些内容可以以后再看
如果出现复杂问题，只记录为“建议开分支任务”，不要马上深挖。
例如：
建议开分支任务： 【Q-01-001】OrderSystem - 用户角色说明 【Q-01-002】OrderSystem - 外部支付服务依赖25-30 分钟：整理问题清单和下一步分支任务
最后 5 分钟不要继续看新代码，专门整理主线任务。
你需要得到三样东西：
1. 当前已理解的项目概览 2. 下一阶段要推进什么 3. 需要开哪些分支任务主线里可以这样写：
当前进度： 已完成阶段 01 项目概览。项目主要负责订单创建、支付、库存锁定和订单状态流转。 已确认： 后端服务位于 server 目录。 前端页面位于 web 目录。 本地启动可能依赖 PostgreSQL 和 Redis。 待开分支任务： 【Q-01-001】OrderSystem - 用户角色说明 【Q-03-001】OrderSystem - 本地依赖服务确认 下一步： 推进【阶段02】OrderSystem - 目录结构。最后建议
用 Codex 接手新项目，最重要的不是问得多，而是把问题放对地方。
主线任务负责“我对项目的整体理解”。
分支任务负责“这个具体问题到底怎么回事”。
分支结束后，再把有价值的结论回填主线。
只要坚持这个习惯，你的 Codex 任务不会越聊越乱，项目理解也会越来越清楚。第一天不需要搞懂所有细节，你只需要建立地图、确认启动方式、知道核心目录，并整理出下一批要解决的问题。这样第二天继续学的时候，你不会从零开始。
