# Product Builder

> 产品级项目构建框架：从需求分析到高质量交付，让 AI 不只是写代码，而是做项目。触发词：做项目、开发产品、完整功能、从零开始。

- Skill: `majiayu000/product-builder` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/product-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/product-builder/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/product-builder

---


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

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

---

## 问题诊断

| 维度 | 当前 AI 表现 | 期望表现 |
|------|-------------|----------|
| 代码生成速度 | ⭐⭐⭐⭐⭐ 极快 | ✅ 已满足 |
| 功能正确性 | ⭐⭐⭐⭐ 基本对 | ✅ 已满足 |
| UI 美观度 | ⭐⭐ 烂 | ❌ 需改进 |
| 交互细节 | ⭐ 粗糙 | ❌ 需改进 |
| 用户体验 | ⭐ 不考虑 | ❌ 需改进 |

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

---

## 工作流程

### Phase 0: 需求澄清（必须）

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

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

#### 澄清问题清单

| 问题类型 | 示例问题 |
|----------|----------|
| **用户是谁** | 目标用户是什么人群？技术水平？ |
| **核心场景** | 用户在什么场景下使用？解决什么问题？ |
| **参考对象** | 有没有喜欢的产品可以参考？ |
| **关键指标** | 怎样算成功？用户满意度？转化率？ |
| **边界条件** | 什么情况不考虑？有什么限制？ |

#### 强制输出 PRD

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

## 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`：

```css
: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: 优化层 - 性能、响应式、无障碍
```

#### 实现顺序

| 顺序 | 层级 | 验收标准 |
|------|------|----------|
| 1 | 数据层 | API 能调通，数据结构正确 |
| 2 | 逻辑层 | 核心逻辑单元测试通过 |
| 3 | UI 层 | 页面渲染正确，组件可用 |
| 4 | 交互层 | 动效流畅，异常提示清晰 |
| 5 | 优化层 | 性能达标，响应式正常 |

---

### Phase 3: 组件级规格

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

#### 组件规格模板

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

### 视觉规格
- **尺寸**: 宽度 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: 迭代打磨

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

#### 打磨检查清单

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

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

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

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

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

---

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

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

#### 5.1 运行测试验证

```bash
# 运行所有测试
npm test

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

# E2E 测试
npx playwright test
```

#### 5.2 自查清单检查

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

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

#### 5.3 提交 Code Review

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

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

#### 5.4 Reviewer 批准

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

只有全部通过才能 approve=true
```

---

## 进度持久化

### 进度文件

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

```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 }
  }
}
```

### 会话恢复协议

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

---

## 团队协作模式（Evaluator-Optimizer）

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

### 角色分工

| 角色 | 职责 | 输出 |
|------|------|------|
| **产品经理** | 需求分析、PRD 撰写、优先级排序 | PRD 文档 |
| **设计师** | 设计规范、Design Token、组件规格 | 设计系统 |
| **前端开发** | UI 组件、页面实现、交互逻辑 | 前端代码 |
| **后端开发** | API 设计、数据层、业务逻辑 | 后端代码 |
| **测试** | 测试用例、边界验证、性能测试 | 测试报告 |
| **Reviewer** | 代码审查、安全检查、性能优化 | 审查报告 |

### Evaluator-Optimizer 流程

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

### 强制闭环流程

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

---

## Token 效率考虑

### 代码生成策略

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

### 文件读取优化

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

---

## Prompt 模板

### 启动新项目

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

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

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

### 实现单个功能

```markdown
## 功能：[功能名称]

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

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

### 验证命令
npm test
```

---

## 与其他 Skill 协作

| Skill | 协作方式 |
|-------|----------|
| **long-running-agent** | 复杂项目自动创建团队、分配任务 |
| **self-improvement** | 记录踩坑经验、提炼最佳实践 |
| **insight-capture** | 捕获用户偏好、记录项目决策 |
| **code-review** | Phase 5 强制审查流程 |

---

## 触发条件

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

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

---

## 核心原则

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

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

---

## 五不原则

| 原则 | 含义 |
|------|------|
| **不做完不结束** | 每个任务必须有明确完成标准 |
| **不验证不完成** | 必须有人审查 |
| **不记录不结束** | 必须写入进度 |
| **不恢复不开始** | 新会话必须检查上次进度 |
| **不提交不结束** | 每次变更必须 git commit |

---

## 示例：完整项目流程

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

### 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
```