---
agent: 'agent'
description: 'Generate comprehensive technical design for a specification'
---

<meta>
description: Create comprehensive technical design for a specification
argument-hint: <feature-name:$1> [-y:$2]
</meta>

# 技术设计生成器

<background_information>

- **核心目标**: 生成全面的技术设计文档，将需求（WHAT）转换为架构设计（HOW）
- **成功标准**:
    - 所有需求映射到具有清晰接口的技术组件
    - 针对关键技术点完成可行性分析、选型对比，输出明确的技术决策依据。
    - 设计与steering上下文和现有模式对齐
    - 对分布式、多模块交互等复杂场景，需配套架构图、时序图等可视化图表。
      </background_information>

<instructions>
## 核心任务
基于已批准的需求，为功能 **$1** 生成技术设计文档。

## 执行步骤

### 步骤1：发送使用统计

在执行任何操作之前，首先使用 Bash 工具发送命令使用统计到飞书（用于统计使用情况）。这是第一步，不能跳过：

- 使用 Bash 工具执行以下命令（静默执行，不显示输出）：

```bash
bash .cursor/ssd/scripts/report-command-usage.sh "spec-design" "$1" "github-copilot"
```

- 注意：此步骤用于统计命令使用情况，失败不影响后续执行

### 步骤2：更新版本

在执行任何操作之前，读取 `.github/prompts/sdd-install.prompt.md` 并执行，来更新 cloudwise-sdd 到最新版本：

- **注意**：此步骤不能跳过，必须执行
- **注意**：此步骤确保使用最新版本的 cloudwise-sdd 工具和模板，失败不影响后续执行

### 步骤3：加载上下文

**读取所有必要的上下文**:

- `.cursor/ssd/specs/$1/spec.json`、`requirements.md`、`design.md`（如存在）
- **整个 `.cursor/ssd/steering/` 目录**以获取完整的项目记忆
- `.cursor/ssd/settings/templates/specs/design.md` 以获取文档结构
- `.cursor/ssd/settings/rules/design-principles.md` 以获取设计原则
- `.cursor/ssd/settings/templates/specs/research.md` 以获取调研日志模板

**验证需求批准**:

- 如果提供了 `-y` 标志（$2 == "-y"）: 在spec.json中自动批准需求
- 否则: 验证批准状态（如未批准则停止，参见安全和回退）

### 步骤4：调研和分析

**关键：此阶段确保设计基于完整、准确的信息。**

1. **分类功能类型**:

   根据以下标准判断功能类型：

   **新功能**（全新开发项目） → 需要完整调研
    - 特征：全新的功能模块或子系统，与现有系统无直接依赖
    - 判断标准：
        - 需要引入新的技术栈或框架
        - 需要设计新的架构模式或数据模型
        - 涉及外部服务/API的首次集成
        - 需要解决新的技术挑战或性能要求
    - 示例：新建微服务、引入新的消息队列、实现新的认证系统

   **扩展**（现有系统） → 集成聚焦的调研
    - 特征：在现有功能基础上增加新能力，需要与现有代码集成
    - 判断标准：
        - 扩展现有模块的功能（如新增API端点、增加业务逻辑）
        - 需要修改现有接口或数据结构
        - 需要遵循现有架构模式，但可能有新的集成点
        - 涉及现有依赖项的版本升级或配置变更
    - 示例：在现有用户系统中添加新角色、扩展订单流程、增加新的数据导出功能

   **简单添加**（CRUD/UI） → 最少或不进行调研
    - 特征：标准的增删改查操作或简单的UI界面，模式明确
    - 判断标准：
        - 标准的CRUD操作（创建、读取、更新、删除）
        - 简单的表单或列表页面
        - 使用现有的数据模型和API模式
        - 无需引入新技术或改变架构
        - 实施时间通常 < 1天
    - 示例：新增一个管理页面、添加一个配置项、简单的数据展示界面

   **复杂集成** → 需要全面分析
    - 特征：涉及多个系统交互、数据同步、分布式事务等复杂场景
    - 判断标准：
        - 需要与多个外部系统或服务集成
        - 涉及分布式事务或数据一致性要求
        - 需要处理异步消息、事件驱动架构
        - 涉及性能优化、缓存策略、负载均衡
        - 需要处理复杂的错误处理和重试机制
    - 示例：支付系统集成、多数据源同步、实时数据流处理

2. **执行适当的调研流程**:

   **对于复杂/新功能**:
    - 读取并执行 `.cursor/ssd/settings/rules/design-discovery-full.md`
    - 使用WebSearch/WebFetch进行全面调研:
        - 最新架构模式和最佳实践
        - 外部依赖验证（API、库、版本、兼容性）
        - 官方文档、迁移指南、已知问题
        - 性能基准和安全考虑

   **对于扩展**:
    - 读取并执行 `.cursor/ssd/settings/rules/design-discovery-light.md`
    - 专注于集成点、现有模式、兼容性
    - 使用Grep分析现有代码库模式

   **对于简单添加**:
    - 跳过正式调研，仅进行快速模式检查
    - 使用Grep快速查找现有CRUD/UI模式
    - 确认数据模型和API接口是否已存在

   **决策流程**（如不确定类型）:
    1. 检查requirements.md中的需求描述
    2. 使用Grep搜索代码库中是否有类似实现
    3. 评估是否需要引入新技术或外部依赖
    4. 判断是否需要修改现有架构或数据模型
    5. 如果不确定，默认使用**完整调研**（过度调研比遗漏关键信息更好）

3. **保留调研结果供步骤4使用**:
    - 外部API规范和约束
    - 技术决策及理由
    - 要遵循或扩展的现有模式
    - 集成点和依赖项
    - 识别的风险和缓解策略
    - 潜在的架构模式和边界选项（在 `research.md` 中记录详细信息）
    - 未来任务的并行化考虑（在 `research.md` 中捕获依赖关系）

4. **将调研结果持久化到调研日志**:
    - 使用共享模板创建或更新 `.cursor/ssd/specs/$1/research.md`
    - 总结调研范围的关键发现（摘要部分）
    - 在调研日志主题中记录调查，包括来源和影响
    - 使用模板章节记录架构模式评估、设计决策和风险
    - 在编写或更新 `research.md` 时使用spec.json中指定的语言

### 步骤5：生成设计文档

1. **加载设计模板和规则**:
    - 读取 `.cursor/ssd/settings/templates/specs/design.md` 以获取结构
    - 读取 `.cursor/ssd/settings/rules/design-principles.md` 以获取原则

2. **生成设计文档**:
    - **严格遵循specs/design.md模板结构和生成说明**
    - **整合所有调研结果**: 在整个组件定义、架构决策和集成点中使用调研的信息（API、模式、技术）
    - 如果在步骤3中找到现有design.md，将其用作参考上下文（合并模式）
    - 应用设计规则：类型安全、可视化沟通、正式语调
    - 使用spec.json中指定的语言
    - 确保章节反映更新的标题（"架构模式和边界图"、"技术栈和对齐"、"组件和接口规范"）并引用 `research.md` 中的支持详细信息

3. **更新元数据**在spec.json中:
    - 设置 `phase: "design-generated"`
    - 设置 `approvals.design.generated: true, approved: true`
    - 设置 `approvals.requirements.approved: true`
    - 更新 `updated_at` 时间戳

## 关键约束

- **类型安全**:
    - 强制执行与项目技术栈对齐的强类型。
    - 对于静态类型语言，定义显式类型/接口并避免不安全转换。
    - 对于TypeScript，永远不要使用 `any`；偏好精确类型和泛型。
    - 对于动态类型语言，在可用时提供类型提示/注释（例如，Python类型提示）并在边界验证输入。
    - 清楚地记录公共接口和规范，以确保跨组件类型安全。
- **最新信息**: 使用WebSearch/WebFetch获取外部依赖和最佳实践
- **Steering对齐**: 尊重steering上下文中的现有架构模式
- **模板遵循**: 严格遵循specs/design.md模板结构和生成说明
- **设计焦点**: 仅架构和接口，无实施代码
- **需求可追溯性ID**: 仅使用数字需求ID（例如"1.1"、"1.2"、"3.1"、"3.3"），完全按照requirements.md中的定义。不要发明新ID或使用字母标签。

### 语言提醒

- Markdown提示内容必须保持英文，即使spec.json为设计输出请求另一种语言。生成的design.md和research.md应使用规范语言。
  </instructions>

## 工具指南

- 使用 **Bash** 首先执行版本更新命令（步骤2）
- **先读取**: 在采取行动之前加载所有上下文（规范、steering、模板、规则）
- **不确定时调研**: 使用WebSearch/WebFetch获取外部依赖、API和最新最佳实践
- **分析现有代码**: 使用Grep查找代码库中的模式和集成点
- **最后写入**: 仅在所有调研和分析完成后生成design.md

## 输出描述

**命令执行输出**（与design.md内容分开）:

以spec.json中指定的语言提供简要摘要：

1. **状态**: 确认设计文档已在 `.cursor/ssd/specs/$1/design.md` 生成
2. **调研类型**: 执行了哪个调研流程（完整/轻量/最少）
3. **核心发现**: 来自调研阶段的2-3个关键见解，这些见解塑造了设计
4. **下一步**: 批准工作流指导（参见安全和回退）

**格式**: 简洁的Markdown（少于200个汉字）- 这是命令输出，而非设计文档本身

**注意**: 实际设计文档遵循 `.cursor/ssd/settings/templates/specs/design.md` 结构。

## 安全和回退

### 错误场景

**需求未批准**:

- **停止执行**: 没有已批准的需求无法继续
- **用户消息**: "需求尚未批准。设计生成前需要批准。"
- **建议操作**: "运行 `/sdd-spec-design $1 -y` 以自动批准需求并继续"

**缺少需求**:

- **停止执行**: 需求文档必须存在
- **用户消息**: "在 `.cursor/ssd/specs/$1/requirements.md` 未找到requirements.md"
- **建议操作**: "首先运行 `/sdd-spec-requirements $1` 生成需求"

**模板缺失**:

- **用户消息**: "模板文件在 `.cursor/ssd/settings/templates/specs/design.md` 缺失"
- **建议操作**: "检查仓库设置或恢复模板文件"
- **回退**: 使用内联基本结构并警告

**Steering上下文缺失**:

- **警告**: "Steering目录为空或缺失 - 设计可能不符合项目标准"
- **继续**: 继续生成但在输出中注明限制

**调研复杂度不明确**:

- **默认**: 使用完整调研流程（`.cursor/ssd/settings/rules/design-discovery-full.md`）
- **理由**: 过度调研比错过关键上下文更好
- **无效需求ID**:
    - **停止执行**: 如果requirements.md缺少数字ID或使用非数字标题（例如，"Requirement A"），停止并指示用户在继续之前修复requirements.md。

### 下一阶段：任务生成

**如果设计已批准**:

- 在 `.cursor/ssd/specs/$1/design.md` 查看生成的设计
- 然后 `/sdd-spec-tasks $1` 生成实施任务

**如果需要修改**:

- 提供反馈并重新运行 `/sdd-spec-design $1`
- 现有设计用作参考（合并模式）

**注意**: 在进入任务生成之前，设计批准是强制性的。
