## Spec

**「在编写代码之前赋予结构」** - 完全遵循 Kiro 的规格驱动开发

与传统代码生成工具不同，实现 Kiro 的规格驱动开发，重点是为开发的混沌赋予结构。从最少的需求输入，逐步展开到产品经理级别的详细规格和可实施的设计，**从原型到生产环境**保证一致的质量。

### 使用方法

```bash
# 请求 Claude 的 Spec Mode(最少需求输入)
「创建[功能描述]的 spec」

# Kiro 式分阶段展开：
# 1. 简单需求 → 自动生成详细用户故事
# 2. 使用 EARS 记法的结构化需求描述
# 3. 通过分阶段对话精细化规格
# 4. 生成 3 个独立文件：
#    - requirements.md: EARS 记法的需求定义
#    - design.md: 包含 Mermaid 图、TypeScript 接口的设计
#    - tasks.md: 自动应用最佳实践的实施计划
```

### 实证效果 (Kiro 实绩)

**2 天完成安全文件共享应用**

```bash
「创建文件共享系统 (支持加密) 的 spec」
→ 2 天完成生产级别的加密文件共享应用
→ 自动应用安全最佳实践
→ 无需额外提示
```

**新手一晚开发游戏**

```bash
「创建 2D 益智游戏的 spec」
→ 游戏开发新手的开源开发者
→ 一晚完成游戏创建
→ 实现逻辑由 Kiro 处理，开发者专注创造性
```

**周末从原型到生产**

```bash
「创建电商网站商品管理系统的 spec」
→ 一个周末从概念到可运行的原型
→ 从原型到生产环境的一致质量
→ 通过 spec-driven development 的结构化方法
```

### 基本示例

```bash
# 新功能的 spec 创建 (最少输入)
「商品评论系统
- 星级评分功能
- 评论发布
- 图片上传」

# 系统功能的 spec 创建
「用户认证
- OAuth 支持
- 多因素认证」

# API 功能的 spec 创建
「支付系统 API
- Stripe 集成
- 重视安全性」
```

### 与 Claude 配合

```bash
# 复杂功能 spec
「创建聊天功能的 spec。包括 WebSocket、实时通知、历史管理」

# 数据库关联功能 spec
「创建电商网站库存管理功能的 spec。包括商品添加、库存更新、警报功能」

# 前端功能 spec
「创建 React 仪表板的 spec。包括图表显示、筛选器、导出功能」

# 后端功能 spec
「创建 RESTful API 的 spec。包括认证、验证、日志记录」
```

### Spec Mode 的特点

**分阶段对话工作流**

- 完全再现 Kiro 的核心价值——分阶段讨论
- 在各阶段与用户合作精细化规格
- 经过疑问解决、选项讨论、批准流程后生成文件

**3 阶段的交互式展开**

- **Phase 1**: Requirements Discovery → 讨论 → 批准 → 生成 `requirements.md`
- **Phase 2**: Design Exploration → 讨论 → 批准 → 生成 `design.md`
- **Phase 3**: Implementation Planning → 讨论 → 批准 → 生成 `tasks.md`

**动态规格制定**

- 通过对话解决需求的模糊性
- 提示和讨论技术选项
- 说明权衡并确认判断

### 详细示例

```bash
# 复杂系统功能
「创建在线支付系统的 spec。包括 Stripe 集成、安全性、错误处理」

# 前端功能
「创建 React 组件的 spec。包括状态管理、属性设计、测试」

# 后端功能
「创建 GraphQL API 的 spec。包括 Schema 设计、解析器、认证」

# DevOps 功能
「创建 CI/CD 管道的 spec。包括测试自动化、部署、监控」
```

### 分阶段对话工作流 (Phase by Phase)

#### Phase 1: Requirements Discovery & Discussion

**1. 从最少输入自动扩展 (Kiro 式)**

```text
用户：「用户管理系统
- 登录功能
- 个人资料编辑
- 管理员权限」

Claude：「从需求生成详细用户故事。
这个理解正确吗？

自动生成的用户故事：
- 用户注册和认证功能 (支持 OAuth)
- 个人资料管理功能 (头像、设置)
- 权限管理功能 (RBAC)
- 密码重置功能
- 安全审计日志

已补充未明确的细节。还需要其他功能吗？」
```

**2. 使用 EARS 记法的结构化需求描述**

```text
Claude：「使用 Kiro 的 EARS 记法结构化需求：

EARS 记法需求定义：

WHEN 用户尝试登录时
GIVEN 输入正确的邮箱和密码
THEN 系统确认认证
AND 成功时重定向到仪表板

WHILE 用户在个人资料编辑页面时
THE SYSTEM SHALL 实时执行验证
AND 预览显示更改内容

WHERE 需要管理员权限的功能
IS 尝试访问时
THE SYSTEM SHALL 确认权限级别
AND 不足时拒绝访问」
```

**3. 边缘情况和安全需求的自动补充**

```text
Claude：「基于 Kiro 的最佳实践，还考虑了以下情况：

安全需求 (自动补充)：
- 暴力攻击对策
- 会话管理和超时
- CSRF 保护和 XSS 对策
- 密码强度要求

边缘情况 (自动检测)：
- 同时登录限制
- 账户锁定功能
- 数据迁移时的一致性保证
- 大量请求时的负载均衡

这些需求合适吗？」
```

**5. Phase 1 完成和批准**

```text
Claude：「Requirements Phase 已完成。
可以生成 requirements.md 吗？」
→ 「继续」→ 生成 requirements.md
```

#### Phase 2: Design Exploration & Discussion

**1. 代码库分析 + 自动设计建议 (Kiro 式)**

```text
Claude：「分析现有代码库，提出最佳架构：

代码库分析结果：
- 认证：JWT + Express.js(v4.18.x)
- 数据库：PostgreSQL(v14+)
- 前端：React + TypeScript(v18+)
- 现有模式：Repository 模式、Service 层分离

Kiro 推荐架构：
- 符合 Clean Architecture
- Domain-Driven Design 元素
- 部分应用 CQRS 模式
- 自动化的安全最佳实践

使用这个设计吗？」
```

**2. 使用 Mermaid 图的可视化设计**

```text
Claude：「自动生成系统设计的 Mermaid 图：

自动生成的架构图：

graph TB
    Client[React Client] --> API[Express API Gateway]
    API --> Auth[Auth Service]
    API --> User[User Service]
    API --> Profile[Profile Service]

    Auth --> AuthDB[(Auth Database)]
    User --> UserDB[(User Database)]
    Profile --> ProfileDB[(Profile Database)]

    Auth --> JWT[JWT Service]
    Auth --> OAuth[OAuth Provider]

还需要生成数据流图吗？」
```

**3. TypeScript 接口自动生成**

```text
Claude：「基于设计自动生成 TypeScript 接口：

自动生成的 TypeScript 接口：

// Domain entities
interface User {
  readonly id: UserId;
  readonly email: Email;
  readonly profile: UserProfile;
  readonly auth: AuthSettings;
  readonly permissions: Permission[];
  readonly createdAt: Date;
  readonly updatedAt: Date;
}

interface UserProfile {
  readonly displayName: string;
  readonly avatar: AvatarUrl;
  readonly preferences: UserPreferences;
}

interface AuthSettings {
  readonly passwordHash: PasswordHash;
  readonly mfaEnabled: boolean;
  readonly lastLoginAt: Date;
  readonly failedAttempts: number;
}

// Use cases
interface UserRepository {
  findById(id: UserId): Promise<User | null>;
  findByEmail(email: Email): Promise<User | null>;
  save(user: User): Promise<void>;
}

interface AuthenticationService {
  authenticate(credentials: LoginCredentials): Promise<AuthResult>;
  refreshToken(token: RefreshToken): Promise<AccessToken>;
}

使用这个接口设计吗？」
```

**4. Phase 2 完成和批准**

```text

Claude：「Design Phase 已完成。
可以生成 design.md 吗？」
→ 「继续」→ 生成 design.md

```

#### Phase 3: Implementation Planning & Discussion

**1. 最佳实践自动应用 (Kiro 式)**

```text

Claude：「生成了自动应用 Kiro 最佳实践的实施计划：

自动生成的实施策略：

1. 安全第一开发
   - 自动集成 OWASP Top 10 对策
   - 自动实现加密和哈希
   - 自动生成安全测试

2. 强制清洁架构
   - 自动实现层分离
   - 自动应用依赖倒置
   - 强制可测试设计

3. 性能优化
   - 自动实现缓存策略
   - 数据库优化
   - 利用异步处理

使用这个方法吗？」

```

**2. 质量检查点自动设置**

```text

Claude：「自动设置各实施阶段的质量检查点：

自动质量保证流程：

Phase 3a: 后端实施

- [ ] 安全扫描 (SAST/DAST)
- [ ] API 规范测试 (OpenAPI 合规)
- [ ] 性能测试 (负载和响应)
- [ ] 漏洞扫描 (依赖关系和 CVE)

Phase 3b: 前端实施

- [ ] 无障碍测试 (WCAG 2.1 AA)
- [ ] 浏览器兼容性测试
- [ ] 响应式设计验证
- [ ] 安全头确认

Phase 3c: 集成和部署

- [ ] E2E 测试套件
- [ ] CI/CD 管道配置
- [ ] 监控和日志设置
- [ ] 生产环境安全审计

全部自动执行。有额外的质量标准吗？」

```

**3. 依赖关系和风险缓解的自动分析**

```text

Claude：「自动分析实施顺序和风险缓解策略：

优化的实施顺序：

Week 1: 基础设施和安全基础

- 数据库设计和模式创建
- 认证基础 (JWT + 会话管理)
- 安全中间件实施
- 基本 API 端点

Week 2: 核心功能实施

- 用户管理功能
- 个人资料管理功能
- 权限管理系统
- 验证和错误处理

Week 3: 高级功能和优化

- 多因素认证实施
- 审计日志功能
- 性能优化
- 前端集成

自动检测的风险缓解策略：

- 多因素认证：分阶段引入 (SMS→应用认证)
- 会话管理：Redis 集群配置
- 大量访问：速率限制 + CDN 利用
- 数据一致性：加强事务管理

这个计划没有问题吗？」

```

**4. Phase 3 完成和批准**

```text

Claude：「Implementation Planning Phase 已完成。
可以生成 tasks.md 吗？」
→ 「继续」→ 生成 tasks.md

```

### Kiro 特有的功能

**EARS 记法 (Easy Approach to Requirements Syntax)**

```text
# Kiro 标准的 EARS 记法模式

WHEN [情况・触发器]
GIVEN [前提条件]
THEN [系统行为]
AND [额外行为]

WHILE [状态・流程]
THE SYSTEM SHALL [必须行为]
AND [相关行为]

WHERE [功能・组件]
IS [条件・状态]
THE SYSTEM SHALL [对应行为]
```

**自动生成功能**

- **Mermaid 图**: 自动生成架构和数据流图
- **TypeScript 接口**: 基于设计自动创建类型定义
- **最佳实践**: 自动集成安全和性能对策
- **质量检查点**: 自动设置分阶段质量标准

**hooks 联动**

- 文件保存时的自动质量检查
- 自动应用代码标准
- 自动执行安全扫描
- 自动验证 OWASP Top 10 对策

**原型→生产质量保证**

- 通过结构化方法的一致设计
- 强制安全第一开发
- 自动应用可扩展架构
- 集成持续质量管理

### 注意事项

**适用范围**

- Spec Mode 最适合功能实施
- 简单修复或小规模更改使用常规实施形式
- 推荐用于新功能开发或复杂功能改造

**质量保证**

- 明确各阶段的完成标准
- 实施前的设计审查
- 包括测试和无障碍的全面质量标准

**执行注意事项**

- 解决需求的模糊性后再进入设计阶段
- 设计完成后生成实施任务
- 重视各阶段的批准流程

### 触发短语和控制

#### 分阶段工作流控制

**开始触发器**

- 「创建[功能名]的 spec」
- 「想用 spec 驱动开发[功能名]」
- 「从规格书设计[功能名]」

**阶段进度控制**

- **「继续」**: 完成当前阶段并生成文件，进入下一阶段
- **「修改」**: 在当前阶段内调整和改进内容
- **「重做」**: 从头开始当前阶段
- **「详细说明」**: 提供更详细的说明或选项
- **「跳过」**: 跳过当前阶段进入下一个 (不推荐)

**文件生成时机**

```text
Phase 1 完成 → 「继续」 → 生成 requirements.md
Phase 2 完成 → 「继续」 → 生成 design.md
Phase 3 完成 → 「继续」 → 生成 tasks.md
```

### 执行示例 (分阶段流程)

```bash
# 使用示例
用户：「创建用户管理系统的 spec」

# Phase 1: Requirements Discovery
Claude: [开始需求确认和讨论]
用户: [响应・讨论・修改]
Claude: 「Requirements Phase 已完成。可以继续吗？」
用户: 「继续」
→ 生成 requirements.md

# Phase 2: Design Exploration
Claude: [开始设计提案和讨论]
用户: [技术选择・架构讨论]
Claude: 「Design Phase 已完成。可以继续吗？」
用户: 「继续」
→ 生成 design.md

# Phase 3: Implementation Planning
Claude: [开始实施计划讨论]
用户: [优先级・风险・工时讨论]
Claude: 「Implementation Phase 已完成。可以继续吗？」
用户: 「继续」
→ 生成 tasks.md

# 完成
Claude: 「spec 驱动开发的准备已完成。可以开始实施。」
```

### 与 /plan 的区别

| 特征     | /plan            | /spec                                               |
| -------- | ---------------- | --------------------------------------------------- |
| 对象     | 一般实施计划     | 功能规格驱动开发                                    |
| 输出格式 | 单一计划文档     | 3 个独立文件 (requirements.md、design.md、tasks.md) |
| 需求定义 | 基本需求整理     | 使用 EARS 记法的详细验收标准                        |
| 设计     | 以技术选型为中心 | 基于代码库分析                                      |
| 实施     | 一般任务分解     | 考虑依赖关系的序列                                  |
| 质量保证 | 基本测试策略     | 全面质量要求 (测试、无障碍、性能)                   |
| 同步     | 静态计划         | 动态 spec 更新                                      |

### 推荐用例

**推荐使用 spec**

- 新功能开发
- 复杂功能改造
- API 设计
- 数据库设计
- UI/UX 实施

**推荐使用 plan**

- 系统整体设计
- 基础设施构建
- 重构
- 技术选型
- 架构变更