新手入门
本指南解释了在安装和初始化 OpenSpec 后它是如何工作的。有关安装说明，请参阅 [[[[主 README]]]]。
工作原理
OpenSpec 帮助您和您的 AI 编码助手在编写任何代码之前就构建内容达成一致。工作流遵循一个简单的模式：
┌────────────────────┐
│ Start a Change │ /opsx:new
│ (开始变更) │
└────────┬───────────┘
│
▼
┌────────────────────┐
│ Create Artifacts │ /opsx:ff or /opsx:continue
│ (创建工件：提案、 │
│ 规格、设计、任务) │
└────────┬───────────┘
│
▼
┌────────────────────┐
│ Implement Tasks │ /opsx:apply
│ (实施任务： │
│ AI 编写代码) │
└────────┬───────────┘
│
▼
┌────────────────────┐
│ Archive & Merge │ /opsx:archive
│ Specs │
│ (归档并合并规格) │
└────────────────────┘OpenSpec 创建什么
运行 openspec init 后，您的项目将拥有此结构：
openspec/
├── specs/ # 事实来源 (您系统的行为)
│ └── <domain>/
│ └── spec.md
├── changes/ # 提议的更新 (每个变更一个文件夹)
│ └── <change-name>/
│ ├── proposal.md
│ ├── design.md
│ ├── tasks.md
│ └── specs/ # 增量规格 (正在变更的内容)
│ └── <domain>/
│ └── spec.md
└── config.yaml # 项目配置 (可选)两个关键目录：
specs/- 事实来源。这些规格描述了您的系统当前的行为方式。按领域组织 (例如，specs/auth/,specs/payments/)。changes/- 提议的修改。每个变更都有自己的文件夹，其中包含所有相关工件。当变更完成时，其规格将合并到主specs/目录中。
理解工件
每个变更文件夹都包含指导工作的工件：
| 工件 | 目的 |
|---|---|
proposal.md | "为什么" 和 "什么" - 捕捉意图、范围和方法 |
specs/ | 显示 ADDED (新增)/MODIFIED (修改)/REMOVED (移除) 需求的增量规格 |
design.md | "如何" - 技术方法和架构决策 |
tasks.md | 带复选框的实施清单 |
工件相互构建：
proposal ──► specs ──► design ──► tasks ──► implement
▲ ▲ ▲ │
└───────────┴──────────┴────────────────────┘
update as you learn (边学边更新)您总是可以在实施过程中随着了解的深入回头完善早期的工件。
增量规格如何工作
增量规格 (Delta specs) 是 OpenSpec 中的关键概念。它们显示了相对于当前规格正在发生的变化。
格式
增量规格使用章节来指示变更类型：
markdown
# Delta for Auth (Auth 的增量)
## ADDED Requirements (新增需求)
### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.
#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
## MODIFIED Requirements (修改的需求)
### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
## REMOVED Requirements (移除的需求)
### Requirement: Remember Me
(Deprecated in favor of 2FA)归档时发生什么
当您归档变更时：
- ADDED 需求被追加到主规格中
- MODIFIED 需求替换现有版本
- REMOVED 需求从主规格中删除
变更文件夹移动到 openspec/changes/archive/ 以进行审计历史记录。
示例：您的第一个变更
让我们通过为应用程序添加暗黑模式来演示。
1. 开始变更
You: /opsx:new add-dark-mode
AI: Created openspec/changes/add-dark-mode/
Ready to create: proposal2. 创建工件
使用 /opsx:ff (快进) 一次性创建所有规划工件：
You: /opsx:ff
AI: Creating artifacts for add-dark-mode...
✓ proposal.md — why we're doing this, what's changing
✓ specs/ — requirements and scenarios
✓ design.md — technical approach
✓ tasks.md — implementation checklist
Ready for implementation!3. 创建了什么
proposal.md - 捕捉意图：
markdown
# Proposal: Add Dark Mode
## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.
## 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
for state management.specs/ui/spec.md - 显示新需求的增量：
markdown
# 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
- AND the preference persists across sessions
#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is usedtasks.md - 实施清单：
markdown
# Tasks
## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence
## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle
## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables4. 实施
You: /opsx:apply
AI: Working through tasks...
✓ 1.1 Created ThemeContext with light/dark state
✓ 1.2 Added CSS custom properties to globals.css
✓ 1.3 Implemented localStorage persistence
✓ 2.1 Created ThemeToggle component
...
All tasks complete!在实施过程中，如果您发现设计需要调整，只需更新工件并继续。
5. 归档
You: /opsx:archive
AI: Archiving add-dark-mode...
✓ Merged specs into openspec/specs/ui/spec.md
✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
Done! Ready for the next feature.您的增量规格现在已成为主规格的一部分，记录了您的系统如何工作。
验证和审查
使用 CLI 检查您的变更：
bash
# 列出活动变更
openspec list
# 查看变更详情
openspec show add-dark-mode
# 验证规格格式
openspec validate add-dark-mode
# 交互式仪表板
openspec view下一步
- [[[[工作流]]]] - 常用模式以及何时使用每个命令
- [[[[命令]]]] - 所有斜杠命令的完整参考
- [[[[概念]]]] - 对规格、变更和 Schema 的更深层理解
- [[[[自定义]]]] - 让 OpenSpec 按您的方式工作