| name | sdd-spec |
| description | 将头脑风暴结论转化为结构化规格文档，包含需求、技术设计、任务拆解和决策记录。Use when user says "write spec", "写规格", "sdd spec", or wants to formalize a brainstormed idea into an implementable specification. Reads .plan/brainstorm.md if available. |
| argument-hint | Reference brainstorm output or describe the feature to spec |
| disable-model-invocation | true |
SDD Spec — 规格文档生成
将需求讨论结论转化为开发者可直接执行的结构化规格文档。
输入来源
按优先级：
.plan/brainstorm.md — 存在则优先基于此- 用户口头描述 — 无 brainstorm 文件时直接从描述开始
- 代码库探索 — 补充技术细节
两者都不充分时，先问 3 个以内关键问题，不强行生成半成品。
规格文档模板
写入 .plan/spec.md。模板设计原则：每个段落都有明确的下游消费者（implement 读什么、review 检查什么），去掉没人读的段落。
# 规格文档：<功能名称>
> 来源：[brainstorm](./brainstorm.md) / 用户直接描述
> 日期：YYYY-MM-DD
## 1. 目标与约束
**做什么**：一句话。
**不做什么**：防止范围蔓延。
**约束**：性能、兼容性、技术限制（如无则写"无"）。
## 2. 技术设计
### 架构决策
| 决策点 | 选择 | 理由 | 替代方案 |
|--------|------|------|----------|
| ... | ... | ... | ... |
### 接口设计
关键函数/类/API 签名（伪代码即可，implement 会读这部分）。
### 文件变更清单
| 文件 | 变更类型 | 说明 |
|------|----------|------|
| path/to/file | 新建/修改/删除 | 做什么 |
## 3. 验收标准
用编号列表，每条可测试：
1. Given ... When ... Then ...
2. ...
## 4. 任务拆解
按实现顺序排列。
### Ticket 1：<任务名>
- **目标**：一句话
- **涉及文件**：文件列表
- **实现要点**：关键步骤
- **验收方式**：如何确认完成
- **依赖**：无 / Ticket N
### Ticket 2：...
...
## 5. 决策日志
> 记录讨论过程中做出的关键决策，防止"为什么这样做"在对话腐烂中丢失。
> implement 阶段遇到疑问时回查这里。
| # | 决策 | 理由 | 日期 |
|---|------|------|------|
| D-1 | ... | ... | ... |
编写原则
- 可执行 — 每个 Ticket 小到一个 agent 可独立完成
- 无歧义 — 接口签名用代码而非自然语言
- 可验证 — 每个 Ticket 有明确验收方式
- 不写废话 — 不要"引言"、"背景介绍"等填充段落
任务拆解原则
- 每个 Ticket 独立可运行，不依赖隐式上下文
- 依赖关系显式声明
- 单 Ticket 不超过 200 行代码变更
- 太大则拆子任务
- 优先拆基础设施（数据模型、公共工具），再拆业务逻辑
复杂度升级（按需）
| 信号 | 升级动作 | 何时值得 |
|---|
| 接口设计涉及多模块交互 | 调 LSP findReferences 验证接口可行性 | 改公共 API、跨模块调用 |
| 变更影响面不确定 | 用 codegraph impact 分析影响范围 | 重构核心模块 |
| 方案需要压力测试 | 提示用户运行 /grill-me | 高风险、高不确定性 |
| 规格文档较长需要润色 | 派发「技术文档工程师」子智能体 | 对外发布的 API 文档 |
完成后
规格文档已生成到 .plan/spec.md。
- 想压力测试方案？用
/grill-me
- 开始实现？用
/sdd-implement
- 需要修改某个 Ticket？直接告诉我
