AI 辅助编程全生命周期

主题

/product-design ​

产品设计契约。需求确认后、技术方案前使用。

产品设计契约 ​

在需求确认（/spec）之后、技术方案（/plan）之前，生成两份互补的设计契约：

  • product-spec.md — 产品结构：信息架构、用户旅程、状态权限、埋点
  • design-spec.md — 视觉规范：Token、组件、交互模式、组合模式

两份文件通过共享组件词汇表连接，AI 生成 UI 代码时必须同时参考。

触发时机 ​

  • 需求已确认（有 spec.md 或口头确认），功能涉及 UI
  • 用户主动输入 /product-design

输入要求 ​

此 Skill 可接受以下输入（按推荐程度排序）：

  1. 最理想：同时有 spec.md（需求）和 prd.md（数据模型） — 两份文件都能直接映射
  2. 可接受：只有 spec.md — product-spec 正常生成，design-spec 的内容模型部分用 [FILL]
  3. 最低限度：用户口头描述 — 必须在 Step 1 通过提问补足上下文，否则容易偏离

如果需求还不清晰，建议先运行 /spec；如果涉及多实体数据模型，建议先运行 /prd。

步骤 ​

Step 1: 理解项目上下文 ​

读取以下文件（存在则读，不存在则跳过）：

  1. docs/spec.md 或 docs/*-spec.md — 需求规格
  2. docs/prd.md — PRD（如有）
  3. 项目已有的 product-spec.md / design-spec.md（如有，是更新而非新建）

如果以上都不存在，向用户提问：

  • 这个产品是做什么的？核心功能是什么？
  • 目标平台？（小程序 / Web / 两端）
  • 有没有视觉参考？（竞品、截图、风格关键词）

用一句话复述确认：

"我理解这是一个 [平台] 的 [产品类型]，核心是 [功能]。对吗？"

Step 2: 确定范围与裁剪 ​

根据项目规模裁剪模板章节。不是所有章节都要填。

必填章节（所有项目）：

  • product-spec: §1 产品定义、§2 信息架构（站点地图 + 路由）、§3 核心旅程（首次体验 + 主价值循环）、§4 页面注册与状态矩阵、§5 用户状态与权限
  • design-spec: §1 设计原则、§2 Token 系统（颜色 + 字体 + 间距）、§4 核心组件、§5 交互模式（表单 + 加载 + 错误）

按需章节（向用户确认是否需要）：

  • 转化/付费旅程 — 有商业化需求时
  • 通知与消息体系 — 有推送/消息需求时
  • 数据分析与埋点 — 需要数据驱动时
  • 国际化 — 多语言需求时
  • 动效规范 — 有动画需求时
  • 暗色模式 — 需要主题切换时

向用户展示裁剪建议：

"根据你的项目，我建议填写以下章节：[列表]。跳过：[列表]。同意吗？"

Step 3: 建立共享词汇表 ​

这是两份文件的连接点，必须先建立。

从 Step 1 收集的信息中提取项目会用到的 UI 组件，结合模板默认词汇表，生成项目的共享词汇表草案。格式：

markdown
| 规范名称 | 含义 | 使用场景 | design-spec 章节 |
|---------|------|---------|----------------|
| Modal | 居中对话框 + 遮罩 | 确认/提示/权限拒绝 | DS:4.6 |
| Toast | 短暂非阻断消息 | 操作反馈 | DS:4.7 |
| EmptyState | 无数据占位 | 列表空态 | DS:4.7 |
| [项目自定义] | [FILL] | [FILL] | DS:4.x |

向用户展示词汇表草案，等待确认后再进入 Step 4。

词汇表确认后，写入两份文件的 §0.2，后续步骤中引用组件必须使用此表中的规范名称。

Step 4: 生成 product-spec.md ​

从模板获取结构（按优先级：docs/templates/product-spec-template.md → ~/.claude/product-spec-template.md → 本 Skill 内置章节结构）。

按以下顺序填写：

  1. 产品定义（§1）— 从 spec.md 提取定位、用户画像、价值主张
  2. 信息架构（§2）— 站点地图、导航模型、路由规范、内容模型
  3. 用户旅程（§3）— 首次体验、主价值循环、转化（如适用）
  4. 页面注册与状态矩阵（§4）— 每个页面的 7 种状态
  5. 代码风险区域（§4.3，按需）— 当 spec.md 包含敏感数据盘点（§7.1）或产品涉及安全/支付/数据密集型逻辑时，标注系统中不同模块的 AI 协作强度
  6. 用户状态与权限（§5）— 状态机、权限矩阵
  7. 按需章节（§6-§10）

关键原则：

  • 用 [FILL] 标记需要用户补充的信息，不要编造业务数据
  • 旅程表格的"组件"列使用 Step 3 建立的词汇表名称
  • 页面状态矩阵中引用 design-spec 的组件（如 Skeleton -> DS:4.7）
  • 交叉引用使用 -> PS:章节号 和 -> DS:章节号 格式
  • 为以下结构同时生成 Mermaid 图（VitePress / GitHub 原生渲染）：
    • 站点地图（§2.1）→ graph TD 树形图，展示页面层级和导航关系
    • 用户状态机（§5.1）→ stateDiagram-v2，展示状态转换和触发事件
    • 实体关系（§2.4）→ erDiagram，展示实体和关联关系
    • Mermaid 图紧跟在对应的文本/表格描述之后，作为可视化补充而非替代

输出到 docs/product-spec.md（或用户指定的路径）。

等待用户确认 product-spec.md 后再进入 Step 5。 用户应审查：

  • 信息架构是否覆盖了所有页面？有无孤立页面？
  • 用户旅程是否完整？异常路径有无恢复方案？
  • 权限矩阵是否覆盖了所有角色 × 功能？

Step 5: 生成 design-spec.md ​

从模板获取结构（按优先级：docs/templates/design-spec-template.md → ~/.claude/design-spec-template.md → 本 Skill 内置章节结构）。

按以下顺序填写：

  1. 设计原则（§1）— 风格关键词、核心约束、优先级
  2. Token 系统（§2）— 颜色、字体、间距、圆角、阴影、断点
  3. 布局系统（§3）— 安全区、页面骨架、网格
  4. 组件规范（§4）— 按钮、输入框、卡片、列表项、导航、浮层、反馈、媒体、标签
  5. 交互模式（§5）— 表单、加载、错误处理、下拉刷新、手势
  6. 组合模式（§6）— 列表页、详情页、表单页、设置页、结果页
  7. 按需章节（§7-§8）— 动效、响应式/暗色模式

关键原则：

  • Token 值用 CSS 变量格式（--color-primary），不写死具体值除非用户提供了品牌色
  • 组件规范包含：props/变体、状态（default/hover/active/disabled/error）、正确/错误示例
  • 每个组件标注无障碍要求（对比度、触控区域、ARIA）
  • 用 [FILL] 标记品牌相关的值（颜色、字体），用 [DEFAULT] 提供合理默认值

输出到 docs/design-spec.md（或用户指定的路径）。

Step 6: 一致性检查 ​

两份文件生成后，执行交叉检查：

  1. 词汇表一致 — product-spec 引用的组件名都在 design-spec §4 中定义
  2. 页面覆盖 — product-spec §4.1 的每个页面类型都有 design-spec §6 的组合模式
  3. 状态覆盖 — product-spec §4.2 状态矩阵引用的组件（Skeleton、EmptyState、ErrorState）都在 design-spec 中定义
  4. 交叉引用有效 — 所有 -> DS:x.x 和 -> PS:x.x 指向的章节存在

输出检查结果，有不一致则修正。

Step 7: 输出摘要与下一步 ​

markdown
## 产品设计契约已生成

| 文件 | 路径 | 章节数 | FILL 项 |
|------|------|--------|---------|
| product-spec.md | docs/product-spec.md | X | Y 项待填 |
| design-spec.md | docs/design-spec.md | X | Y 项待填 |

### 待用户补充
- [列出关键的 FILL 项]

### 下一步
- 补充 FILL 项后，使用 `/plan` 进行技术方案设计
- AI 生成 UI 代码时会自动参考这两份文件

模板路径 ​

按优先级查找模板（找到即停）：

  1. 项目级：docs/templates/product-spec-template.md、docs/templates/design-spec-template.md
  2. 全局级：~/.claude/product-spec-template.md、~/.claude/design-spec-template.md
  3. 兜底：使用本 Skill 内置的章节结构（即步骤中描述的 §1-§10 / §1-§8）

IMPORTANT ​

  • 不要无脑填模板 — 根据项目规模裁剪，小项目可能只需要 product-spec 的 5 个必填章节 + design-spec 的 Token 和核心组件
  • 不要编造业务数据 — 用户画像、定价、指标等必须来自 spec.md 或用户输入，不确定就用 [FILL]
  • 两份文件必须互相引用 — 这是契约的核心价值，孤立的两份文件不如不写
  • design-spec 用英文 — 遵循项目约定（代码注释用英文），Token 名和组件名用英文
  • product-spec 用中文 — 面向产品理解，中文更直观
  • 等待确认 — 每个关键步骤（裁剪范围、词汇表、最终输出）都等用户确认

面向个人开发者的 AI 辅助编程工程化方案

基于 Claude Code 构建