frontend-dev-workflow

name	frontend-dev-workflow
description	前端开发 AI Coding 工作流技能，适用于接手存量前端项目、修改已有页面、新增页面。 测试先行（守护测试 → 改代码 → 视觉验证）的完整闭环。 触发词包括：接手项目、接手前端、新增页面、修改页面、改UI、改样式、前端工作流、 前端测试、E2E测试、视觉验证、画像、项目画像、守护测试、截图对比、前端规范、 前端最佳实践、playwright测试、写测试、补测试。 模糊场景（如「帮我改一下这个页面」）先确认是否按工作流执行。
metadata	{"author":"liuhean","email":"[e-mail]"}

详细说明、代码示例、Prompt 模板按场景拆分为以下文件：

文件	内容
references/ref-01-project-onboarding.md	§1 定位与适用范围、§2 接手项目（画像生成、CLAUDE.md 模板、视觉基线）
references/ref-02-modify-page.md	§3 修改已有页面（7 步流程、Figma 还原、守护测试）
references/ref-03-new-page.md	§4 新增页面（TDD 流程、data-testid 规范）
references/ref-04-testing.md	§5 测试体系全集（E2E/单元/组件/视觉回归/性能/a11y/CI）
references/ref-05-visual-verification.md	§6 视觉验证闭环（三种方式、AI 视觉审查、设计 token 提取对比表）
references/ref-06-ai-collaboration.md	§7 AI 协作规范（授权矩阵、验收标准、PR 证据包、会话产物沉淀与经验判定标准）
references/ref-07-scenarios-pitfalls.md	§8 常见场景速查 + §9 避坑指南（翻车类型、框架特有坑）
references/ref-08-tooling-prompts.md	§10 工具配置（MCP/Hooks/playwright.config）+ 附录A Prompt 模板 + 附录B 组件提取

前端开发 AI Coding 工作流

核心原则：测试先行 → 最小改动 → 视觉验证闭环 适用：存量前端项目接手 / 修改已有页面 / 新增页面（框架无关）

本技能是独立技能，不依赖其他技能。若上游已有需求、设计或任务产物，本技能只消费 spec.md、interaction-design.md、design-system-context.md、plan.md、tasks.md 等通用输入；若这些输入缺失、失效或错误，返回对应需求/spec 阶段修正，MUST NOT 在实施步骤中临场新建或补写设计文档。

框架术语映射（Vue / React / Angular / Svelte）→ 详见 § 1.1

---

场景识别

用户意图	执行场景
接手项目、了解前端项目	→ 场景 A
修改页面、改UI、调整样式	→ 场景 B
新增页面、加路由	→ 场景 C
写测试、补E2E、建测试体系	→ 场景 D
视觉验证、截图对比	→ 场景 E

意图模糊时先询问：「是 A 接手项目 / B 修改页面 / C 新增页面？」

---

场景 A：接手项目

完整 prompt 和 CLAUDE.md 模板 → 详见 § 2

执行顺序：

A1 生成项目画像（§ 2.1） 读取 package.json、构建配置、路由配置、状态管理目录、API 层目录、典型页面文件，输出技术栈清单、页面清单、组件层次、样式方案、API 调用方式。

A2 写入 CLAUDE.md（§ 2.2） 先输出项目画像草稿，等用户确认后，再将画像写入 CLAUDE.md（或 AGENTS.md，全项目唯一）；内容必须包含：技术栈、关键约定、不可修改区域（拦截器/路由守卫/鉴权工具）、验证命令。

A3 建立视觉基线（§ 2.3） 先列出建议截图清单，等用户确认后，再截图关键页面保存到 .baseline/（加入 .gitignore）。

注意：.baseline/ 仅用于人工对比；toHaveScreenshot() 生成的 snapshot 文件必须纳入 git。

A4 生成 Design Token 上下文（§ 2.4） 扫描项目设计系统配置（Tailwind config / CSS variables / 主题文件 / UI 库 token），提取语义化 token 别名表，写入 docs/ds-context.md。内容包含：颜色语义别名、间距规格、字体层级、组件变体映射。场景 B/C 在使用或创建 token 前 MUST 先读此文件，禁止使用裸色值/裸间距。

---

场景 B：修改已有页面

7 步详细流程 → 详见 § 3；Prompt 模板 → 附录 A.2

不可跳步，严格按序执行：

① 截图现状（1440px + 768px）→ 保存到 .baseline/
② Read 代码 + 理解结构（页面/子组件/样式位置/动态绑定）
③ 写守护测试 → 跑绿灯，再动代码         ← 核心约束
④ 精确描述改动（「从 A 改到 B」，不说「改好看点」）
⑤ 执行修改（高风险改动先确认，再 /freeze 锁住非 UI 层）
⑥ 跑守护测试 + 截图对比
⑦ 补充本次改动的新测试

Step ③ 守护测试覆盖维度选择（§ 5.5）：

维度	何时必选
UI（元素可见、布局、响应式）	改模板层/样式层
UX（交互流程、操作反馈）	改交互逻辑
异常边界（空数据、接口报错）	改业务逻辑
兼容性 L1（Chromium 基线）	默认每次
兼容性 L2（加 WebKit）	改全局样式/公共组件
回归（抽查其他页面）	改公共代码

Step ④ 有设计图时：只使用已锁定的设计引用与设计基线；可调用 /figma:implement-design 辅助还原（§ 3.5 情况A），但不得在本步骤新建设计文档

Step ⑤ 高风险改动前 prompt 追加：

改动前确认清单：
1. 本次会修改的所有文件
2. 逻辑层是否有改动（如有说明理由）
3. 所有动态样式绑定（条件class/动态style），确认不会丢失
4. 改动是否影响公共组件或全局样式
5. 是否涉及依赖或配置变更
仅当涉及逻辑层 / 公共组件 / 全局样式 / 依赖 / 配置时，展示以上清单并等待用户确认

---

场景 C：新增页面

完整流程 → 详见 § 4；data-testid 规范 → § 4.5；Prompt 模板 → 附录 A.3

TDD + 2步确认模式，不可跳步：

① 基于已锁定规格整理实施建议与复用分析（功能 + 交互 + 相似组件） → 等用户确认
② 列出 E2E 测试清单与文件改动清单 → 等用户确认后写测试（红灯）  ← TDD 起点
③ 生成页面代码直到测试全绿，所有交互元素加 data-testid
④ 视觉验证（1440px + 768px 截图走查） + 代码审查

data-testid 命名规范：[页面]-[区块]-[元素] 示例：order-detail-edit-btn、order-detail-goods-table

---

场景 D：建立测试体系

测试类型选择 → § 5.2；渐进式节奏 → § 5.1；E2E 示例 → § 5.6；UX 测试示例 → § 5.7 视觉回归测试（何时引入/避坑）→ § 5.8；CI/PR 门禁配置 → § 5.12；非E2E接入模板 → § 5.13 性能测试 → § 5.9；可访问性 → § 5.10；运行时监控 → § 5.11

测试类型决策：

纯函数/纯逻辑？→ 单元测试（Vitest/Jest）
公共组件库？  → 组件测试（Testing Library）+ E2E
其他          → E2E 测试（Playwright）← 首选，框架无关

渐进式建立节奏（§ 5.1）：

1. 第 1 周：E2E 基础设施（安装 + 冒烟测试）→ 详见 § 5.3、§ 5.4
2. 持续：改哪测哪（守护测试 → 改代码 → 补新测试）
3. 持续：新页面测试先行（TDD）
4. 第 2~3 周：单元测试基础设施
5. 按需：公共组件测试

独立触发本场景时：先确认项目现状、目标和优先范围，再输出实施方案并等待确认。

---

场景 E：视觉验证闭环

三种验证方式对比 → § 6.1；设计图还原度验证 → § 6.4（含各工具 token 提取方式对比表） 视觉回归测试详情（何时引入/避坑要点）→ § 5.8

日常改动验证（§ 6.2）： 截图改后页面 → 与 .baseline/ 对比 → 确认改动点生效、未改区域不变 → 更新基线

独立触发本场景时：先确认验证页面、对比基准和重点区域，再执行截图对比。

AI 视觉审查 Prompt（§ 6.3）：

[截图]
以设计审查视角检查：间距节奏、对齐一致性、字体层级、
颜色对比度（WCAG AA）、可点击区域≥44px、移动端溢出

---

AI 协作规范

完整规则 → 详见 § 7

Prompt 工程化管理（§ 7.1）： 项目级 prompt 模板存放在 .prompts/，纳入 git 管理。模板只引用 CLAUDE.md，不重复内嵌画像。

AI 输出验收标准（§ 7.2）：

• 自动验收：lint / typecheck / 现有测试全绿 / 新增代码有对应测试
• 人工验收：代码风格一致、无未确认 npm 包、无 mock 数据残留、改动范围与需求一致

会话产物沉淀（§ 7.3）：

内容	写入位置
架构决策和权衡	memory/decisions.md
踩坑和已知限制	memory/issues.md
发现的代码模式（出现 2 次以上）	memory/patterns.md
项目上下文	CLAUDE.md / AGENTS.md
可复用 prompt	.prompts/

写入 memory/patterns.md / memory/issues.md 前，先按 references/ref-06-ai-collaboration.md §7.3 的经验判定标准过滤：三镜头（黑话/索引/逻辑）+ 九类垃圾特征排除 + 源码事实校验 + 与历史去重合并。

AI 变更授权矩阵（§ 7.4）：

对象	默认	允许条件
认证/鉴权、支付、.env*、密钥	MUST NOT	不允许，人工落地
CI/CD 配置	MUST NOT	任务明确包含「搭建测试门禁」时，需独立 PR
package.json scripts	MAY	接入 lint / typecheck / test:e2e 脚本时
package.json devDependencies	MAY	接入测试/lint 工具
package.json dependencies	MUST NOT	需求显式授权
MCP / 本地开发工具配置	MAY	不写密钥，不影响生产
模板层/样式层	MAY	改 UI 时默认允许
逻辑层业务代码	须说明	仅纯展示逻辑，其他需用户确认

Review Checklist（AI 生成代码专用）（§ 7.5）：

□ 是否引入了未使用的新依赖？
□ 是否符合项目现有代码组织方式？
□ 是否有 AI 幻觉痕迹（不存在的 API、错误的参数顺序）？
□ 是否复用了已有工具函数/组件，而非重新实现？
□ 改动范围是否精确匹配需求，无附带「顺手优化」？

AI PR 证据包（§ 7.6）： PR 描述 MUST 包含：需求摘要（改了什么/明确不改什么）、改动文件清单、自动化验证结果（lint + typecheck + tests）、改前/改后视觉截图、回归影响范围、配置/依赖变更说明（如有）、未覆盖项与剩余风险。

收尾反思两问（§ 7.7）： AI 交付前 MUST 自问并随 PR 证据包一并输出：① 眼下最没把握的是什么？② 我最大的遗漏是什么？我没意识到什么？（前者源自 Sam Altman，后者源自 Claude；用于标注置信度边界与盲点，不否定交付）。

---

常见场景速查

表格页、表单页、导航布局、UI 库升级、暗色模式、国际化 → 详见 § 8

---

避坑指南

翻车类型及预防、各框架特有坑（Vue/React/Angular/Svelte）、什么时候不该用 AI 改 → 详见 § 9

---

工具配置参考

MCP 配置（Playwright/Context7/Figma 插件）、Hooks 配置、playwright.config.ts 推荐配置 → 详见 § 10

---

Prompt 模板速查

6 个完整模板（画像生成、存量页面修改、新增页面、视觉审查、守护测试、UI 库文档查询）→ 详见 附录 A

---

渐进式提取公共组件

完整流程 → 详见 附录 B

发现重复 UI 模式时的原则：

• 先标记后提取：发现重复先在 CLAUDE.md 记录「待提取模式」，积累 3 次以上再提取
• 不回改存量：提取组件后，已有页面保持不动；新页面和后续改动才使用新组件
• 渐进替换：存量页面因其他需求需改动时，顺手替换为新组件

---

参与贡献

仓库地址：https://github.com/liuhean2021/Anan-Agent-Skills 技能目录：skills/frontend-dev-workflow/