第一次让 Codex 接手陌生项目，我不会先让它写代码：7 步完成项目接管

lrt369805210

310人浏览 · 2026-07-31 10:39:37

lrt369805210 · 2026-07-31 10:39:37 发布

摘要： 让 Codex 接手陌生项目，第一步不是写代码。本文给出一套 7 步接管流程，覆盖项目规则、架构、运行链路、验证基线、风险边界和首个任务，文末附可直接复制的提示词。

关键词： Codex、AI 编程、代码库分析、AGENTS.md、项目接管、代码审查、提示词

第一次把一个陌生项目交给 Codex，很多人的第一句话是：

帮我看一下这个项目，然后把这个功能做了。

这句话不能说错，但它把两个本来应该分开的阶段揉在了一起：先理解项目，再修改项目。

项目小、结构简单时，Codex 可能边看边改也能完成；项目一旦包含多个服务、历史兼容逻辑、隐藏的权限边界，或者本地本来就有未提交的改动，直接开写就容易出现另一种结果：代码改了不少，真正的问题却没有解决。

所以我第一次让 Codex 接手陌生项目时，通常不会先让它写代码。我会先让它完成下面 7 件事。做完之后，它不一定理解了项目的每一个角落，但至少已经知道：项目怎么运行、核心流程在哪里、哪些地方不能随便碰，以及接下来应该从哪个小任务开始。

OpenAI 当前给出的 Codex 使用建议里，也反复强调两件事：大型代码库需要更明确的上下文；修改前先映射相关区域，并为每一轮改动安排最小、可验证的检查。Codex 使用建议｜代码库重构实践

先看完整流程

这 7 步不是让 Codex 把所有文件读一遍，而是逐步缩小不确定性：

步骤	要解决的问题	应该拿到的结果
1. 锁定只读范围	当前能不能安全开始	工作区状态、约束文件、不可改内容
2. 读取项目规则	这个仓库要求怎么工作	安装、测试、风格和目录规则
3. 建立架构地图	项目由哪些部分组成	入口、模块、依赖和数据流
4. 找到可运行路径	怎么把项目真正跑起来	环境、命令、端口和外部依赖
5. 追踪一条核心链路	真实业务是怎么流动的	从入口到结果的调用链
6. 建立验证基线	修改前项目本来是什么状态	构建、测试、Lint 与已有失败
7. 划出风险边界并选首个任务	接下来改什么最安全	风险清单、未知项和小步任务

第一步：先锁定只读范围，不要马上改文件

接手陌生项目最先要确认的，不是用了 React 还是 Vue，而是当前工作区是否安全。

如果这是一个 Git 仓库，要先看工作区有没有未提交修改；如果存在用户自己的改动，Codex 应该保留它们，而不是为了“恢复干净环境”直接覆盖。还要查找 AGENTS.md、README、CONTRIBUTING 等规则文件，确认仓库有没有明确的操作边界。

第一次可以直接这样说：

先不要修改任何文件，也不要安装依赖。

请先检查当前项目：
1. 如果是 Git 仓库，报告当前分支和工作区状态；
2. 查找并阅读适用的 AGENTS.md、README、CONTRIBUTING 和开发文档；
3. 识别项目使用的语言、框架、包管理器和主要入口；
4. 标出当前已有修改、敏感配置和不应直接操作的目录；
5. 先给我一份只读检查结果，等待确认后再继续。

这一轮的重点不是“多看几个文件”，而是确认 Codex 有没有站在正确的项目根目录、读到正确的规则，以及是否知道哪些改动不属于它。

第二步：把项目自己的规则读明白

陌生项目最容易踩的坑，往往不在业务代码里，而在仓库约定里。

例如：

项目到底使用 npm、pnpm、yarn、uv 还是其他工具；
测试应该跑全量还是只跑某个子包；
生成文件能不能手动修改；
数据库迁移、接口兼容和版本号有什么要求；
哪些命令需要网络、密钥或者外部服务；
提交前必须执行哪些检查。

AGENTS.md 就适合保存这类长期有效的仓库说明。官方建议把构建和测试命令、评审要求、项目约定放进去，并在更靠近特定目录的位置添加更具体的规则。AGENTS.md 官方说明

如果项目里没有 AGENTS.md，先不要为了形式立刻创建。可以让 Codex 从现有文档和脚本中整理出“已确认规则”和“仍需确认的问题”，等团队确认无误后再固化。

可复制提示词：

请总结这个仓库实际采用的开发规则，不要只复述 README。

至少包含：
- 依赖安装与启动命令；
- 构建、测试、Lint 和格式化命令；
- 目录或模块的特殊约束；
- 生成文件、数据库迁移和敏感配置的处理方式；
- 文档中互相冲突或已经过时的地方。

每条结论请标明依据来自哪个文件；无法确认的内容单独列为“待确认”。

最后一句很重要。它能把“代码里确实存在的事实”和“模型根据惯例做出的猜测”分开。

第三步：建立架构地图，但不要做成目录复读机

很多所谓的“项目分析”，最后只是把目录树重新排版了一遍：src 放源码，components 放组件，utils 放工具函数。这样的信息看起来完整，实际没有回答项目是怎么工作的。

一份有用的架构地图，至少应该说明：

系统有哪些可以独立运行或部署的部分；
每个部分从哪里启动；
核心业务模块如何依赖；
数据存在哪里，又经过哪些边界；
项目依赖了哪些数据库、消息系统或第三方服务；
测试主要覆盖哪些层，明显缺口在哪里。

可以这样要求：

请为这个项目建立一份面向新开发者的架构地图。

不要逐个解释所有目录，重点回答：
- 有哪些运行单元、入口和核心模块；
- 一次典型请求或任务会经过哪些层；
- 数据存储和外部服务在哪里接入；
- 模块之间最重要的依赖关系是什么；
- 哪些文件最能代表项目当前的设计方式。

结论请附关键文件路径，并区分“代码确认”和“推断”。

到这里，Codex 应该能用几段话讲清项目，而不是只给出一张很长的文件清单。

第四步：找到一条真正可运行的路径

读懂结构不等于项目能运行。

这一阶段要把“文档里的启动方式”验证成“当前环境里可执行的启动方式”，包括：

需要什么运行时和版本；
根据哪个锁文件选择包管理器；
环境变量从哪里来，哪些可以使用示例值；
默认端口是否被占用；
是否依赖数据库、浏览器、容器或其他服务；
首次启动会不会写数据库、生成文件或修改本地配置。

这里不建议一上来就让 Codex 自动安装所有东西。先让它列出准备执行的命令，以及哪些操作会联网、写文件或需要凭证。

请找出这个项目的最小可运行路径，暂时不要直接执行安装或迁移。

输出：
1. 推荐的运行时与版本；
2. 依赖安装命令及判断依据；
3. 必需和可选的环境变量；
4. 需要同时启动的服务及端口；
5. 第一次启动可能产生的文件或数据变更；
6. 一套最小启动和健康检查步骤。

把需要联网、凭证或可能影响本地数据的操作单独标出来。

等这份清单合理，再授权它执行。这样即使项目启动失败，排查范围也会小很多。

第五步：选一条核心业务链路，追到底

真正理解一个项目，最有效的方法通常不是继续扩大阅读范围，而是选择一条用户能感知的流程，从头追到尾。

例如：

用户登录后，身份是怎么校验和保存的；
点击“提交”后，请求经过哪些接口和服务；
一条消息从前端发出后，怎样进入队列、数据库和接收端；
一个命令从 CLI 输入后，如何变成后台任务和最终输出。

这一轮需要的不是抽象架构，而是可以核对的调用链：入口文件、关键函数、数据结构、状态变化、错误处理和测试位置。

请选择这个项目最能代表核心价值的一条用户流程，从入口追踪到最终结果。

请按实际执行顺序说明：
- 用户或外部输入从哪里进入；
- 经过哪些组件、接口、服务和数据结构；
- 状态在哪里读取和写入；
- 权限、失败和重试在哪里处理；
- 相关测试覆盖了什么，还缺什么。

请引用关键文件和函数，不要只给概念图。

如果这一条链路都讲不清楚，还不适合立刻让它修改核心功能。

第六步：建立“修改前”的验证基线

这是最容易被省略、也最影响后续判断的一步。

如果修改前已经有 3 个测试失败，修改后仍然是同样的 3 个失败，不能直接说“这次改坏了”；反过来，如果从来没有运行过测试，Codex 说“已经完成”也缺少证据。

基线通常包括：

当前工作区状态；
项目能否构建或启动；
最小相关测试是否通过；
Lint、类型检查和格式检查结果；
已知失败及其错误摘要；
当前环境无法执行的检查，以及原因。

在修改代码前，请建立一份验证基线。

优先运行仓库文档中已有的检查命令；如果全量检查成本过高，先选择最小相关检查并说明原因。

请记录：
- 实际执行的命令；
- 通过和失败的结果；
- 修改前就存在的失败；
- 因环境、权限或外部依赖无法执行的检查；
- 后续修改完成后需要重复执行的验证项。

不要为了让结果变绿而修改测试或忽略错误。

官方的代码库重构建议也是先描述当前行为，再明确结构变化和证明行为稳定的最小检查，而不是把大量修改堆在一个 diff 里统一验证。

第七步：划出风险边界，再选择第一个小任务

完成前六步后，Codex 已经积累了不少信息，但这时仍然不适合直接给它一个“顺便把架构优化一下”的开放任务。

先让它整理风险边界：

身份认证、权限判断和密钥处理；
数据库迁移、删除和不可逆操作；
对外 API、协议和历史兼容；
并发、重试、幂等和消息顺序；
生成代码、第三方同步文件和构建产物；
当前测试没有覆盖的关键路径。

然后从一个边界清楚、结果可验证的小任务开始。比如修一个能够复现的 Bug、补一组缺失测试、修正文档和实现之间的差异，而不是第一次就进行跨模块重构。

最后一轮提示词可以这样写：

基于前面的检查，请输出一份项目接管摘要，包含：

1. 项目目标和主要运行单元；
2. 核心链路和关键文件；
3. 已确认的开发与验证命令；
4. 当前已有失败和环境限制；
5. 高风险区域与不应直接修改的内容；
6. 仍未确认的问题；
7. 三个适合作为首次改动的小任务。

请按“风险最低、验证最清楚、最能帮助理解项目”的顺序推荐，并说明第一项的完成标准。暂时不要实施。

这份摘要比一篇泛泛的“项目介绍”更有用。下一次开始新任务时，它可以直接成为上下文；确认稳定后，也可以把长期有效的部分补进项目文档或 AGENTS.md。

如果不想分七次问，可以直接复制这段

下面是一份合并版提示词。它适合第一次打开陌生仓库时使用：

请先以只读方式接手这个陌生项目，不要修改文件、安装依赖或执行迁移。

请按以下顺序完成检查：

1. 检查 Git 工作区状态，识别现有修改和不可覆盖内容；
2. 阅读适用的 AGENTS.md、README、CONTRIBUTING、开发文档和项目脚本；
3. 建立架构地图，说明运行单元、入口、核心模块、数据流和外部依赖；
4. 找出最小可运行路径，列出环境、安装、启动、端口和健康检查方式；
5. 选择一条核心用户流程，从入口追踪到最终结果，引用关键文件和函数；
6. 根据仓库已有命令设计修改前的验证基线，区分已有失败和环境限制；
7. 标出认证、权限、数据、兼容性和不可逆操作等高风险区域，并推荐三个适合作为首次改动的小任务。

要求：
- 区分代码事实、文档描述和你的推断；
- 每个关键结论附文件路径；
- 不要为了完成分析而修改代码；
- 遇到冲突或缺失信息时明确列出，不要自行补齐；
- 最后输出一份简洁的项目接管摘要，等待我确认后再开始修改。