| name | frontend-dev-workflow |
| description | 前端开发 AI Coding 工作流技能，适用于接手存量前端项目、修改已有页面、新增页面。 测试先行（守护测试 → 改代码 → 视觉验证）的完整闭环。 触发词包括：接手项目、接手前端、新增页面、修改页面、改UI、改样式、前端工作流、 前端测试、E2E测试、视觉验证、画像、项目画像、守护测试、截图对比、前端规范、 前端最佳实践、playwright测试、写测试、补测试。 模糊场景（如「帮我改一下这个页面」）先确认是否按工作流执行。
|
| metadata | {"author":"liuhean","email":"allsmy.com@gmail.com"} |
详细说明、代码示例、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 周：E2E 基础设施（安装 + 冒烟测试）→ 详见
§ 5.3、§ 5.4
- 持续：改哪测哪（守护测试 → 改代码 → 补新测试）
- 持续：新页面测试先行（TDD）
- 第 2~3 周：单元测试基础设施
- 按需：公共组件测试
独立触发本场景时：先确认项目现状、目标和优先范围，再输出实施方案并等待确认。
场景 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/
