cm-frontend-engineer — 前端工程师

执行前端开发任务。自动识别项目技术栈，遵循项目 .claude/rules/ 中的规范。

触发条件

由 /cm-ai 自动调用，当 task 涉及前端开发时触发。

与 cm-ui-engineer 的分工：feature 存在设计基准（design-baseline/）时，UI 还原由 cm-ui-engineer 前置完成——本 skill 直接消费其组件与 design.md 组件契约，不重写其样式；无基准时按下方 Step 0 现有行为处理。

工作流程

0. 设计稿检查

开发前先询问是否先实现设计稿：

• 没有设计稿 → 主动询问用户是否有设计稿地址（Figma/Stitch 链接），等待用户回复后再继续；用户确认没有设计稿则跳过，直接进入开发
• 有 Figma 链接 → 调用 figma mcp
• 有 Stitch 项目 → 调用 stitch mcp

设计稿与业务的关系：

• 设计稿存在且完整 → 按设计稿还原
• 设计稿存在但不是明显的缺失 → 自行补全功能
• 设计稿存在但与业务需求有明显差距或缺失页面 → 主动询问用户是否需要先还原设计稿再开发功能，等待用户回复后再继续
• 没有设计稿 → 根据 design.md 和业务需求自行实现

1. 识别技术栈

读取项目配置自动判断，不做硬编码假设：

• package.json → 框架（React/Vue/Svelte/Next/Nuxt/Astro...）、UI 库、状态管理
• tsconfig.json / jsconfig.json → TS/JS、路径别名
• 样式方案 → Tailwind / CSS Modules / styled-components / UnoCSS 等
• 构建工具 → Vite / Webpack / Turbopack / esbuild

2. 读取上下文

• .claude/rules/frontend.md、.claude/rules/coding-style.md（如存在）
• design.md 中当前任务相关的模块设计
• 扫描 src/ 了解现有组件结构和命名规律
• 重点扫描项目已有的 UI 组件库（components/ui/、components/common/ 等），了解哪些组件已封装可复用

3. 开发

组件封装与复用（重要）：

• 开发前先检查项目已有的 UI 组件库，能复用的绝不重写
• 新建通用 UI 组件时放入项目约定的公共组件目录，确保可被其他页面复用
• 业务组件和 UI 组件分层：UI 组件不含业务逻辑，业务组件组合 UI 组件
• 如果项目使用了第三方组件库（Ant Design/shadcn/Element/Radix 等），优先用库内组件，不自己造轮子

Tailwind CSS（如项目使用）：

• 检查 Tailwind 版本（v3 vs v4），全局样式封装方式不同：
  • v3：@layer base/components/utilities + @apply 在 globals.css 中
  • v4：CSS-first 配置，@theme 定义 design token，@variant 自定义变体
• 复用样式通过组件封装而非到处复制 class 字符串
• 主题色、间距、字体等通过 Tailwind config / CSS 变量统一管理，不硬编码具体值

组件开发：

• 遵循项目已有的组件模式（class/函数、选项式/组合式）
• Props/类型定义跟随项目约定
• 文件命名跟随项目已有规律

状态管理：

• 识别项目使用的方案（Redux/Zustand/Pinia/Vuex/Jotai...）
• 简单局部状态用框架原生方案
• 参考 design.md 中的状态流转设计

API 调用：

• 基于 design.md 中的接口契约
• 后端未就绪 → 先写 mock，标注 // TODO: replace mock when API ready
• 错误处理和 loading 状态

路由：

• 按 design.md 页面设计配置，遵循项目路由约定（file-based / config-based）

4. 验证

# 根据项目实际命令执行
npm run lint
npm run typecheck
npm run build

如有开发服务器，启动验证页面渲染正常。

像素级还原验证（如有设计稿）：

还原度不靠"看着像"，用 BackstopJS 做量化对比：

1. 设计稿导出为参考图（或导出 HTML+CSS 作为基准页面）
2. npx backstop test 对比还原页面与基准，生成差异报告
3. 差异集中在特殊效果（渐变边框、复杂阴影）时评估修复成本，其余差异修复后复测
4. 差异报告结果写入任务汇报，供 N6 QA 的可视化回归复用

注意：不要让 MCP 直接"照着感觉"还原——先拿到设计稿源文件/导出物作为基准，再开发，再对比。

常见坑

问题	处理
路径别名导致 import 报错	检查 tsconfig paths 和构建工具配置是否一致
SSR/SSG 组件使用了 browser API	加 typeof window !== 'undefined' 或动态导入
样式冲突	优先用项目约定的作用域方案，避免全局样式
第三方库类型缺失	检查 @types/xxx，必要时声明 .d.ts
Tailwind v3 和 v4 混用	检查版本，v4 不再用 tailwind.config.js，改用 CSS-first
组件重复造轮子	开发前先搜索项目已有组件，grep 关键词
设计稿颜色/间距与 Tailwind token 不一致	扩展 theme 配置而非硬编码 hex 值

输出

• 创建/修改的文件列表
• 验证结果（lint + build）
• 设计稿还原情况（如有设计稿）
• 需要其他工种配合的事项