规范 (Spec)

规范（Spec）是 OpenSpec 的核心概念。它们描述了系统当前的行为，是系统的行为源真相。

规范文件结构

规范文件使用 Markdown 格式，包含规范标题、目的和需求。

基本结构

# <领域> 规范

## Purpose
描述此规范的目的和范围。

## Requirements

### Requirement: <需求名称>
需求描述。

#### Scenario: <场景名称>
- GIVEN <初始条件>
- WHEN <动作>
- THEN <期望结果>
- AND <额外期望结果>

示例

# Authentication Specification

## Purpose
Authentication and session management for the application.

## Requirements

### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.

#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard

#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed

需求关键词

规范使用标准关键词来指示需求的类型：

关键词	含义	使用场景
SHALL	必须	强制性需求
SHOULD	应该	推荐性需求
MAY	可以	选择性需求

场景格式

每个需求可以包含多个场景，使用 Given/When/Then 格式：

Given（初始条件）

描述场景的初始状态。

- GIVEN a user with valid credentials
- GIVEN a logged-in user

When（动作）

描述触发场景的动作。

- WHEN the user submits login form
- WHEN the user clicks the logout button

Then（期望结果）

描述期望的结果。

- THEN a JWT token is returned
- THEN the user is redirected to dashboard
- AND the user is logged out

组织规范

规范应该按领域组织：

openspec/specs/
├── auth/          # 认证领域
│   └── spec.md
├── payments/      # 支付领域
│   └── spec.md
├── notifications/ # 通知领域
│   └── spec.md
└── ui/            # UI 领域
    └── spec.md

编写规范的最佳实践

1. 具体明确 - 避免模糊的语言
2. 可测试 - 每个需求应该是可测试的
3. 独立 - 规范之间应该相互独立
4. 完整 - 每个需求应该包含所有必要的场景
5. 更新 - 随着系统演变更新规范

规范编辑

规范可以随时编辑。OpenSpec 鼓励在实施过程中根据学习到的信息更新规范。

下一步

• 变更 (Change) - 了解变更的概念
• Delta 规范 - 了解如何指定变更
• 使用指南 - 开始创建变更