Ai-Engineering on Tao

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	项目初始设计（唯一零返工）

提示词优化迭代系统：多 Agent 协作的设计链路

di4urp@gmail.com (taevas) — Wed, 15 Apr 2026 20:17:10 +0800

系统概述

这是一个基于多 Agent 协作的提示词自动优化系统，通过迭代对比生成结果与参考标准，持续改进提示词质量，直至达到预设的一致性阈值。

核心流程图

flowchart TD Start([开始]) --> A[主 Agent: 准备初始提示词] A --> B[启动 Subagent 1
任务: 使用提示词分析目标网站] B --> C{Subagent 1 生成文档} C --> D[输出: test/DESIGN.md] D --> E[主 Agent: 初步审查结果] E --> F[启动 Subagent 2
任务: 对比两个 DESIGN.md] F --> G[Subagent 2 执行对比] G --> H{读取参考文档} H --> I[collections/nike/DESIGN.md
（参考标准）] G --> J{读取测试文档} J --> K[test/DESIGN.md
（待评估）] I & K --> L[Subagent 2: 一致性分析] L --> M[生成评估报告] M --> N[输出: 一致性打分] M --> O[输出: 修改建议] N --> P{一致性评分} P -->|满意| Done([完成 - 迭代结束]) P -->|需改进| Q[主 Agent: 根据建议优化提示词] O --> Q Q --> R[记录提示词版本] R --> S[版本历史库
V1, V2, V3...] S --> B style Start fill:#e1f5e1 style Done fill:#ffe1e1 style B fill:#e3f2fd style F fill:#e3f2fd style L fill:#fff3e0 style Q fill:#f3e5f5 style S fill:#fce4ec

核心设计链路

第一阶段：初始化

角色： 主 Agent

任务：

加载初始提示词模板
配置目标网站 URL：https://www.nike.com/
设置参考标准文档路径：collections/nike/DESIGN.md
初始化版本历史库（空）
设置一致性评分阈值（建议：85/100）

输出：

初始提示词 V0
迭代计数器 = 0

第二阶段：生成循环（迭代核心）

步骤 2.1：启动生成 Subagent

角色： Subagent 1

任务：

接收当前版本的提示词
访问目标网站 https://www.nike.com/
使用提示词分析网站内容
生成品牌设计文档

输出： test/DESIGN.md

关键技术点：

网站内容抓取与解析
基于提示词的结构化生成
Markdown 格式输出

步骤 2.2：主 Agent 初步审查

角色： 主 Agent

任务：

读取 test/DESIGN.md
检查文档完整性（必需章节：品牌概述、设计规范、视觉元素等）
快速格式验证
记录迭代元数据（时间戳、提示词版本）

步骤 2.3：启动对比 Subagent

角色： Subagent 2

任务：

读取参考文档：collections/nike/DESIGN.md
读取测试文档：test/DESIGN.md
执行深度一致性分析

分析维度：

维度	权重	评估内容
结构完整性	20%	章节覆盖、层级结构
内容准确性	30%	品牌信息、设计规范的准确性
细节丰富度	20%	颜色、字体、间距等细节
格式规范性	15%	Markdown 语法、代码块格式
语言表达	15%	专业术语使用、表述清晰度

输出：

一致性打分（0-100）
详细评估报告（逐维度打分）
具体修改建议列表

步骤 2.4：迭代决策

角色： 主 Agent

决策逻辑：

if 一致性打分 >= 阈值:
输出最优提示词
生成最终报告
终止迭代
else:
进入优化阶段
返回步骤 2.1

步骤 2.5：优化提示词

角色： 主 Agent

任务：

解析 Subagent 2 的修改建议
识别低分维度对应的提示词问题
生成优化策略
更新提示词

优化策略示例：

结构完整性低分 → 补充"必须包含以下章节"指令
内容准确性低分 → 增加"请核对以下关键信息"指令
细节丰富度低分 → 添加"请详细描述每个设计元素"指令
格式规范性低分 → 强化 Markdown 格式要求
语言表达低分 → 提供专业术语示例

步骤 2.6：版本管理

角色： 系统

任务：

迭代计数器 += 1
将优化后的提示词保存为 V{计数器}
记录到版本历史库
生成对比报告（V{n-1} vs V{n}）

版本记录格式：

{
 "version": "V3",
 "timestamp": "2024-04-15T20:30:00Z",
 "prompt_content": "...",
 "test_score": 72,
 "changes": ["补充了颜色系统章节要求", "增加了间距规范说明"],
 "diff_from_previous": "..."
}

第三阶段：收敛输出

当一致性评分达到阈值时：

输出内容：

最优提示词版本
最终一致性打分报告
完整迭代历史
优化趋势图
效果对比表格（V0 vs V最优）

可优化点

1. 评估维度权重动态调整

当前问题： 固定权重可能无法适配不同类型的网站和文档

优化方案：

根据参考文档的特征自动调整权重
例如：电商网站侧重"内容准确性"，设计网站侧重"细节丰富度"

2. 并行化多个测试网站

当前问题： 只在 Nike 网站上测试，泛化能力未知

优化方案：

同时在多个同类网站（Adidas、Puma、Under Armour）测试
使用平均分评估提示词的泛化性
只有多网站都达标才算收敛

3. 增量式生成

当前问题： 每次都是全量生成，浪费计算资源

优化方案：

Subagent 2 识别低分章节
下一轮迭代只生成需要改进的章节
其他章节复用上一轮结果

4. 自动阈值调整

当前问题： 固定阈值可能导致过度优化或收敛困难

优化方案：

初始阈值设低（如 60 分）
每轮迭代根据改进幅度动态调整
连续 3 轮改进 < 2 分时自动降低阈值要求

5. 提示词模板库

当前问题： 每次从零开始优化，效率低

优化方案：

预置针对不同网站类型的提示词模板库
根据网站特征自动选择最接近的初始模板
减少迭代轮次

问题点

1. 幻觉风险

问题描述： Subagent 1 可能生成网站上不存在的信息

解决方案：

在提示词中强调"只生成网站明确展示的信息"
引入事实核查 Subagent
对生成的关键信息进行交叉验证

2. 迭代发散

问题描述： 可能出现提示词越来越复杂但效果反而下降

解决方案：

限制最大迭代次数（如 20 轮）
记录历史最优解，发现退化时回滚
引入提示词复杂度惩罚机制

3. 收敛过慢

问题描述： 某些情况下需要几十轮迭代才能收敛

解决方案：

引入早停机制（early stopping）
连续 5 轮无显著改进时终止
分析卡点并人工干预

4. 参考文档偏差

问题描述： collections/nike/DESIGN.md 本身可能存在主观性或错误

解决方案：

使用多个专家标注的参考文档
计算参考文档之间的共识
只对比高共识部分

5. 网站内容变化

问题描述： Nike 网站可能在迭代期间更新，导致对比失效

解决方案：

每轮迭代缓存网站快照
所有 Subagent 使用同一快照
或明确标注网站访问时间戳

补充扩展点

6. 负样本对比机制

设计思路： 除了与参考文档对比，还引入负样本测试：

故意使用"反例提示词"生成文档
评估系统应能识别出明显的错误
验证评估系统的鲁棒性

实现方式：

# 在迭代过程中随机插入负样本测试
if iteration % 5 == 0:
 negative_prompt = "请生成一个完全错误的 Nike 设计文档"
 negative_result = generate(negative_prompt)
 negative_score = evaluate(negative_result)
 assert negative_score < 30, "评估系统无法识别负样本"

7. A/B 测试框架

设计思路： 对于每个优化点，同时尝试多个策略，选择效果最好的：

示例：

优化"细节丰富度"时，同时测试：
- 策略 A：“请详细描述每个设计元素”
- 策略 B：“补充每个元素的 RGB 值、使用场景和设计意图”
- 策略 C：提供具体的颜色、字体示例模板
使用多 Agent 并行测试
选择得分最高的策略

8. 可解释性增强

设计思路： 为每次迭代增加"推理链路"记录，让优化过程更透明：

记录内容：

## 迭代 V3 决策记录

### 问题诊断
- 当前得分：72/100
- 主要短板：细节丰富度（45%）、格式规范性（58%）

### 优化推理
1. 细节不足分析：
 - 颜色系统缺少 RGB 值
 - 字体规范缺少 line-height、letter-spacing
 - 间距单位混用（px、rem、em）

2. 格式问题分析：
 - 表格缺少对齐声明
 - 代码块语言标注不一致
 - 链接使用相对路径而非绝对路径

### 优化策略
- 在提示词中添加"颜色系统必须包含 RGB 值"的显式指令
- 增加格式规范示例代码块
- 要求统一使用 rem 单位

### 预期效果
- 细节丰富度提升至 65%
- 格式规范性提升至 80%
- 综合得分预期：78/100

实施建议

优先级排序

P0（必须）： 解决幻觉风险、迭代发散
P1（重要）： 评估维度动态调整、并行多网站测试
P2（优化）： 增量式生成、A/B 测试、可解释性增强

技术栈推荐

Agent 编排： Claude Agent SDK 或自定义框架
网站抓取： Playwright 或 Puppeteer（支持动态内容）
对比评估： 结构化 diff + LLM 辅助
版本管理： Git + 自定义元数据存储

成功指标

指标	目标值
最终一致性评分	≥ 85
平均迭代轮次	≤ 10
单次迭代耗时	≤ 2 分钟
提示词长度增长率	≤ 50%（避免膨胀）
泛化测试通过率	≥ 80%（在同类网站上）

总结

这个提示词优化迭代系统通过多 Agent 协作形成了一个闭环反馈机制：

闭环路径： 版本库 → Subagent 1 → 生成文档 → Subagent 2 → 评估打分 → 优化提示词 → 版本库
核心价值： 将人工优化提示词的经验转化为可自动执行的迭代流程
扩展潜力： 可应用于各类需要高质量结构化输出的场景

关键在于设计好评估维度和优化策略，让每次迭代都有明确的改进方向。