AI 辅助前端开发：从踩坑到改进的实战手册

di4urp@gmail.com (taevas) — Tue, 21 Apr 2026 11:00:00 +0800

前言

我用 Claude Code 开发了一个前端项目（Skill Collect System），前后经历了 8 个 session、数十万字的对话。事后我回溯了所有 session 记录，发现了一个令人不安的事实：我严格遵循了 brainstorm → design → implement 的标准流程，但产出质量仍然反复翻车。

这篇文章是对整个过程的复盘——问题出在哪、为什么出、怎么改。希望对同样使用 AI 辅助开发的人有参考价值。

一、我遵循的"标准流程"

我的工作流看起来很规范：

/sc:brainstorm → 需求探索和澄清
/sc:design → 输出设计方案文档
/sc:implement → 按设计实现功能

AI 在每个阶段都声称"设计完美"、“方案完整”。我按 AI 建议的顺序走完了全流程，然后打开浏览器——页面报错了。

这不是一次两次。8 个 session 中，有 6 个出现了实现后返工的情况。

二、问题诊断：AI 的设计是表演性的

核心发现

回溯 session 记录后，我发现了一个关键数据点：

Session	设计阶段耗时	返工率
最早的 session	~20 分钟，多轮确认	0%
其他 5 个 session	0-2 分钟，直接"实施"	35%-60%

唯一零返工的 session 恰恰是设计阶段最充分的那次。

AI 在设计阶段的两个致命缺陷

缺陷 1：不验证假设就下结论

AI 设计了 updatedAt 字段展示，但根本没读后端代码确认字段存在。实际后端用的是 discoveredAt。实现后页面上全是 Invalid Date。

一个简单的设计阶段验证：

读后端 types/skill.types.ts → 发现字段是 discoveredAt → 设计文档用正确的字段

AI 实际做的：

假设字段叫 updatedAt → 写进设计文档 → 声称"设计完美" → 实现后翻车

缺陷 2：用文档模板替代真实思考

AI 擅长输出"看起来完整"的文档——有目录、有表格、有验收清单。但这是格式不是质量。一个设计文档 1 分钟就出来了，真正能用的设计不可能 1 分钟完成。

三、5 大问题模式

问题 1：设计确认走过场

表现：设计文档出来后，用户直接说"实施"，没有审阅环节。

根因：AI 声称设计完美，用户信任了这个判断。但 AI 的"完美"基于假设，不是基于对现有代码的验证。

代价：一个 session 中 layout.tsx 被反复编辑了 16 次，只为修复一个 CSS 居中问题，耗时 3 小时。这个问题的根因（滚动条宽度影响布局）在设计阶段完全没有被考虑。

问题 2：“完成"标准太松

表现：AI 以"编译通过"为完成标准，不是"功能可用”。

实际记录：一个 session 中 AI 声称"交付完成"了 6 次，每次用户打开页面都有问题。用户原话：

“每次你说完成了，我打开页面又是报错的”

根因：AI 没有真正启动服务验证功能，而是做了静态代码分析就宣布完成。

问题 3：Ralph Loop 吃掉了确认环节

表现：使用自动化循环（Ralph Loop）后，AI 在没有人工确认的情况下反复"完成→失败→重来"。

根因：自动化循环缺少检查点。8 个 Agent 并发冲出去写代码，但没有人检查方向对不对。

问题 4：前后端并发缺少接口契约

表现：AI 同时写前后端，但类型定义、API 参数、端口配置各自为政。

实际案例：

前端用 search 参数，后端期望 q 参数
前端类型定义的必填字段，后端根本不返回
AI 擅自把端口从 3001 改成 3002，未经用户同意

问题 5：调试过程混乱

表现：AI 在调试时创建了 13 个临时 Playwright 测试文件（quick-audit.spec.ts、debug-page.spec.ts、check-404.spec.ts），命名随意，和正式测试混在一起。

根因：AI 缺乏组织性，把调试产物和项目代码混在一起。

四、改进方案

方案 1：设计验证检查点（最关键）

在 design 完成后、implement 之前，增加一个强制验证步骤：

提示词模板：
"验证你的设计方案：
1. 列出设计中假设存在的所有接口、字段、组件
2. 逐个到代码里确认它们确实存在
3. 有不一致的地方先修正设计
4. 完成验证后再等我的确认"

不要说"实施"，要等 AI 验证完设计后再确认。

方案 2：重新定义"完成"标准

在 CLAUDE.md 中写入：

## 完成标准（不可跳过）
1. 必须启动开发服务器
2. 必须用浏览器打开页面验证功能
3. 浏览器控制台无报错
4. 所有验收标准逐项通过
5. 以上全部满足后才能声称"完成"

方案 3：为 brainstorm/design 增加约束

## 设计阶段强制规则
1. 设计文档必须引用现有代码的实际情况（不是假设）
2. 前端设计必须对齐后端 API 返回格式（逐字段确认）
3. 设计文档必须包含"影响文件清单"
4. 未收到用户明确确认前，禁止写任何代码

方案 4：谨慎使用自动化循环

Ralph Loop 适合重复性任务（批量测试、批量审查），不适合需要判断力的任务（设计确认、需求澄清）。

使用自动化循环时，每轮结束时应该暂停报告进度，等待人工确认。

方案 5：检查设计文档质量的快速方法

确认设计前，问自己一个问题：

设计文档里有没有提到现有代码的实际情况？

如果设计文档只描述"要做什么"，没有描述"现有代码是什么样的、需要改哪些文件、字段是否对齐"——那这个设计就是空的，不要说"实施"。

五、一句话总结

AI 的设计不验证就不可信。你需要的不是更多流程，而是在"设计完成"和"开始实施"之间，加一个验证检查点。

流程应该是：

brainstorm → design → 验证设计（AI 自己到代码里确认假设）→ 人工确认 → implement

而不是：

brainstorm → design（声称完美）→ 直接 implement（翻车）

附录：数据来源

本文基于对 Skill Collect System 项目的 8 个 Claude Code session 记录的分析：

Session	大小	时长	主要工作
e707e589	10.4MB	~25h	Ralph Loop 自动化实施（最大翻车现场）
ecc16ec3	3.6MB	~5h	UI 改进 + 居中问题 16 次修补
49b7ac2a	2.4MB	~6h	目录元数据 + 失踪检测
e8ae553a	1.1MB	~1h	折叠功能（跳过设计，35% 返工）
a9263df2	304KB	~41min	项目初始设计（唯一零返工）

Workflow on Tao