> ## Documentation Index > Fetch the complete documentation index at: https://adonis-til.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # AI 时代前端工作流：4 阶段防御框架 > 把需求梳理、编码、验证、上线拆成 4 阶段，每个阶段有对应的失败模式和防御手段，附 3 个可复用 skill > 发布于 2026-04-20 · 更新于 2026-04-20 AI 让写代码的速度翻了几倍，但线上 bug 并没有同比例下降。原因不在 AI 写错了代码——大多数时候类型能过、语法能过、跑起来也能过——而在两件事：**进入 AI 之前需求就是模糊的**，**离开 AI 之后验证手段还停在"UI 走查 + 类型检查"**。这篇把前端从需求到上线拆成 4 个阶段，每个阶段点名它最容易踩的失败模式，给出一套可以抄的防御动作。 *** ## 4 阶段 × 对应失败模式 ``` 需求 → 编码 → 验证 → 上线 ↑ ↑ ↑ ↑ 业务 AI 边界 紧急 偏差 幻觉 漏测 回滚 ``` 每一步都有一个**最可能出问题的地方**，用对应的工具或模板拦截。不是每一步都要做得很重，但每一步都要**有意识**——下面按阶段展开。 *** ## 阶段 1 · 需求反向梳理 这是最被忽视的阶段。大多数团队上手就写，结果写到一半发现 PRD 里有坑，回头再沟通成本翻倍。防御动作不是"把 PRD 写得更完整"（这是另一个工种的事），而是**在写代码之前，让 AI 帮你把隐藏问题暴露出来**。 ### 把所有素材一次性喂进去 不要预先筛选。PRD、群聊记录、设计稿截图、现有代码、上次类似需求踩过的坑，全部喂进 AI 的同一个会话。 尤其不要只喂 PRD 正文——**群聊里 PM 的反悔、临时改口、设计师的吐槽，往往才是真实意图**。这些半成品信息单独看是噪声，放在一起才能让 AI 找出 PRD 和现实的差异。 ### 三段式输出 让 AI 按这个顺序产出： 1. **明确需求清单**：每一条附带验收标准和优先级（P0/P1/P2） 2. **隐含假设清单**：PRD 没写但实现时必须确定的事，格式是 "假设是 A，如果是 B 会导致 Y" 3. **歧义冲突清单**：文档自相矛盾、文档和群聊不一致、设计稿和文字不一致 外加一个预估：完成 P0 要几天？哪些假设如果到开发中才发现会导致返工大于半天？ ### 迭代追问 AI 第一轮通常把"假设"写得很笼统。挑最关键的一条让它给 **3 种可能方案 + 实现复杂度差异**，第二轮才能压榨出有用细节。 ### 产出一条对齐消息 把歧义冲突清单整理成**一条消息**发给 PM。比如 "关于订单筛选功能我确认 5 个点" 要比 "这个需求不清楚" 便宜 10 倍。PM 回复后把结论写进 `docs/requirements/<需求名>.md`，这份文档是下一个阶段（写代码）的上下文输入——也是阶段 3 review 时的评分标准。 ### 三个陷阱 * **不要让 AI 自己决定"假设"**，它会默默选一个方案写下去 * **群聊记录超过 500 行**先让 AI 摘要 "关键决策点" 再做输入 * **第一次做某类需求**多问一轮 "这类功能业界常见的坑" > 对应的可复用 skill：`requirement-analysis`。Claude Code / Codex 读取到 PRD、群聊、需求梳理等关键词会自动触发。 *** ## 阶段 2 · 编码 · 三工具分工 Claude Code、Codex CLI、Cursor 各有真正擅长的场景。按任务选工具比"一把锤子砸到底"效率高得多。 ### 三工具的真实强项 | 工具 | 真正擅长 | 别用它干 | | --------------- | ----------------------------------- | -------------------------------- | | **Claude Code** | 多文件改动、长任务、agentic 流程、skill 系统、深度推理 | 简单一行改动（太重）、tab 补全 | | **Codex CLI** | 速度快、单文件编辑、快速问答、跨终端并行多实例 | 跨目录复杂重构（context 没 Claude Code 深） | | **Cursor** | 编辑器内 tab 补全、`Cmd+K` 改写选中代码、可视化 diff | 长链推理任务（Agent 不如 Claude Code 稳） | ### 按任务类型选工具 ``` 任务 → 首选工具 ──────────────────────────────────────────── 需求讨论 / 方案设计 → Claude Code（/brainstorming） 多文件新功能（3+ 文件） → Claude Code Agent 重构一整个模块 → Claude Code Agent 单文件加函数 / 改组件 → Cursor Cmd+K 或 Codex 写一段已想清楚的逻辑 → Cursor Tab 补全 类型定义 / 接口声明 → Cursor Cmd+K 改 CSS / 样式微调 → Cursor Tab 补全 写单测 → Codex（快、便宜） 查 API 用法 → Context7 MCP（任一工具） 查不熟的代码原理 → Claude Code + deepwiki MCP 提交前 review → 和写代码不同的工具（见阶段 3） 紧急小修复 → Cursor Cmd+K 就地改 ``` **核心原则：写代码的工具不等于 review 代码的工具**。这是阶段 3 能发挥的前提，后面会解释为什么。 ### 典型 end-to-end workflow（中型需求） ``` 1. Claude Code 会话 A：/brainstorming + requirement-analysis skill → 产出需求清单 docs/requirements/xxx.md 2. git worktree add ../myapp.wt/xxx -b feat/xxx → 进入独立工作目录 3. Claude Code 会话 B（cd 到 worktree）： 喂需求清单 → Agent 模式多文件编辑 4. Cursor 打开新 worktree： 细节微调 Cmd+K，补样式 Tab 补全，看 HMR 实时效果 5. Codex 新终端（也 cd 到 worktree）： verify-edge-cases skill → 扫边界 code-review-business skill → 核对需求 6. Cursor 里根据 Codex 反馈改 7. Claude Code 会话 C 或 Codex：写单测 → pnpm test 8. git push → 开 PR ``` **会话 A（需求）/ B（编码）/ C（测试）分开**，每个会话上下文干净。用 worktree **物理隔离项目**，用多 session **逻辑隔离任务**——两个维度互相增强。worktree 的具体用法见另一篇 [Git Worktree 实战](../tools/git-worktree.md)。 ### 三个 AI 编码坏习惯 **坏习惯 1：让 AI 改它没读过的文件**。Cursor Agent 最容易犯。AI 基于"它以为的文件内容"写 diff，覆盖你的真实修改。对策：Claude Code 有强制 Read 保护；Cursor 里手动用 `@file` 把目标文件拉进 context 再改。 **坏习惯 2：一次让 AI 生成完整 feature**。"给我写个订单筛选面板，带 API、状态管理、错误处理" 这种一大坨结果看起来对，细节全幻觉。对策：拆成 **类型 -> 接口 -> hook -> 组件** 四步，每步审完再下一步。 **坏习惯 3：信赖 AI 声明的 API**。AI 很擅长编造不存在的函数签名和配置项，尤其是小众库和新版本。对策：用 Context7 MCP，先 `resolve-library-id tanstack-query`，再 `query-docs useSuspenseQuery`——不要让 AI 凭记忆写 API。 *** ## 阶段 3 · 验证 · 双重扫描 大多数团队这个阶段的防线是"UI 走查 + 类型能过" ≈ 90%，线上 bug 恰恰集中在剩下的 10%。补两个轻量防御——**边界 case 扫描** 和 **业务逻辑 review**，不追求完备，但要能命中高危漏洞。 ### 3a · 边界 case 扫描 让 AI **对着具体代码**扫这 7 大类边界。泛泛的清单自己也能背，价值在于把清单和当前实现映射起来。 | 类别 | case | 典型 bug | | ---- | -------------------------------------------------- | -------------------------- | | 空值 | `null` / `undefined` / `""` / `[]` / `0` / `false` | "Cannot read of undefined" | | 极值 | 超长字符串、超大数字、负数、emoji、特殊字符 | 布局溢出、精度丢失、XSS | | 权限 | 未登录、token 过期、权限降级 | 白屏、无限重定向、越权 | | 网络 | 慢网、断网、接口 500、接口超时、接口变慢 | 重复请求、loading 卡住、数据错乱 | | 并发 | 快速双击、切 tab 中途再切、提交中再提交 | 重复订单、race condition | | 状态过渡 | loading -> error、error -> success 反复切 | 旧数据闪现、loading 卡死 | | 多端环境 | 移动端小屏、超长文案、浅深色模式 | 布局破、文案溢出、对比度不足 | ### 3b · 业务逻辑 review 关键：**只从业务逻辑正确性**角度找问题，不关心代码风格、性能、测试。 评分标准就是**阶段 1 产出的需求清单**——逐条核对： * 哪些需求点实现了但**有偏差**？ * 哪些需求点**完全漏了**？ * 哪些地方**多做了需求没说的事**？（也是问题，引入预期外行为） 这是阶段 1 的第二次价值发挥——需求清单同时是开发输入 + review 评分标准。一份文档，两次使用。 ### 双会话互审 ``` 会话 A（写代码）→ 实现 ↓ 提交前 会话 B（不同工具）→ verify-edge-cases（扫边界） ↓ 会话 B → code-review-business（核对需求） ↓ 反馈 会话 A → 改 ↓ 二次 review 会话 B → 确认 ``` 为什么必须是**不同会话甚至不同工具**？ * 会话 A 有上下文偏见——自己写的代码自己读起来"都对" * 会话 B 没有预设，更像真实的 QA * 两个会话不共享 thinking，视角天然不同 在同一个会话里让 AI "再审一遍" 基本没用，它会为之前的实现找理由。 ### 跳过规则 * **必须跑**：新功能 0 到 1 / 核心交易、登录、支付 / 共享组件 / 重构 * **可以跳**：纯文案、纯样式微调、demo 页、README 铁律：涉及**用户数据 + 金钱 + 权限** = 必跑。 ### 单测的定位 AI 写单测没问题，但要加一条纪律：**让 AI 先列"要测的 case 清单"，人审一遍，再写实现**。 ``` 先不要写代码，请基于这个组件，列出你准备写的测试 case 清单（每条一行）。 我确认后你再写实现。 ``` 直接让 AI 写测试，它容易写"测了等于没测"的 case，比如 `render()` 不报错。先列清单能看出它有没有覆盖逻辑分支。 *** ## 阶段 4 · 上线（待续） 这部分留给后续文章。几条要点先标记出来： * **Feature flag**：大功能用 flag 包住，出问题直接关闭不走回滚 * **关键路径埋点 + 报警**：登录、下单、支付埋错误日志（Sentry 或自建），线上出问题比 PM 先知道 * **"能在 5 分钟内止血"才敢紧急上线**：没 flag 没监控的紧急上线就是裸奔 这几条展开需要单独讲前端 feature flag 的轻量实现、React 里最佳落地姿势、错误监控的上报策略——下一篇补。 *** ## 落地：三个 Skill 上面的流程里提到的三个 skill 已经落地到本地，**单一 master + symlink** 模式让 Claude Code 和 Codex 共用一份源文件： ``` ~/.agents/skills/ (master) ├── requirement-analysis/SKILL.md ├── verify-edge-cases/SKILL.md └── code-review-business/SKILL.md ~/.claude/skills/ → symlink 到 master ~/.codex/skills/ → symlink 到 master ``` 改一次源文件，两个工具同时生效。Cursor 不识别 skills，可以用 `@~/.agents/skills//SKILL.md` 引用同一份。 | Skill | 触发关键词 | 阶段 | | ---------------------- | ------------------------------ | -- | | `requirement-analysis` | "梳理需求"、"PRD 不清楚"、"需求太模糊" | 1 | | `verify-edge-cases` | "检查边界"、"扫边界"、"edge case check" | 3a | | `code-review-business` | "业务 review"、"需求核对"、"对一下需求" | 3b | skill 会被 agent **按 description 自动匹配触发**，不需要手动 `/command`。一个 skill 的价值不是写 prompt 模板，而是把"应该怎么想这个问题"编码成 agent 的默认动作。 ### 为什么阶段 2 的"工具分工"不做成 Skill skill 适合"给数据、出结果"的流程化任务。阶段 2 的分工是**决策框架**，价值在脑子里——让 agent 按它执行反而奇怪。所以这部分保持成文档。 *** ## 反常识总结 * **AI 写的代码多数是对的**，但"需求理解偏差 + 边界漏测"这两个阶段的漏洞会被放大——速度起飞的同时，漏洞上线的速度也起飞 * **群聊记录比 PRD 更有价值**。反悔、改口、吐槽里藏着真实意图，不要只喂正文 * **写代码的工具不等于 review 代码的工具**。同一个会话的 "再审一遍" 基本没用 * **需求清单是一份文档、两次使用**：开发的输入 + review 的评分标准 * **worktree 是物理隔离，session 是逻辑隔离**，两者合用比单用任何一个都强 * **AI 写单测前先列 case 清单**，否则容易产出 `render()` 不报错这种没意义的测试 * **涉及用户数据、金钱、权限就必须过验证阶段**，其余场景可以按需跳过 * **Skill 不是 prompt 模板，是把"应该怎么想"编码成 agent 默认动作**——所以并非所有流程都值得封装成 skill