让 Codex 接手陌生前端项目，我会先确认这 5 个入口

孙梦⁶⁶⁶₆₆₆666

636人浏览 · 2026-08-05 17:59:53

孙梦⁶⁶⁶₆₆₆666 · 2026-08-05 17:59:53 发布

上一篇我把 Codex 前端任务整理成了一条闭环：先分流任务，再定义结果，然后理解项目、制定计划、小步修改、分层验收。

进入第 2 周，我想从闭环中最容易被低估的一步开始：

Codex 第一次接触一个陌生前端项目时，到底应该先看什么？

很多人的第一反应是打开 src，再去找名称最像需求的页面。比如需求里写“修改用户列表”，就直接搜索 user、list 或“用户管理”，找到一个 .vue 文件便开始读。

这种方式偶尔很快，风险也很明显。

搜索命中的可能是旧页面、移动端副本、测试样例、废弃路由，甚至只是一个同名组件。即使页面找对了，项目真正的约束也可能藏在更外层：脚本决定怎样启动，配置决定怎样解析路径，入口决定插件和状态怎样装配，路由决定页面怎样进入，项目规则决定哪些现成封装不能绕过。

所以我现在不会让 Codex 一上来就扎进业务代码。我会先让它确认 5 个入口：

项目边界；
项目规则；
执行入口；
应用启动入口；
当前业务入口。

这 5 个入口确认以后，业务代码才有坐标。

为什么“先找到页面”仍然可能读错项目

陌生项目里的错误，常常不是语法错误，而是上下文定位错误。

比如一个仓库里同时存在：

管理后台；
H5 页面；
公共组件包；
接口类型包；
旧版管理后台；
演示或测试应用。

需求只写“修改订单详情页”。如果不先确认项目边界，Codex 可能找到两个都叫 OrderDetail 的组件，并根据文件内容完整程度选择其中一个。它的代码分析可能没有问题，修改对象却从一开始就错了。

再比如，package.json 中存在 dev、dev:test 和 dev:admin 三个脚本，分别加载不同环境和入口。只看组件文件，很难知道当前任务实际运行在哪一套配置下。

这就是我不把“找到相关文件”当作接手完成的原因。

我更关心的是一条证据链：

仓库中的哪个应用 → 受哪些规则约束 → 怎样启动 → 从哪个入口装配 → 用户怎样进入目标功能

只有这条链能够连起来，我才认为 Codex 找到了真正的修改现场。

入口一：先确认项目边界，不把仓库根目录当成应用根目录

第一个入口不是某个源文件，而是项目边界。

我会先让 Codex 回答：

当前工作区是单应用还是多应用仓库？
前端应用根目录在哪里？
当前任务属于哪个应用或包？
这个应用依赖哪些本地公共包？
是否存在旧版、移动端、示例或构建产物目录？

这里不能只看目录名称，还要结合依赖清单、工作区配置和脚本来判断。

例如下面只是一个演示结构：

repository/
├─ apps/
│  ├─ admin-web/
│  └─ mobile-web/
├─ packages/
│  ├─ ui/
│  └─ api-types/
├─ legacy/
├─ package.json
└─ workspace-config

如果任务是管理后台列表，最小范围可能是 apps/admin-web，同时需要读取它依赖的 packages/ui 和 packages/api-types。mobile-web 与 legacy 可能存在同名页面，但默认不应进入修改范围。

项目边界的产出不需要很长，一张表就够：

位置	角色	与当前任务的关系
管理后台应用	目标应用	允许读取，按任务范围修改
公共 UI 包	本地依赖	读取用法，修改需单独确认
接口类型包	契约来源	读取，是否修改取决于接口契约
移动端应用	其他端	默认不修改
旧版目录	历史实现	只能参考，不能默认视为标准

这里最容易出现的误判

最常见的是把目录名当成事实。例如看到 common 就认定它是公共标准，看到 legacy 就认定它完全无效，看到 admin 就认定它一定是当前生产应用。

目录名只能提供线索。真正的证据来自依赖关系、脚本、配置、入口引用以及当前任务明确指定的范围。

如果一个仓库存在多个候选应用，而需求没有说明目标，我会让 Codex 暂停并列出候选，不允许它自行选择一个开始修改。

入口二：再确认项目规则，知道哪些做法不是自由选择

项目边界确定后，我会先找规则，而不是先找组件。

规则可能来自：

仓库或目录中的 AGENTS.md；
项目说明和开发文档；
包管理与脚本约定；
格式、类型和测试配置；
当前目录下更具体的开发规范；
明确启用的本地 Skill。

这一步要解决的不是“项目偏好什么代码风格”，而是识别哪些决定已经由项目作出。

例如：

必须使用已有请求封装，不能在页面里直接创建请求实例；
弹窗统一经过项目组件，不直接使用底层组件；
类型检查必须使用项目脚本，而不是自己拼一条命令；
当前目录要求使用某种状态组织方式；
提交前必须运行哪些检查；
哪些文件或生成代码不能直接编辑。

我会要求 Codex 把规则分成三类：

类型	含义	处理方式
硬规则	明确要求或禁止	必须执行，冲突时暂停
项目模式	从稳定实现中归纳	需要给出参考位置
当前任务选择	本次才需要决定	不能伪装成项目规则

这能避免一种常见问题：Codex 从某个页面里看到一种写法，就把它提升成全项目规范。

规则不是越多越好

接手阶段只需要提取与当前任务相关的规则。

修改列表筛选时，接口封装、状态管理、分页和验证方式很重要；与图标素材、营销页面布局有关的规则可能暂时不用进入上下文。把所有规范一次性堆给 Codex，反而会让真正的硬约束失去优先级。

规则入口完成后，我要看到的不是一份“项目很规范”的评价，而是一张可以执行的短清单：本次必须遵守什么、证据在哪里、存在什么冲突。

入口三：确认执行入口，知道项目怎样被启动和检查

我把 package.json 中的脚本、包管理信息和相关配置称为执行入口。

在读业务代码之前，至少要知道：

使用什么包管理方式；
当前应用怎样启动；
构建、类型检查、测试和代码检查怎样运行；
不同脚本是否对应不同环境或子应用；
是否存在自动生成、预处理或环境注入步骤；
哪些检查当前环境能够实际执行。

这一步决定后面能拿到什么证据。

如果仓库已经提供 typecheck、test 和 build 等脚本，Codex 应优先理解并复用它们，而不是看到框架后自己猜命令。脚本名称也不能只按字面解释，需要查看它实际执行了什么、作用在哪个工作区。

例如同样叫 build，在多应用仓库中可能只构建默认应用；同样叫 test，可能只运行单元测试，不覆盖页面交互。脚本通过能证明什么、不能证明什么，都应该在接手阶段说明。

我会记录一张验证能力表

检查	实际脚本或入口	能证明什么	不能证明什么
类型检查	以仓库实际脚本为准	类型关系和部分引用正确	真实交互符合需求
单元测试	以仓库实际范围为准	已覆盖逻辑仍成立	未覆盖页面路径正常
构建	以目标应用脚本为准	项目可以完成构建流程	运行时数据和体验正确
页面验证	目标应用与路由	用户路径和页面状态	所有隐藏分支都无问题

如果项目没有某项检查，我会把它标记为“当前不存在”或“无法运行”，不会凭空补一句“测试通过”。

执行入口的意义，不只是以后方便运行命令，而是从任务一开始就知道交付证据的上限。

入口四：沿应用启动入口，确认框架能力怎样被项目装配

项目边界和执行方式明确后，我才会沿启动链读代码。

对于常见前端应用，启动链可能经过：

HTML 容器 → 脚本入口 → 根组件 → 路由 → 状态管理 → 插件与全局能力

具体文件名和顺序取决于项目，不能按框架习惯直接假定。

我会要求 Codex 确认：

真正的脚本入口由哪里指定；
根组件承担什么职责；
路由、状态、权限、国际化等能力在哪里注册；
全局组件、指令或方法怎样挂载；
环境变量和别名怎样影响模块引用；
是否存在按环境切换的入口或插件。

这一步常常能解释“为什么一个页面不能照通用写法修改”。

例如页面里看不到错误提示的导入，不代表它可以随意换一种提示方式，项目可能在启动阶段注入了统一能力；路由文件里看不到全部页面，也不代表页面没有注册，项目可能使用模块扫描或生成路由；状态模块没有在目标页面直接初始化，也可能在应用入口统一装配。

启动入口的完成证据

我会让 Codex 用一条简短链路说明，而不是贴大段代码：

启动脚本从哪里进入
→ 创建应用
→ 注册哪些关键能力
→ 挂载根组件
→ 路由如何连接业务页面

每个箭头后面应有具体文件或配置依据。

如果入口存在多个分支，必须说明当前任务使用哪一支，以及这个判断来自脚本、环境配置还是路由条件。

入口五：最后定位当前业务入口，而不是只找到同名页面

前四个入口建立了项目坐标，第五个入口才是当前业务功能。

我不会只问“页面文件在哪”，而会要求沿用户动作找入口：

用户通过哪个菜单、路由或父页面进入；
路由参数、查询参数或权限信息从哪里来；
目标页面是否只是容器，主要逻辑是否在子组件或组合函数中；
页面调用哪个状态模块、请求层和公共组件；
离开、刷新、关闭重开时状态怎样变化；
是否存在另一个同名入口服务于不同角色或终端。

例如需求是“修改编辑弹窗”，仅找到 EditDialog.vue 仍然不够。至少要知道：

哪个页面打开它 → 传入什么标识 → 它怎样取得数据 → 保存后通知谁 → 谁负责刷新列表 → 关闭时由谁清理状态

这条链决定了修改应落在弹窗内部、页面容器、状态模块，还是接口转换层。

搜索结果只是候选，不是入口证据

名称搜索适合发现候选文件，但需要用引用关系、路由配置和运行路径确认。

如果一个组件没有当前入口引用，或者只出现在故事、测试和旧目录中，就不能因为实现完整而把它视为目标文件。

业务入口确认后，我才允许 Codex 输出预计修改范围。此时的范围应该能解释每一个文件为什么与用户路径有关。

我会要求 Codex 交付一份“接手结论”，而不是代码

5 个入口读完后，第一次交付不应是修改后的页面，而是一份简短接手结论：

# 陌生前端项目接手结论

## 1. 项目边界
- 目标应用：
- 相关本地包：
- 默认不进入范围的目录：
- 判断依据：

## 2. 当前任务规则
- 必须遵守：
- 可参考模式：
- 冲突或待确认：
- 规则来源：

## 3. 执行与验证入口
- 启动方式：
- 类型、测试、构建等检查：
- 当前无法运行或无法证明的事项：

## 4. 应用启动链
- 入口文件：
- 关键装配：
- 路由或环境分支：

## 5. 业务入口
- 用户进入路径：
- 页面与组件链：
- 状态与请求链：
- 预计影响范围：

## 6. 结论
- 已确认事实：
- 合理推断：
- 需要人决定：
- 是否可以进入修改计划：是 / 否

这份结论的价值是把“我已经读过项目”变成可检查产物。

如果其中仍然存在会改变实现方向的未知项，下一步应是补查或确认，而不是让 Codex 一边猜一边改。

哪些信号出现时，我会要求立即暂停

接手陌生项目时，以下情况不适合继续向代码修改推进：

存在多个候选应用，无法确定目标；
项目规则与稳定代码模式明显冲突；
启动脚本或环境入口无法对应到目标页面；
找到多个同名页面，却无法确认当前路由使用哪个；
目标功能实际依赖计划外公共包；
关键接口、权限或状态归属只有推断，没有证据；
仓库检查无法运行，且没有替代验证方式；
需求描述与当前真实行为不一致。

暂停不是接手失败，而是说明阅读已经发现一个需要人处理的分叉。

最危险的不是项目复杂，而是项目仍有多个合理解释，Codex 却选了其中一个继续生成完整代码。

不同规模的任务，5 个入口不需要读到同样深

这套顺序不意味着每次都要全面审计整个仓库。

局部低风险任务

确认目标应用、适用规则、可运行检查和直接业务入口即可。启动链可以只查到与当前能力有关的位置。

标准业务功能

需要完整确认 5 个入口，尤其是状态、请求、路由和生命周期的连接关系。

公共能力或高风险修改

除了 5 个入口，还要扩大引用范围，补充兼容策略、回退方式和多个应用的验证路径。

阅读深度由风险决定，但阅读顺序不应该倒过来。先有项目坐标，再进入具体实现，通常比从一个组件向外猜整个系统更可靠。

写在最后

让 Codex 接手陌生前端项目，我不会把“找到相关页面”当作理解完成。

我会先确认：

当前任务到底属于仓库中的哪个项目；
这个范围受哪些规则约束；
项目怎样启动和完成检查；
应用怎样装配路由、状态和全局能力；
用户怎样真正进入当前业务功能。

这 5 个入口连起来以后，页面、组件、状态和接口才不再是一组孤立文件，而是一条有来源、有责任边界、也有验证出口的执行路径。

下一篇我会进一步把这套接手顺序落到具体操作：怎样只用目录、配置和入口文件，先建立一张“最小项目地图”。重点不是罗列文件，而是把每个目录和配置结论都连接到真实启动链与业务入口。

本系列持续更新。第 2 周接下来会沿这张地图继续深入项目规则、调用链、代码差异和验证证据，逐步走完一次完整的 Codex 前端任务闭环。

每日好工具推荐：

在这里推荐一款超好用的图片压缩工具——“图压”在线图片压缩｜免费压缩 JPG、PNG、WebP - 图压工具。同事安利给我的，用过后真的觉得太香了！支持批量压缩、调整压缩百分比，最关键的是它是离线程序，下载到本地就能反复用。我平时做自媒体和写前端时经常用到，再也不用去网上找在线压缩工具了。它也带在线压缩功能，很方便。