Chapter 3：Spec 规范文件格式
学习目标
- 掌握 OpenSpec Spec 文件的标准结构
- 理解 YAML 前置元数据的作用
- 熟练编写 Requirement（需求项）
- 理解 OpenSpec 的 Markdown + YAML 混合格式
概念讲解（Why）
什么是 Spec 文件
在 SDD 范式中，Spec 文件是描述系统功能的"规范说明书"。它不是传统的需求文档，而是一份结构化的、机器可解析的、包含明确验收标准的文档。
OpenSpec 选择 Markdown 作为 Spec 文件的主要格式，原因有三：
- 可读性：Markdown 对人类友好，便于评审和协作
- 可解析性：通过 YAML front matter 可以提取结构化数据
- 灵活性：支持嵌入代码块、图表等富文本内容
为什么需要标准化结构
如果每个开发者按照自己的喜好编写规范，AI 解析规范的难度会增加。OpenSpec 定义了标准化的 Spec 文件结构，确保无论谁编写规范，AI 都能一致地理解和解析。
原理分析（How）
Spec 文件标准结构
一个完整的 Spec 文件包含以下部分：
--- title: 模块名称 version: 1.0.0 status: draft | review | approved | implemented domain: 所属领域 owner: 负责人 created: 创建日期 updated: 更新日期 --- # 模块名称 ## 概述 [用一到两段话描述模块的核心功能] ## 功能范围 ### 包含 - [明确列出包含的功能点] ### 不包含 - [明确列出不包含的功能点] ## 需求项 ### Requirement: 功能点名称 #### 描述 [详细描述该功能点的需求] #### 验收标准 - [ ] 标准1 - [ ] 标准2 #### 优先级 - [ ] 高 - [ ] 中 - [ ] 低 #### 依赖 - [依赖的其他 Requirement 或 Spec] ## 接口定义 ### API 端点 #### POST /api/xxx **请求：** ```json { "field": "type (required/optional, 说明)" }响应：
- 200 OK：成功响应
- 400 Bad Request：参数错误
- 401 Unauthorized：未授权
数据模型
User
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | UUID | PK | 主键 |
| string | unique, not null | 邮箱 | |
| password | string | not null | 加密密码 |
错误处理
错误码
| 错误码 | 描述 | 处理方式 |
|---|---|---|
| E001 | 参数缺失 | 返回 400，提示具体字段 |
| E002 | 参数格式错误 | 返回 400，提示正确格式 |
| E003 | 资源不存在 | 返回 404 |
验收标准
- 所有需求项的验收标准都已实现
- API 响应符合接口定义
- 错误码覆盖完整
### YAML Front Matter 的作用 YAML front matter（`---` 之间的内容）用于存储规范文件的元数据，这些元数据可以被工具程序解析： ```yaml title: 用户认证模块 version: 1.0.0 # 语义化版本，用于变更追踪 status: draft # 草稿/评审中/已批准/已实现 domain: auth # 领域划分，便于分类管理 owner: zhangsan # 负责人，便于协作 created: 2026-04-28 # 创建日期 updated: 2026-04-28 # 最后更新日期Requirement 的原子性原则
每个 Requirement 应该描述一个独立的、原子性的功能点。好的 Requirement 应该满足以下标准：
- 完整性：描述清楚"做什么"，但不涉及"怎么做"
- 独立性：可以独立实现和测试，不依赖其他 Requirement
- 可验证性：有明确的验收标准，可以判断是否完成
