# Spec 工作流说明

## 简介

CloudBase AI ToolKit 内置了 Kiro 风格的 Spec 工作流，旨在让 AI 编程过程更加工程化、规范化，提升需求梳理、设计、开发、验收的全流程体验。现在支持灵活的斜杠命令控制，让用户可以根据任务复杂度选择合适的开发模式。

## 工作流理念

- **工程化**：将需求、设计、任务分明，避免"拉霸式" vibe coding。
- **可追溯**：每一步都有文档记录，便于回溯和团队协作。
- **AI 协作**：AI 负责梳理需求、设计方案、拆分任务，人类专注决策与评审。
- **自动生成**：自动生成 requirements.md、design.md、tasks.md 等规范文档。
- **灵活控制**：支持斜杠命令控制，智能判断任务复杂度。

## 工作流控制

### 斜杠命令系统

CloudBase AI ToolKit 提供了灵活的斜杠命令来控制工作流：

- **`/spec`** - 强制使用完整 spec 流程（需求文档、技术方案、任务拆分）
- **`/no_spec`** - 跳过 spec 流程，直接执行任务
- **`/help`** - 显示 workflow 命令帮助
- **默认** - AI 根据任务复杂度智能判断

### 智能判断机制

AI 会根据任务复杂度自动选择合适的开发模式：

**使用 spec 流程的场景：**
- 新功能开发
- 复杂架构设计
- 多模块集成
- 涉及数据库设计
- 涉及用户界面设计
- 涉及第三方服务集成

**跳过 spec 流程的场景：**
- 简单 bug 修复
- 文档更新
- 配置修改
- 代码重构
- 性能优化
- 测试用例编写

## 工作流流程

### Spec 流程（/spec 或智能判断使用）

1. **需求梳理**
   - 采用 EARS（简易需求语法）方法，AI 协助用户梳理需求，生成 `requirements.md`。
2. **技术方案设计**
   - 基于需求，AI 生成技术架构、技术选型、接口/数据库设计等，形成 `design.md`。
3. **任务拆分**
   - 按照需求和设计，AI 拆分具体开发任务，生成 `tasks.md`。
4. **自动执行与追踪**
   - AI 根据任务清单自动推进开发，实时更新任务状态。

### No-Spec 流程（/no_spec 或智能判断跳过）

1. **直接分析任务需求**
2. **快速制定执行计划**
3. **直接执行任务**
4. **保持代码质量和项目规范**
5. **必要时进行确认**

## 典型文件结构

```
specs/
  your-feature/
    requirements.md  # 需求文档
    design.md        # 技术方案设计
    tasks.md         # 任务拆分与进度
```

### requirements.md 示例

```markdown
# 需求文档

## 介绍

简要描述需求背景和目标。

## 需求

### 需求 1 - 需求名称

**用户故事：** 用户故事内容

#### 验收标准

1. While <可选前置条件>, when <可选触发器>, the <系统名称> shall <系统响应>
2. ...
```

### design.md 示例

```markdown
# 技术方案设计

- 架构图（可用 mermaid）
- 技术选型说明
- 数据库/接口设计
- 安全性与测试策略
```

### tasks.md 示例

```markdown
# 实施计划

- [ ] 1. 任务信息
  - 具体要做的事情
  - _需求: 相关的需求点编号
```

## 使用示例

### 强制使用 Spec 流程

**用户输入：**
```
/spec 开发一个用户管理系统
```

**AI 响应：**
```
🎯 Workflow 模式：Spec 流程

📋 判断依据：用户明确指定使用 /spec 命令
🔄 后续流程：将按照标准软件工程方式执行
  1. 需求澄清和确认
  2. 需求文档设计（requirements.md）
  3. 技术方案设计（design.md）
  4. 任务拆分（tasks.md）
  5. 执行任务并更新状态

✅ 确认：我将开始需求澄清阶段，请确认是否继续？
```

### 跳过 Spec 流程

**用户输入：**
```
/no_spec 修复登录按钮的样式问题
```

**AI 响应：**
```
🎯 Workflow 模式：No-Spec 流程

📋 判断依据：用户明确指定使用 /no_spec 命令
🔄 后续流程：将直接分析并执行任务
  1. 直接分析任务需求
  2. 快速制定执行计划
  3. 直接执行任务
  4. 保持代码质量和项目规范

⚠️ 注意：将跳过需求文档和技术方案设计阶段，直接执行修复任务
✅ 确认：我将开始分析登录按钮样式问题，请确认是否继续？
```

### 智能判断（默认）

**用户输入：**
```
开发一个复杂的电商购物车功能
```

**AI 响应：**
```
🎯 Workflow 模式：Spec 流程

📋 判断依据：任务涉及复杂功能开发（电商购物车）
🔄 后续流程：将按照标准软件工程方式执行
  1. 需求澄清和确认
  2. 需求文档设计（requirements.md）
  3. 技术方案设计（design.md）
  4. 任务拆分（tasks.md）
  5. 执行任务并更新状态

✅ 确认：我将开始需求澄清阶段，请确认是否继续？
```

## 与 AI IDE 的集成

- 支持 Cursor、Claude Code、WindSurf、CodeBuddy 等主流 AI IDE
- 通过内置规则和 MCP 工具，AI 可自动识别并执行 Spec 工作流
- 用户只需用自然语言描述需求，AI 自动生成并维护 Spec 文档
- 支持斜杠命令控制，提供灵活的开发模式选择

## 优势

- **规范化开发流程**：降低沟通和协作成本
- **灵活控制**：根据任务复杂度选择合适的开发模式
- **智能判断**：AI 自动判断是否需要使用 spec 流程
- **便于团队协作**：需求追溯和文档管理
- **支持自动化测试**：与持续集成流程集成
- **让 AI 真正成为开发流程的"助理工程师"**

## 最佳实践

### 选择合适的命令

**使用 /spec 的场景：**
- 新功能开发
- 复杂架构设计
- 多模块集成
- 涉及数据库设计
- 涉及用户界面设计
- 涉及第三方服务集成

**使用 /no_spec 的场景：**
- 简单 bug 修复
- 文档更新
- 配置修改
- 代码重构
- 性能优化
- 测试用例编写

### 智能判断的使用

**建议：**
- 不确定时可以不指定命令，让 AI 智能判断
- 观察 AI 的判断依据，了解其逻辑
- 如果判断不准确，可以手动指定命令

### 质量保证

**注意事项：**
- /no_spec 模式仍需要遵循项目规范
- 复杂任务建议使用 /spec 确保质量
- 任何模式下都需要用户确认重要操作
- 保持代码质量和可维护性

## 典型用法

1. 用户在 AI IDE 中输入需求（可选择使用斜杠命令）
2. AI 根据命令或智能判断选择合适的开发模式
3. 如果使用 spec 流程，AI 自动生成 specs/your-feature/ 下的 requirements.md、design.md、tasks.md
4. 用户确认后，AI 按流程推进开发并持续更新任务状态
5. 开发完成后，所有文档可用于评审、归档和后续维护

---

如需进一步了解 Spec 工作流或遇到问题，欢迎查阅[官方文档](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/development)或加入技术交流群。 
