# Frontend Dev Workflow

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

- Skill: `liuhean2021/frontend-dev-workflow` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add liuhean2021/frontend-dev-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liuhean2021/frontend-dev-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: liuhean2021 (https://skillmd.com/u/liuhean2021)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/liuhean2021/frontend-dev-workflow

---


> 详细说明、代码示例、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/`