AI 辅助前端开发工作流

把前端研发中的需求理解、上下文准备、实现、验证、Review 与知识回流组织成可重复的 AI 协作闭环，并明确哪些决策仍必须由工程师负责。

#frontend #synthesis #growing

[!info] related notes

所属 MOC: 前端工程化 MOC

Agent 角色: Agent 在前端工程中的角色

Review: AI Code Review 与重构

TDD: AI 编码时代的 TDD

前端可靠性: AI 产品前端可靠性

工程资产: 前端团队 AI 工程资产

AI 辅助前端开发工作流

一句话定义

AI 辅助前端开发不是“让模型直接把页面写完”，而是把：

Contract
→ Context
→ Plan
→ Implement
→ Verify
→ Review
→ Integrate
→ Learn

组织成闭环，让 AI 加速可验证工作，而工程师保持需求、架构和质量责任。

1. Contract：先定义完成条件

开始前先明确：

用户要完成什么行为；
哪些 UI 状态必须存在；
哪些 API / component contract 不能破坏；
responsive / accessibility / performance 边界；
什么测试或浏览器证据算完成。

错误方式：

“帮我优化一下这个页面”

更好的任务描述：

目标：窄屏时筛选器自动收缩，但保留状态/日期筛选
不可破坏：现有 query params 与 keyboard navigation
验证：desktop + 900px + 600px 三档截图，lint/test/build 通过

AI 最怕的不是任务复杂，而是 acceptance criteria 模糊。

2. Context：给足“最小充分上下文”

上下文应优先包含：

目标文件
相关组件
设计系统 / token
已有模式
API type
测试
错误日志 / screenshot
项目规则

而不是把整个 repository 无差别塞进去。

一个实用 Context Packet

Task
- 要改什么

Existing behavior
- 当前怎样工作

Constraints
- 不能破坏什么

References
- 相似组件 / Figma / screenshot

Validation
- lint / unit / e2e / browser

核心原则：

把“AI 必须推测”的部分尽量变成可读取证据。

3. Plan：先建立修改边界

对跨文件任务，先让 Agent 回答：

真正需要改哪些层；
哪些现有组件可以复用；
数据流从哪到哪；
哪些是风险点；
如何验证。

如果计划开始出现：

重写整个模块
新增第二套组件
绕开现有 design system

但任务本身只是局部改造，应先纠正 scope，再编码。

4. Implement：优先交给 AI 哪些工作

AI 更适合：

明确 UI skeleton；
重复组件迁移；
TypeScript 类型补齐；
机械 refactor；
test scaffold；
adapter / mapper；
API wiring；
样式 token 替换；
根据现有模式生成同类代码。

共同特点：

有局部 contract，结果容易验证。

5. 哪些内容不要直接委托判断

工程师应重点掌握：

产品需求是否正确；
信息架构；
状态 ownership；
public API / domain boundary；
安全与权限；
是否值得引入 dependency；
是否值得做 abstraction；
最终 UX 是否成立。

AI 可以提出方案，但不能把“模型说得很合理”当成设计证据。

6. Verify：让验证成为开发循环的一部分

AI 生成代码之后必须进入证据链：

static check
→ unit/integration test
→ build
→ browser/runtime
→ visual/interaction check

不同问题用不同 oracle。

Type / compile

TypeScript；
lint；
build。

Behavior

unit / integration / e2e；
API contract test。

UI

浏览器截图；
responsive resize；
keyboard / focus；
console/network。

“代码看起来对”不是验证。

7. UI 任务尤其需要视觉闭环

前端 Agent 最常见失败：

DOM 正确
CSS 也合法
但实际界面很差

因此 UI 任务至少验证：

spacing；
alignment；
overflow；
narrow width；
empty/loading/error；
theme；
interaction feedback。

如果有真实设计稿或 screenshot，应把它当 visual reference，而不是只靠自然语言描述。

8. Review：审查“为什么这么改”

Review 不只看有没有 bug。

要检查：

Correctness

数据流正确吗？
stale state / race condition？
error path？

Architecture

是否引入重复 abstraction？
是否破坏 ownership boundary？
是否把 server state 塞进 local/global state？

Maintainability

命名；
component boundary；
dead code；
magic value；
duplicated style。

UX

用户是否更容易完成任务？
小屏/键盘/异常态是否成立？

详见 AI Code Review 与重构。

9. TDD 何时特别适合 Agent

如果任务可以先写稳定 observable behavior：

failing test
→ minimal implementation
→ test pass
→ refactor

Agent 的搜索空间会明显缩小。

特别适合：

formatter / parser；
reducer；
API handler；
state transition；
validation；
bug regression。

UI 美学探索则不应机械强迫所有东西先写 unit test。

10. Integration：不要直接把大改动当最终结果

更稳的改动单位：

small coherent diff
→ validate
→ review
→ commit/integrate

比：

一次让 Agent 改 40 个文件
→ 最后才发现方向错

风险更低。

对于长任务，可以用 branch/worktree 保护主线。

11. Stop Condition

Agent 需要明确什么时候结束。

例如：

acceptance criteria 全部满足
lint/test/build pass
浏览器无新增 console error
视觉状态已核对
没有 unrelated diff

否则 Agent 容易继续“顺手优化”，把任务扩大成无边界重构。

12. Learn：把重复纠正变成工程资产

如果同一个错误第二次出现：

项目规则 → AGENTS.md / CLAUDE.md；
复杂操作 → Skill；
稳定验证 → test / lint rule；
可复用 UI → component/design token；
架构结论 → ADR / knowledge note。

这样 AI workflow 才会随项目持续变强，而不是每次重新聊天。

一个完整示例

任务：把筛选 Header 做成响应式。

1. Contract
   → 600px 下收缩低优先级 label
   → query state 不丢

2. Context
   → Header component
   → button primitive
   → existing responsive utility
   → screenshot

3. Plan
   → 不改 filter domain
   → 只改 presentation + responsive composition

4. Implement
   → reuse primitives

5. Verify
   → typecheck
   → component tests
   → 1200/800/600 screenshots
   → keyboard tab

6. Review
   → no hardcoded theme color
   → no duplicate component

7. Integrate
   → focused commit

常见失败模式

Prompt 很长，但没有 acceptance criteria

上下文很多不代表目标清楚。

AI 一次重写太多

Diff 大到无法 review，就失去 Human-in-the-loop 的意义。

只跑 lint

Lint 不能证明 UI 或业务行为正确。

把 AI 当搜索替代品

当前 API、库行为、浏览器兼容性仍应看权威来源和真实运行证据。

只评价“代码写得快”

真正指标应包括：

lead time；
defect / regression；
review cost；
rework；
validation coverage。

学习检查

不看正文回答：

为什么 AI 开发闭环应该从 Contract 开始，而不是从 Prompt 开始？
“最小充分上下文”与“把整个仓库都塞进去”有什么差异？
哪些前端任务天然更适合 AI，为什么？
Typecheck、test、browser、visual check 分别是哪类 oracle？
为什么 UI 任务不能只靠 lint/test？
Stop condition 为什么能减少 Agent 的 scope creep？
同一个纠正重复出现两次后，应该怎样沉淀为工程资产？
给一个真实前端功能，按 Contract → Context → Plan → Implement → Verify → Review → Integrate 设计执行流程。