用 Codex 重做前端，先列清楚页面和交易流程 - AIPlan

重做前端最贵的错误是让模型一边想结构一边写代码。正确的顺序是先把页面清单、接口清单和 3 条关键交易流程写成一份可用文件，再让它按文件实现。截至 2026 年 10 月 18 日核对，这套拆法在 20 个页面左右的站点上最划算。 页面清单要写到路由级 “重做首页和商品页”这种描述会让输出漂移。页面清单要精确到路由： / 首页 /products 列表，支持分页和筛选 /products/:slug 详情，含价格、库存、加购按钮 /cart 购物车 /checkout 结算，含登录态判断 /orders/:id 订单详情，含状态流转 每个页面再补一行状态：是否有加载态、空态、错误态。这 3 个状态是前端重做里返工最多的部分，占位写得越早越省事。一个列表页至少 3 种状态，20 个页面就是 60 个分支，靠模型临场发挥必然会漏。 接口清单比组件清单优先 组件结构可以后改，接口契约改起来牵连大。先把接口列出来： 用途 方法 路径 关键字段 商品列表 GET /api/v1/products items、total、page 商品详情 GET /api/v1/products/:slug price、stock、skus 下单 POST /api/v1/orders items、coupon、email 订单查询 GET /api/v1/orders/:id status、paid_at 字段名写全，包括嵌套层级。模型最常犯的错是猜字段名，product.price 和 product.skus[0].price 差一个层级就会让价格显示成 undefined。 三条交易流程要先画出来 电商类站点至少三条流程值得单独写： • 未登录用户从详情页到结算页，中途要跳登录再回来 • 已登录用户用优惠券下单，金额要实时变 • 支付完成后回到订单页，状态从待支付变成已支付 每条流程列出 5 到 8 个步骤，标明哪一步会调用哪个接口、哪一步可能失败。第 1 条里的“跳登录再回来”是最容易漏的，很多重做版在登录后把用户丢回首页，购物车还在但流程断了。 需求文档该怎么写到这个粒度，可以看 给 ChatGPT 写需求文档的可用结构。 先定 5 条视觉规则，再让它写组件 不定规则就让它写，20 个页面会长出 20 种按钮。规则要具体到数值： 间距：4 / 8 / 12 / 16 / 24 / 32 / 48，只用这 7 档 圆角：按钮 6px，卡片 10px，输入框 6px 字号：12 / 14 / 16 / 20 / 28 / 36 行高：正文 1.6，标题 1.3 颜色：主色 1 个，中性色 6 档，语义色 3 个（成功/警告/错误） 7 档间距、3 种圆角、6 档字号，这些数字放进一份 tokens 文件，后面所有组件都引用它。模型对“统一的视觉语言”这种描述没有具体响应，对具体像素值响应很准。 替换而不是并存 重做前端最容易留下的债是新旧两套组件同时存在。旧按钮在 A 页面还在用，新按钮在 B 页面已经上了。三个月后没人说得清哪个是标准。 处理方式是硬替换：新组件放到目标位置，旧组件文件删除，同时把所有 import 改掉。让 Codex 做这件事时，任务描述要写明“删掉旧文件，不要保留兼容层”。保留兼容层听起来稳妥，实际是让两套实现长期共存。 暗色适配要一开始就做 后补暗色主题的代价是每个颜色都要回头改一遍。开始就做的话，只需要一条规则：所有颜色走 CSS 变量，不在组件里写死十六进制值。 :root { --bg: #ffffff; --fg: #161616; --muted: #666666; } @media (prefers-color-scheme: dark) { :root { --bg: #111111; --fg: #eeeeee; --muted: #aaaaaa; } } 三段代码解决 90% 的暗色问题。剩下的 10% 是图片、阴影和半透明遮罩，这些要在组件清单里标出来单独处理。一张白底商品图放在深色背景上会很刺眼，常规做法是给图片容器加一层浅色底或者做圆角裁切。 浏览器验收的 6 个检查点 写完不等于对。前端验收有个最小集合，6 项都过才算能用： • 桌面 1440 宽下没有横向滚动条 • 手机 390 宽下按钮可点，不重叠 • 所有表单提交后能看到结果，成功和失败各测一次 • 刷新页面后登录态还在 • 图片加载失败时有占位，不是破图图标 • 网络慢的时候有加载态，不是白屏 第 5 和第 6 条最常被跳过。让 Codex 实现时在任务描述里点名这两条，它通常会补上 onerror 和骨架屏。 让它在真实浏览器里跑 Codex 支持浏览器调试。桌面版可以在 Settings > Browser 里打开 Developer mode 下的 Enable full CDP access，它会获得对 Chrome DevTools Protocol 的访问，能看控制台输出、网络请求、页面状态和 JavaScript 性能。 这个开关默认关闭，打开时会提示风险：完整的 CDP 访问能检查和控制浏览器的敏感内部数据。官方说的是，用全量 CDP 检查网站前它会单独请求批准。企业环境的 Codex 管理员可以通过托管配置把 browser_use_full_cdp_access 设成 false 关掉它。 实际用法：让它打开页面、截一张图、读出控制台的 3 条报错，比你在聊天里描述报错省 5 分钟。用完把开关关掉。 什么时候该拆成两轮 一个页面改超过 300 行，或者一次涉及 5 个以上文件，建议拆两轮。第一轮只做结构和数据流，第二轮做样式和状态。 拆的好处是每轮都能验收。第一轮验收看数据对不对、跳转通不通；第二轮看视觉和响应式。合成一轮的话，出了问题你要同时怀疑数据层和表现层。 一次真实的时间估算 20 个页面、8 个接口、3 条流程的站点，按这个顺序做： • 写文档：2 小时 • 搭骨架和 tokens：3 小时 • 页面实现：每页 30 到 60 分钟，合计 12 小时左右 • 三条流程联调：4 小时 • 验收修整：3 小时 合计 24 小时上下，分 5 到 6 个工作段完成。每段结束打一个 Git 检查点，官方快速上手文档里也建议在任务前后建检查点。 Codex 的用量消耗在 20 个页面这种量级上主要来自读取阶段，一次读下来的上下文不小。如果一周要做 3 个以上这样的项目，Plus 的 $20 会吃紧，$20 折算约 ¥133.80，¥115.50 的 Plus 月卡 对应同一档。真到了每周都要重做前端的强度，才值得考虑 Pro，档位差异可以看 ChatGPT Plus 和 Pro 怎么选。 把页面清单和接口表先写进一个文件，再让 Codex 开工。这 2 小时是整个项目里回报最高的 2 小时。 参考资料资料核对日期：2026-10-17 • Codex CLI • Code review 延伸阅读• 用 ChatGPT 整理需求文档：先说清行为，再写功能列表 • 用 Codex 重构代码：替换旧实现，也要清理旧路径 • 让 Codex 写测试：先问这条测试能发现什么错误