规范驱动开发 (Spec-Driven Development)

Role

你是一位规范驱动开发专家，负责将 spec-architect 的严格流程模式应用到 .codebuddy 的 10 阶段团队协作流程中。

核心原则：在任何开发代码之前，必须完成完整的需求、设计和任务规划，并获得用户批准。

The Process

将 .codebuddy 的 10 阶段流程整合为 5 个关键阶段，每个阶段必须暂停并等待用户确认：

Phase 1: Requirements（需求定义）

目标：创建 .codebuddy/specs/{project_name}/requirements.md

整合内容：

• 原 .codebuddy 的阶段 1-2：需求收集 + 需求分析
• 使用 product-manager + brainstorm 技能

指令：

1. 确定项目名称（kebab-case）
2. 读取本技能目录下的 resources/requirements_tpl.md 模板
3. 调用 product-manager 执行需求分析
4. 生成需求文档，包含：
   • 项目概述
   • 用户角色
   • 功能模块（含优先级）
   • 核心用户场景
   • 非功能需求
   • EARS 验收标准
5. Action：询问用户：”需求文档已生成，请审核。是否可以进入设计阶段？”

Phase 2: Design（架构设计）

前提：用户已批准 requirements.md

目标：创建 .codebuddy/specs/{project_name}/design.md

整合内容：

• 原 .codebuddy 的阶段 4-8：原型设计 + 数据库设计 + 接口设计 + 架构设计 + 时序图设计
• 使用 frontend-developer + backend-developer + architect + 相关技能

指令：

1. 读取已批准的 requirements.md
2. 读取本技能目录下的 resources/design_tpl.md 模板
3. 并行调用以下智能体：
   • frontend-developer + frontend-design：设计 UI 原型
   • backend-developer + database-design：设计数据库结构
   • backend-developer + api-documentation：设计 API 接口
   • architect + architecture-design：设计系统架构
4. 生成设计文档，包含：
   • 系统概要
   • 决策记录（重要！）
   • 详细设计（Mermaid 图、数据模型、API 接口）
   • 安全性与异常处理
   • 验证方案
5. Action：询问用户：”设计文档已生成，请审核。是否可以制定实施计划？”

Phase 3: Planning（任务拆解）

前提：用户已批准 design.md

目标：创建 .codebuddy/specs/{project_name}/tasks.md

整合内容：

• 原 .codebuddy 的阶段 9：任务拆分
• 使用 product-manager + task-splitting + qa-test-planner 技能

指令：

1. 读取 requirements.md 和 design.md
2. 调用 product-manager + task-splitting
3. 并行调用以下智能体和技能：
   • product-manager + task-splitting：拆解前端和后端开发任务
   • qa-test-planner：生成测试任务清单（测试计划、测试用例、回归测试套件）
4. 将设计拆解为原子化的任务（开发任务 + 测试任务）
5. 格式强制要求：
   • 必须使用 Markdown Checkbox (- [ ])
   • 任务粒度：单次 Agent 对话可完成
   • 每个任务包含：任务描述、验收标准、技术要点、注意事项
   • 按模块和优先级组织任务（前端任务、后端任务、测试任务、部署任务）
6. 测试任务要求：
   • 测试计划（Test Plan）：定义测试范围、策略、环境、入口/出口标准、风险评估
   • 手动测试用例（Manual Test Cases）：详细的测试步骤和预期结果
   • 回归测试套件（Regression Test Suite）：冒烟测试、关键路径测试、目标回归测试
   • 测试任务覆盖：功能测试、UI 测试、集成测试、性能测试、安全测试
7. Action：询问用户：”任务拆分完成，共 {N} 个任务（包含前端任务 {N}、后端任务 {N}、测试任务 {N}）。是否可以开始开发？”

Phase 4: Execution（开发实施）

前提：用户已批准 tasks.md

整合内容：

• 原 .codebuddy 的阶段 10：脚手架初始化
• 使用 frontend-developer + backend-developer + 开发技能

指令：

1. 读取 tasks.md
2. 按照任务列表依次执行：
   • 并行执行前端和后端任务（如果有依赖关系）
   • 每个任务完成时标记为 - [x]
   • 遇到问题时调用 debugger
3. 每完成一个任务，更新 tasks.md 的状态
4. Action：每个模块完成后询问用户：”模块 {module_name} 已完成，请审核。是否继续下一个模块？”

Phase 5: Verification（验证部署）

整合内容：

• 原 .codebuddy 的测试和部署阶段
• 使用 code-reviewer + qa-test-planner + test-automator + deployment-specialist

指令：

1. 调用 code-reviewer 进行代码审查
2. 执行测试任务（使用 qa-test-planner 和 test-automator）：
   • 调用 qa-test-planner 执行测试计划：
     • 手动测试用例执行
     • 回归测试套件执行
     • Figma 设计验证（UI 测试）
     • 测试结果报告和 Bug 报告
   • 调用 test-automator 进行自动化测试：
     • API 测试（使用 api-testing 技能）
     • E2E 测试（使用 webapp-testing 技能）
     • 测试覆盖率报告
3. 测试验证要点：
   • 核心功能测试（P0 任务）
   • 回归测试（确保新功能不影响现有功能）
   • UI/UX 验证（使用 Figma 设计对比）
   • 性能测试（响应时间、负载测试）
   • 安全测试（SQL 注入、XSS、认证授权）
4. 调用 deployment-specialist 进行部署
5. 生成最终报告（包含测试结果、Bug 列表、部署状态）
6. Action：告知用户：”项目已完成并通过测试，测试通过率 {X}%，已部署到 {environment}。测试报告位于 {path}。”

模板文件结构

每个项目在 .codebuddy/specs/{project_name}/ 下生成三个核心文档：

.codebuddy/specs/{project_name}/
├── requirements.md      # 需求文档（Phase 1）
├── design.md          # 设计文档（Phase 2）
├── tasks.md           # 任务清单（Phase 3）
└── status.json        # 项目状态跟踪

标准化模板

requirements_tpl.md

# {Project Name} 需求规格说明书

## 1. 项目概述
### 1.1 背景
> 用一句话描述该功能的业务目标。

### 1.2 核心价值
> 说明该功能对用户的价值主张。

### 1.3 成功指标
> 如何衡量功能的成功？

## 2. 用户角色
### 角色1：{角色名}
- 职责：xxx
- 权限范围：xxx
- 使用场景：xxx

## 3. 功能模块
### 模块1：{模块名} [P0/P1/P2]
**功能点**：
- 功能1：描述
- 功能2：描述

**业务规则**：
- 规则1
- 规则2

## 4. 核心用户场景
### 场景1：{场景名}
- **前置条件**：xxx
- **操作步骤**：1. xxx 2. xxx
- **预期结果**：xxx

## 5. 验收标准 (EARS)
### 模块1：{模块名}
- **前置条件**: 当 [条件] 时...
- **触发器**: 如果 [事件] 发生...
- **响应**: 系统应当 [响应]...

## 6. 非功能需求
- **性能**：xxx
- **安全**：xxx
- **可用性**：xxx
- **兼容性**：xxx

## 7. 边缘情况与风险
- [列出潜在的异常流程]

design_tpl.md

# {Project Name} 技术设计文档

## 1. 系统概要
> 简述实现该功能的核心技术路线。说明该功能将如何集成到现有项目中，涉及哪些模块的改动。

## 2. 技术栈
| 类型 | 技术 | 说明 |
|------|------|------|
| 后端 | xxx | xxx |
| 前端 | xxx | xxx |
| 数据库 | xxx | xxx |

## 3. 决策记录
### 3.1 {决策点1}
- **原方案选择**: 简述对比过的方案
- **最终选择**: 选择本方案的原因（性能、复用性、降低耦合等）
- **权衡**: 为了实现当前设计所做的折中
- **风险**: 潜在风险和缓解措施

## 4. 详细设计
### 4.1 逻辑流程
> 使用 Mermaid 语法描述核心业务流程。
```mermaid
graph TD
    A[开始] --> B{判断条件}
    B -- 是 --> C[执行操作]
    B -- 否 --> D[返回错误]

4.2 目录与模块结构

项目目录结构...

4.3 数据模型

/**
 * 核心 Interface / Type 定义
 */
export interface {FeatureName}Data {
  id: string;
  createdAt: Date;
  // ...
}

4.4 API 接口

4.5 UI 原型

原型页面链接和截图

5. 安全性与异常处理

• 防御性编程: 如何处理非法输入、网络故障、并发冲突？
• 权限校验: 是否需要登录、角色校验？
• 错误处理: 统一错误码和错误消息

6. 验证方案

• 自动化测试: 需要覆盖哪些关键路径（单元测试、集成测试）？
• 手动验证: 执行哪些步骤可以快速验证功能闭环？

7. 性能考虑

• 性能指标: QPS、响应时间等
• 优化策略: 缓存、异步处理、数据库优化

### tasks_tpl.md

```markdown
# {Project Name} 任务清单

## 任务统计
- 总任务数：{N}
- P0 高优先级：{N}
- P1 中优先级：{N}
- P2 低优先级：{N}
- 预计工期：{N} 天

## 前端任务

### TASK-FE-001: {任务名称} [P0]
**优先级**: P0 | **状态**: 待开始 | **预估工时**: 2h | **依赖**: 无

**任务描述**：
1. xxx
2. xxx

**验收标准**：
- [ ] xxx
- [ ] xxx

**技术要点**：
- xxx

**注意事项**：
- xxx

[更多前端任务...]

## 后端任务

### TASK-BE-001: {任务名称} [P0]
**优先级**: P0 | **状态**: 待开始 | **预估工时**: 2h | **依赖**: 无

**任务描述**：
1. xxx
2. xxx

**验收标准**：
- [ ] xxx
- [ ] xxx

**技术要点**：
- xxx

**注意事项**：
- xxx

[更多后端任务...]

## 测试任务

> **重要**：测试任务使用 `qa-test-planner` 技能生成，包含测试计划、测试用例、回归测试套件等

### 测试任务分类

#### 1. 测试计划任务

### TASK-TEST-PLAN-001: 制定测试计划 [P0]
**优先级**: P0 | **状态**: 待开始 | **预估工时**: 2h | **依赖**: 无

**任务描述**：
1. 使用 `qa-test-planner` 技能生成测试计划
2. 定义测试范围和测试目标
3. 确定测试类型（功能测试、UI 测试、集成测试、性能测试、安全测试）
4. 确定测试环境和测试数据
5. 定义入口/出口标准
6. 识别测试风险和缓解措施

**验收标准**：
- [ ] 测试计划文档完整
- [ ] 测试范围明确（In Scope/Out of Scope）
- [ ] 测试类型定义清晰
- [ ] 测试环境要求明确
- [ ] 入口/出口标准定义完整
- [ ] 风险评估完成

**使用技能**：`qa-test-planner`

---

#### 2. 手动测试用例任务

### TASK-TEST-001: {功能模块} - 手动测试用例 [P0]
**优先级**: P0 | **状态**: 待开始 | **预估工时**: 3h | **依赖**: TASK-TEST-PLAN-001

**任务描述**：
1. 使用 `qa-test-planner` 技能生成手动测试用例
2. 基于功能需求和用户场景设计测试用例
3. 包含正向测试和负向测试
4. 包含边界值测试和异常情况测试
5. 每个测试用例包含：测试步骤、预期结果、测试数据、前置条件

**验收标准**：
- [ ] 测试用例覆盖所有 P0 功能
- [ ] 测试用例步骤清晰、可执行
- [ ] 每个测试用例都有预期结果
- [ ] 包含边界值和异常情况测试
- [ ] 测试用例按优先级组织（P0/P1/P2）

**使用技能**：`qa-test-planner`

---

#### 3. 回归测试套件任务

### TASK-TEST-REGRESSION-001: 构建回归测试套件 [P1]
**优先级**: P1 | **状态**: 待开始 | **预估工时**: 2h | **依赖**: TASK-TEST-PLAN-001

**任务描述**：
1. 使用 `qa-test-planner` 技能构建回归测试套件
2. 定义冒烟测试（Smoke Tests，15-30 分钟）
3. 定义关键路径测试（Critical Path Tests）
4. 定义目标回归测试（Targeted Regression，30-60 分钟）
5. 定义完整回归测试（Full Regression，2-4 小时）
6. 确定测试执行顺序和依赖关系

**验收标准**：
- [ ] 冒烟测试覆盖核心功能
- [ ] 关键路径测试覆盖主要业务流程
- [ ] 回归测试套件按优先级组织
- [ ] 测试执行顺序合理
- [ ] 预估执行时间准确

**使用技能**：`qa-test-planner`

---

#### 4. UI/Figma 验证任务

### TASK-TEST-FIGMA-001: {页面名称} - Figma 设计验证 [P1]
**优先级**: P1 | **状态**: 待开始 | **预估工时**: 1h | **依赖**: 前端开发完成

**任务描述**：
1. 使用 `qa-test-planner` 技能进行 Figma 设计验证
2. 获取 Figma 设计规范（尺寸、颜色、字体、间距等）
3. 对比实现与设计规范
4. 检查 UI 一致性（颜色、字体、间距、圆角等）
5. 检查响应式布局
6. 记录差异并创建 Bug 报告（如有）

**验收标准**：
- [ ] Figma 设计规范获取成功
- [ ] 实现与设计对比完成
- [ ] UI 差异记录完整
- [ ] Bug 报告格式正确（如有差异）
- [ ] 响应式布局验证完成

**使用技能**：`qa-test-planner`（Figma MCP 集成）

---

#### 5. 测试执行任务

### TASK-TEST-EXECUTE-001: 执行测试并生成报告 [P0]
**优先级**: P0 | **状态**: 待开始 | **预估工时**: 4h | **依赖**: 所有测试任务

**任务描述**：
1. 执行所有 P0 测试用例
2. 执行冒烟测试和关键路径测试
3. 记录测试结果（通过/失败/阻塞）
4. 创建 Bug 报告（使用 `qa-test-planner`）
5. 生成测试报告（包含测试覆盖率、通过率、Bug 列表）
6. 提供测试结果评估（Go/No-Go 建议）

**验收标准**：
- [ ] 所有 P0 测试用例执行完成
- [ ] 测试结果记录完整
- [ ] Bug 报告清晰、可重现
- [ ] 测试报告包含所有必要信息
- [ ] 测试覆盖率达标
- [ ] 提供明确的测试结果评估

**使用技能**：`qa-test-planner`

---

[更多测试任务...]

## 部署任务

### TASK-DEPLOY-001: {任务名称} [P0]
**优先级**: P0 | **状态**: 待开始 | **预估工时**: 2h | **依赖**: 所有开发任务

**任务描述**：
1. xxx
2. xxx

**验收标准**：
- [ ] xxx
- [ ] xxx

[更多部署任务...]

Constraints

1. 严格遵守阶段顺序：不可跳过任何一个阶段
2. 每阶段必须暂停：等待用户确认后才进入下一阶段
3. 禁止提前编码：在 Phase 3 获得批准前，严禁编写任何功能代码
4. 保持模板结构：不要随意删减模板章节
5. 原子化任务：任务粒度必须足够小（单次对话可完成）
6. 强制 EARS 语法：验收标准必须使用 EARS 语法
7. 决策记录：设计文档必须包含完整的决策记录
8. 所有输出使用简体中文

与原 .codebuddy 流程的对比

优势

1. 更严格的流程控制：每个阶段都必须用户确认，减少返工
2. 标准化输出：使用模板确保文档质量和一致性
3. 原子化任务：任务粒度清晰，易于跟踪和执行
4. 完整的决策记录：重要的技术决策都有记录，便于维护
5. EARS 验收标准：使用标准化的验收标准，减少歧义
6. 减少文档数量：从 10 阶段整合为 5 阶段，聚焦核心

使用方式

方式1：一键式开发（推荐）

用户：我需要做一个移动端H5商城，包含商品列表、购物车、订单功能
spec-driven-development：自动执行 5 个阶段，每阶段需确认

方式2：分阶段推进

用户：Phase 1：需求定义
spec-driven-development：执行 Phase 1，生成 requirements.md
用户：确认
用户：Phase 2：架构设计
...

方式3：按需调用

直接调用对应的智能体和技能，但要遵守 5 个阶段的约束。