这篇文档不讲太多概念重点是给你一套马上能用的做法用 Codex 学项目时不要把所有问题都塞进一个任务里。正确做法是一个“主线任务”负责整体学习多个“分支任务”负责具体问题最后把分支结论回填到主线里。1. 为什么接手新项目容易混乱刚接手一个陌生项目时最容易遇到这些问题README 写得不完整不知道项目到底怎么启动。目录很多不知道哪些文件重要。配置文件一堆不知道哪些影响本地环境。业务链路很长看着看着就迷路。一个报错查半天查完又忘了最开始想学什么。和 Codex 聊太久后任务里混杂了启动、业务、配置、报错、接口、数据库等内容后面很难翻。新手常见错误是开一个 Codex 任务然后一直问所有问题。刚开始还可以后面任务会变得又长又乱。Codex 也会被大量上下文拖住你自己也很难从里面提炼学习笔记。所以接手项目时要把“学习”和“排查”分开。2. 核心方法主线任务 分支任务推荐把 Codex 任务分成两类主线任务主线任务只负责理解整个项目。它像你的项目学习笔记记录这些内容项目是做什么的技术栈是什么怎么启动目录结构核心模块当前学习进度阶段总结待确认问题清单主线任务不要深入排查复杂问题。比如本地启动报错、某个接口逻辑很绕、某个配置含义不清楚这些都应该拆出去。主线任务命名【学习主线】项目名 - 项目入门示例【学习主线】OrderSystem - 项目入门分支任务分支任务只解决一个具体问题。它像专项排查记录目标要小边界要清楚。适合开分支任务的问题包括某个模块的作用某条业务链路某个启动报错某个配置文件某个接口逻辑某个数据库表和代码的关系某个测试失败原因分支任务命名【Q-阶段编号-序号】项目名 - 问题关键词示例【Q-03-001】OrderSystem - 启动报错排查 【Q-04-002】OrderSystem - 下单链路分析为什么要这样分这样做有三个好处。第一主线不会乱。主线任务始终只记录项目学习进度后面回看很清楚。第二分支更聚焦。每个分支只解决一个问题Codex 不容易发散你也更容易判断问题是否解决。第三方便沉淀。分支任务结束后把结论整理成几段话回填到主线主线就会越来越像一份完整的项目入门文档。3. 第一步让 Codex 快速扫项目新手第一天不要一上来就读业务代码也不要直接问“这个项目怎么回事”。更好的做法是让 Codex 先扫一遍项目入口信息。你可以让 Codex 先看READMEpackage.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 任务不会越聊越乱项目理解也会越来越清楚。第一天不需要搞懂所有细节你只需要建立地图、确认启动方式、知道核心目录并整理出下一批要解决的问题。这样第二天继续学的时候你不会从零开始。
