变更 (Change)

变更（Change）是 OpenSpec 中提议的修改。每个变更都存储在一个单独的文件夹中，包含所有相关的工件和增量规范。

变更结构

每个变更都有自己的文件夹，包含以下工件：

changes/<change-name>/
├── proposal.md       # 提案：为什么做这个变更
├── specs/            # 增量规范：什么在变化
├── design.md         # 设计：如何实现变更
└── tasks.md          # 任务：实施清单

变更文件夹结构

openspec/
├── specs/           # 源真相规范
│   └── <domain>/
│       └── spec.md
├── changes/         # 提议的修改
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/   # 增量规范
│           └── <domain>/
│               └── spec.md
├── config.yaml      # 项目配置（可选）
└── schemas/         # 自定义 schema

创建变更

使用默认快速路径

/opsx:propose add-dark-mode

这将创建一个完整的变更，包括所有必需的工件。

使用扩展工作流

/opsx:new add-dark-mode
/opsx:ff

这将创建变更的骨架，然后填充所有工件。

工件

每个变更包含以下工件：

1. 提案 (proposal.md)

提案解释了为什么要做这个变更以及它会改变什么。

# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context.

2. 增量规范 (specs/)

增量规范显示相对于当前规范的变化。

# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately

3. 设计 (design.md)

设计文档解释了如何实现变更。

# Design: Add Dark Mode

## Architecture
Use CSS custom properties for theming with a React context.

## Implementation Steps
1. ThemeContext with light/dark state
2. Add CSS custom properties to globals.css
3. Implement localStorage persistence
4. Create ThemeToggle component

4. 任务 (tasks.md)

任务列表提供了实施的检查清单。

# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties to globals.css
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page

变更状态

状态	描述
Active	当前进行中的变更
Archived	已完成并归档的变更
Cancelled	已取消的变更

管理变更

查看变更列表

openspec list

查看变更详情

openspec show add-dark-mode

验证规范格式

openspec validate add-dark-mode

归档变更

/opsx:archive

最佳实践

1. 一个变更一个主题 - 保持变更聚焦
2. 完整工件 - 确保所有必要工件都已创建
3. 及时归档 - 完成后及时归档变更
4. 清晰命名 - 使用清晰的变更名称

下一步

• Delta 规范 - 了解如何指定变更
• 工件 (Artifact) - 了解所有工件类型
• 使用指南 - 开始创建变更