名称: 规格说明书撰写描述: 编写技术规格，为代理提供足够上下文以实现功能，同时留出自主研究和决策空间。用于计划功能、记录架构决策或创建实施指南时。

规格说明书撰写

遵循写作风格处理散文部分。

规格说明书为代理（或人类）提供自主实现功能所需的上下文。目标不是详尽描述一切；而是提供足够的初始上下文，让实施者可以自行研究并做出明智决策。

注意：本指南使用[占位符]标记您必须填写的内容。代码块显示模板；将所有括号内容替换为功能的详细信息。

核心理念

规格应：

提供上下文，而非指令：给出“为什么”和“什么”，让实施者决定“如何”
记录研究，而非结论：展示已探索的内容、现有内容、缺失内容
留出开放问题：开放问题部分是一个特性，而非缺陷
支持自主实施：阅读此规格的代理应能产生子代理以验证和扩展

好的规格是启动平台，而非要遵循的脚本。

文档结构

头部（必需）

# [功能名称]

**日期**: [YYYY-MM-DD]
**状态**: 草稿 | 进行中 | 已实现
**作者**: [姓名或AI辅助]
**分支**: [可选：如果工作已开始，feat/功能名称]

概述

最多一段。描述功能的作用。不要推销。

## 概述

[一到两句话描述此功能添加或改变的内容及其启用能力。具体说明能力，而非模糊好处。]

动机

结构为当前状态 → 问题 → 期望状态。

## 动机

### 当前状态

[显示实际代码或配置，演示当前工作方式。使用真实代码块，而非散文描述。]

这造成问题：

1. **[问题标题]**: [具体解释什么中断或痛苦]
2. **[问题标题]**: [具体解释什么中断或痛苦]

### 期望状态

[目标状态的简要描述。可包括显示理想API或结构的代码片段。]

研究发现

这是规格的亮点部分。记录您发现的内容，而非假设。

## 研究发现

### [研究主题]

[描述您调查的内容和方法]

| [类别]    | [维度1]  | [维度2]    |
| ------------- | -------------- | ---------------- |
| [项目/库] | [它们做什么] | [它们的方法] |
| [项目/库] | [它们做什么] | [它们的方法] |

**关键发现**: [您的主要发现—可能没有标准存在，或所有人都做X]

**影响**: [这对您的设计决策意味着什么]

包括：

类似项目做什么（比较表格）
您搜索但未找到的内容（“无既定模式存在”）
您查阅的文档链接或参考

设计决策

使用表格进行可追溯性。每个决策都应有理由。

## 设计决策

| 决策            | 选择           | 理由                       |
| ------------------- | ---------------- | ------------------------------- |
| [决策点]    | [您选择的] | [为什么选择此而非替代方案]    |
| [决策点]    | [您选择的] | [为什么选择此而非替代方案]    |
| [延迟决策] | 延迟         | [为什么目前超出范围] |

架构

图表优于散文。使用ASCII艺术可视化关系。

## 架构

[描述图表显示的内容]

┌─────────────────────────────────────────┐ │ [组件名称] │ │ ├── [字段]: [类型或值] │ │ └── [字段]: [类型或值] │ └─────────────────────────────────────────┘ │ ▼ [关系标签] ┌─────────────────────────────────────────┐ │ [组件名称] │ └─────────────────────────────────────────┘

对于多步骤流程：

步骤1: [步骤名称] ──────────────────── [此步骤发生什么]

步骤2: [步骤名称] ──────────────────── [此步骤发生什么]


### 实施计划

分解为阶段。使用复选框跟踪。阶段1应详细；后续阶段可较粗略（实施者将充实）。

```markdown
## 实施计划

### 阶段1: [阶段名称]

- [ ] **1.1** [具体、原子任务]
- [ ] **1.2** [具体、原子任务]
- [ ] **1.3** [具体、原子任务]

### 阶段2: [阶段名称]

- [ ] **2.1** [高级任务—实施者将分解]
- [ ] **2.2** [高级任务]

边缘案例

列出可能打破假设或需要特殊处理的场景。

## 边缘案例

### [场景名称]

1. [初始条件]
2. [发生什么]
3. [预期结果或“见开放问题”]

### [场景名称]

1. [初始条件]
2. [发生什么]
3. [预期结果]

开放问题

此部分向实施者信号“您决定此”。包括您的建议但不关闭问题。

## 开放问题

1. **[关于未解决设计决策的问题]**
   - 选项: (a) [选项A], (b) [选项B], (c) [选项C]
   - **推荐**: [您的建议及原因，但明确留出开放]

2. **[另一个未解决疑问]**
   - [关于此为何不确定的上下文]
   - **推荐**: [建议或“延迟直到X”]

成功标准

我们如何知道完成？验证复选框。

## 成功标准

- [ ] [具体、可验证结果]
- [ ] [具体、可验证结果]
- [ ] [测试通过 / 构建成功 / 文档更新]

参考

将触及或查阅的文件。

## 参考

- `[路径/到/文件.ts]` - [为什么此文件相关]
- `[路径/到/模式.ts]` - [遵循或参考的模式]

好与坏规格

好规格特点

研究有记录: 展示已探索内容，不仅结论
决策有理由: 每个选择在表格中有“为什么”
问题留开放: 实施者有决定空间
代码显示当前状态: 非抽象描述
架构可视化: ASCII图表优于散文
阶段可操作: 可跟踪的复选框

坏规格特点

处方性步骤: 像教程，无自主空间
无研究假设: “我们将使用X”而未探索替代方案
关闭所有问题: 无开放问题部分
抽象描述: “系统将处理Y”而未显示代码
散文墙: 无表格、无图表、无结构

为代理实施者写作

当代理阅读您的规格时，它们应：

从动机部分理解问题
从研究发现知道已探索内容
从设计决策看到建议方向
从实施计划阶段1有起点
从开放问题知道进一步调查内容

然后代理将：

产生子代理以验证您的研究
探索您留出的开放问题
充实实施计划的后续阶段
在您留出空间处做出决策

如果您的规格太处方性，代理将盲目遵循。如果太模糊，代理将困惑。甜点是：足够上下文以开始，足够开放以拥有实施。

快速参考清单

- [ ] 头部（日期、状态、作者）
- [ ] 概述（1-2句）
- [ ] 动机
  - [ ] 当前状态（带代码）
  - [ ] 问题（编号）
  - [ ] 期望状态
- [ ] 研究发现
  - [ ] 比较表格
  - [ ] 关键发现
  - [ ] 影响
- [ ] 设计决策（带理由表格）
- [ ] 架构（ASCII图表）
- [ ] 实施计划（阶段复选框）
- [ ] 边缘案例
- [ ] 开放问题（带推荐）
- [ ] 成功标准
- [ ] 参考

并非每个规格需要每个部分。小功能可能跳过研究发现。迁移规格可能重点在边缘案例。使用判断。

名称: 规格说明书撰写 描述: 编写技术规格，为代理提供足够上下文以实现功能，同时留出自主研究和决策空间。用于计划功能、记录架构决策或创建实施指南时。