Product Builder

Product Builder - 产品级项目构建框架

核心理念：AI 的执行力没问题，问题在于"想得不够细"。本框架强制 AI 在写代码前先"想透"，确保产出是产品级质量而非"能跑就行"。

问题诊断

根本原因：AI 做的是"及格题"，不是"满分题"

工作流程

Phase 0: 需求澄清（必须）

在写任何代码前，必须完成以下步骤：

用户请求 → 反问澄清 → 确认范围 → 输出 PRD

澄清问题清单

强制输出 PRD

# [项目名称] 需求规格文档

## 1. 项目概述
- **目标用户**: [谁会用这个产品]
- **核心价值**: [解决什么问题]
- **成功指标**: [怎样算成功]

## 2. 功能范围
### 必须有 (P0)
- [ ] [功能1]: [描述]
- [ ] [功能2]: [描述]

### 应该有 (P1)
- [ ] [功能3]: [描述]

### 可选 (P2)
- [ ] [功能4]: [描述]

## 3. 非功能需求
- **性能**: [响应时间、并发量]
- **兼容性**: [浏览器、设备]
- **安全**: [认证、授权、数据保护]

## 4. 设计规范
- **风格参考**: [参考产品/设计稿]
- **主色调**: [颜色]
- **字体**: [字体选择]

Phase 1: 设计先行（必须）

禁止直接写代码，必须先定义设计规范：

1.1 收集参考

执行动作：
1. 询问用户有没有喜欢的产品可以参考
2. 如果有，让用户提供截图或链接
3. 如果没有，搜索同类产品的优秀案例
4. 总结设计参考点

1.2 定义 Design Token

在项目开始前创建 design-tokens.css 或 theme.ts：

:root {
  /* 颜色系统 */
  --color-primary: #667eea;
  --color-primary-hover: #5a67d8;
  --color-danger: #e53e3e;
  --color-success: #38a169;
  --color-warning: #d69e2e;

  /* 文字颜色 */
  --color-text: #1a202c;
  --color-text-secondary: #4a5568;
  --color-text-muted: #a0aec0;

  /* 背景颜色 */
  --color-bg: #ffffff;
  --color-bg-secondary: #f7fafc;
  --color-bg-tertiary: #edf2f7;

  /* 间距系统 */
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  --spacing-xl: 32px;
  --spacing-2xl: 48px;

  /* 圆角 */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-xl: 16px;
  --radius-full: 9999px;

  /* 阴影 */
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
  --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);
  --shadow-xl: 0 20px 25px rgba(0, 0, 0, 0.15);

  /* 动效 */
  --transition-fast: 0.15s ease;
  --transition-normal: 0.25s ease;
  --transition-slow: 0.35s ease;

  /* 字体 */
  --font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
  --font-size-xs: 12px;
  --font-size-sm: 14px;
  --font-size-base: 16px;
  --font-size-lg: 18px;
  --font-size-xl: 20px;
  --font-size-2xl: 24px;

  /* 层级 */
  --z-dropdown: 100;
  --z-modal: 200;
  --z-toast: 300;
}

规则：所有样式必须使用这些变量，禁止硬编码颜色、间距、圆角等。

1.3 选择 UI 组件库

推荐优先级：

1. shadcn/ui - Tailwind + Radix UI，可定制性最高
2. Ant Design - 企业级，组件丰富
3. Element Plus - Vue 生态
4. MUI - React 生态

强制要求：指定组件库后，所有组件必须来自该库，不允许自定义基础样式。

Phase 2: 分层实现

将项目分为多层，每层独立验收：

Layer 1: 数据层 - API、数据结构、状态管理
Layer 2: 逻辑层 - 业务逻辑、工具函数
Layer 3: UI 层 - 组件、页面
Layer 4: 交互层 - 动效、反馈、异常处理
Layer 5: 优化层 - 性能、响应式、无障碍

实现顺序

Phase 3: 组件级规格

每个组件实现前，必须先写规格：

组件规格模板

## [组件名称] 组件规格

### 视觉规格
- **尺寸**: 宽度 xx，高度 xx
- **间距**: padding xx，margin xx
- **圆角**: border-radius xx
- **阴影**: [阴影规格]
- **背景**: [背景色/渐变]

### 文字规格
- **标题**: 字号 xx，字重 xx，颜色 xx
- **正文**: 字号 xx，字重 xx，颜色 xx
- **辅助文字**: 字号 xx，颜色 xx

### 交互状态
| 状态 | 样式变化 | 触发条件 |
|------|----------|----------|
| 默认 | [样式] | - |
| 悬停 | [样式] | 鼠标移入 |
| 聚焦 | [样式] | Tab 键 |
| 激活 | [样式] | 点击 |
| 禁用 | [样式] | disabled=true |
| 加载 | [样式] | loading=true |

### 动效规格
| 动效 | 时长 | 缓动函数 | 触发条件 |
|------|------|----------|----------|
| 进入 | 0.3s | ease-out | 组件挂载 |
| 退出 | 0.2s | ease-in | 组件卸载 |
| 悬停 | 0.15s | ease | 鼠标移入 |
| 点击 | 0.1s | ease | 点击 |

### 响应式规格
| 断点 | 布局变化 | 尺寸变化 |
|------|----------|----------|
| 桌面 (>1024px) | [布局] | [尺寸] |
| 平板 (768-1024px) | [布局] | [尺寸] |
| 手机 (<768px) | [布局] | [尺寸] |

### 异常处理
- **数据为空**: 显示空状态
- **加载失败**: 显示错误提示 + 重试按钮
- **网络错误**: 显示离线提示

### 无障碍
- [ ] 键盘可访问
- [ ] 屏幕阅读器友好
- [ ] 颜色对比度达标
- [ ] 聚焦状态可见

Phase 4: 迭代打磨

功能完成后，强制进入打磨阶段：

打磨检查清单

## 视觉打磨
- [ ] 所有颜色使用 Design Token
- [ ] 所有间距使用 spacing 变量
- [ ] 所有圆角使用 radius 变量
- [ ] 字体大小一致
- [ ] 阴影层次分明
- [ ] 图标风格统一

## 交互打磨
- [ ] 所有按钮有悬停状态
- [ ] 所有输入框有聚焦状态
- [ ] 表单有验证提示
- [ ] 加载状态有反馈
- [ ] 错误有友好提示
- [ ] 成功有确认反馈

## 动效打磨
- [ ] 页面进入有动效
- [ ] 组件切换有过渡
- [ ] 列表项有交错动画
- [ ] 按钮点击有反馈
- [ ] 不影响性能

## 响应式打磨
- [ ] 375px 下正常显示
- [ ] 768px 下正常显示
- [ ] 1024px 下正常显示
- [ ] 图片自适应
- [ ] 文字不溢出

## 性能打磨
- [ ] 图片懒加载
- [ ] 组件按需加载
- [ ] 首屏 < 3s
- [ ] 交互响应 < 100ms

Phase 5: 完成验证（新增，必须）

每个功能完成后必须执行以下验证流程：

5.1 运行测试验证

# 运行所有测试
npm test

# 运行特定功能测试
npm test -- --grep "feature-name"

# E2E 测试
npx playwright test

5.2 自查清单检查

Agent 自查清单：
1. 我是否运行了相关测试？
2. 我是否验证了"完成标准"的每一项？
3. 我是否更新了相关文档？
4. 代码是否能正常编译/运行？
5. 是否有遗留的 TODO 或 FIXME？

如果任何一项是"否"，不能标记完成！

5.3 提交 Code Review

完成自查后，必须：
1. 发送消息给 reviewer 审查
2. 等待 reviewer 验证
3. 只有 reviewer 批准后才能标记 completed

禁止行为：
- ❌ 自己标记自己的任务为 completed
- ❌ 跳过 review 环节
- ❌ 没有测试就标记完成

5.4 Reviewer 批准

Reviewer 检查内容：
- [ ] 代码符合设计规范
- [ ] 测试覆盖关键场景
- [ ] 无明显性能问题
- [ ] 无安全漏洞
- [ ] 代码可读性良好

只有全部通过才能 approve=true

进度持久化

进度文件

项目根目录创建 .agent/progress.json：

{
  "project": "项目名",
  "last_session": "2026-03-13T15:00:00",
  "phase": "Phase 3",
  "completed": ["login-form", "api-layer"],
  "in_progress": "dashboard",
  "next_steps": ["完成 dashboard 组件"],
  "notes": "登录逻辑已实现，测试通过",
  "review_status": {
    "login-form": { "approved": true, "reviewer": "reviewer-agent" },
    "api-layer": { "approved": true, "reviewer": "reviewer-agent" },
    "dashboard": { "approved": false, "pending": true }
  }
}

会话恢复协议

新会话开始时必须：
1. 读取 .agent/progress.json
2. 检查 TaskList
3. 找到 in_progress 的任务
4. 发送消息唤醒相关 Agent
5. 如果 Agent 已关闭，重新 spawn

团队协作模式（Evaluator-Optimizer）

对于复杂项目，自动启动团队协作：

角色分工

Evaluator-Optimizer 流程

┌─────────────────────────────────────────────────────┐
│                   Developer Agent                    │
│  (实现功能、编写测试、自查清单)                       │
└─────────────────┬───────────────────────────────────┘
                  │ 提交审查
                  ▼
┌─────────────────────────────────────────────────────┐
│                   Reviewer Agent                     │
│  (代码审查、测试验证、质量评估)                       │
└─────────────────┬───────────────────────────────────┘
                  │
         ┌────────┴────────┐
         ▼                 ▼
    approve=true      approve=false
         │                 │
         ▼                 ▼
   标记 completed     返回 Developer
                      修改后重新提交

强制闭环流程

Agent 完成工作
    ↓
不能直接标记 completed！
    ↓
必须发送消息给 reviewer 审查
    ↓
Reviewer 验证通过后回复 approve=true
    ↓
只有 approve=true 时才能 TaskUpdate(status: "completed")

Token 效率考虑

代码生成策略

1. 分批实现，避免一次性生成大量代码
2. 优先实现核心功能，逐步迭代
3. 使用组件复用，减少重复代码
4. 利用 Design Token，避免重复样式定义

文件读取优化

1. 优先读取关键文件，避免全量扫描
2. 使用 Glob 精确定位文件
3. 大文件分段读取
4. 缓存已读取的文件内容

Prompt 模板

启动新项目

## 任务：开发 [项目名称]

### 执行流程
1. **Phase 0 - 需求澄清**：先提问澄清，确认后输出 PRD
2. **Phase 1 - 设计先行**：定义 Design Token，选择组件库
3. **Phase 2 - 分层实现**：按数据→逻辑→UI→交互→优化顺序
4. **Phase 3 - 组件规格**：每个组件先写规格再实现
5. **Phase 4 - 迭代打磨**：按检查清单逐项打磨
6. **Phase 5 - 完成验证**：测试→自查→Review→批准

### 禁止行为
- ❌ 直接开始写代码
- ❌ 硬编码颜色、间距
- ❌ 忽略加载/错误状态
- ❌ 不做响应式适配
- ❌ 跳过动效和交互细节
- ❌ 没有测试就标记完成
- ❌ 跳过 Review 环节

实现单个功能

## 功能：[功能名称]

### 规格要求
1. **数据结构**：[定义数据结构]
2. **UI 规格**：[布局、颜色、间距]
3. **交互状态**：[悬停、聚焦、加载、错误]
4. **动效**：[进入、退出、过渡]
5. **响应式**：[桌面/平板/手机]

### 完成标准（必须全部满足）
- [ ] 功能正确
- [ ] 视觉符合设计规范
- [ ] 所有交互状态完整
- [ ] 动效流畅
- [ ] 响应式正常
- [ ] 单元测试通过
- [ ] Reviewer 批准

### 验证命令
npm test

与其他 Skill 协作

触发条件

当检测到以下情况时，自动启动此 skill：

1. 用户说"帮我开发/做一个..."
2. 涉及多个页面或功能模块
3. 需要 UI/UX 设计
4. 用户对质量有要求（"好看"、"流畅"、"专业"）

核心原则

AI 不会"想得细"，但会很听话地"做得细"——前提是你先帮它"想细了"

1. 需求先于代码 - 没想清楚就不动手
2. 设计先于实现 - 没有设计规范就不写样式
3. 规格先于组件 - 没有组件规格就不写组件
4. 打磨是必需品 - 功能完成不是结束，打磨才是
5. 验证是强制项 - 没有测试和 Review 就不算完成

五不原则

示例：完整项目流程

用户: 帮我开发一个用户登录页面

### Claude 执行流程:

## Phase 0: 需求澄清
- 目标用户是谁？（普通用户/企业用户）
- 登录方式？（账号密码/手机验证码/第三方登录）
- 有没有参考设计？
- 品牌色是什么？

## Phase 1: 设计先行
创建 design-tokens.css，定义：
- 主色、辅色、错误色
- 间距、圆角、阴影
- 字体、字号
选择组件库：shadcn/ui

## Phase 2: 组件规格
撰写登录表单组件规格：
- 输入框：48px 高，8px 圆角，聚焦时边框变主色
- 按钮：48px 高，渐变背景，悬停加深
- 错误提示：红色文字，抖动动画

## Phase 3: 分层实现
1. 数据层：登录 API 调用
2. 逻辑层：表单验证、错误处理
3. UI 层：登录表单组件
4. 交互层：加载状态、错误提示
5. 优化层：响应式、无障碍

## Phase 4: 打磨
- 添加背景渐变
- 输入框聚焦动效
- 按钮 hover 缩放
- 记住我复选框
- 忘记密码链接
- 注册引导

## Phase 5: 完成验证
1. 运行测试：npm test
2. 自查清单检查
3. 提交 reviewer 审查
4. Reviewer 批准
5. 标记完成
6. 更新 progress.json