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字段类型约束说明idUUIDPK主键emailstringunique, not null邮箱passwordstringnot 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可验证性：有明确的验收标准，可以判断是否完成