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

上一篇我把 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 - 图压工具。同事安利给我的用过后真的觉得太香了支持批量压缩、调整压缩百分比最关键的是它是离线程序下载到本地就能反复用。我平时做自媒体和写前端时经常用到再也不用去网上找在线压缩工具了。它也带在线压缩功能很方便。