OpenSpec

快速入门 ​

本指南介绍在安装和初始化 OpenSpec 之后，它是如何工作的。安装说明请参阅主 README或安装指南。刚接触整套文档？文档首页为你梳理了全部内容。

这些命令在哪里输入？ 有两个地方，混淆它们是最常见的初期错误。

  • openspec ... 命令（如 openspec init）在终端中运行。
  • /opsx:... 命令（如 /opsx:propose）在AI 助手的聊天框中运行，也就是你让它写代码的同一个输入框。

没有单独的"交互模式"需要启动。你只需在聊天框中输入斜杠命令，助手就会接管后续操作。完整说明：命令工作原理。

你的前五分钟 ​

整个流程，每一步都标注了发生的位置：

text
TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
AI CHAT      /opsx:explore                    (可选：先理清思路)
AI CHAT      /opsx:propose add-dark-mode      (AI 起草方案；你审阅)
AI CHAT      /opsx:apply                      (AI 开始构建)
AI CHAT      /opsx:archive                    (规格已更新，变更已归档)

终端中两步完成设置，之后你就在聊天框中工作。本指南的其余部分将逐步拆解每个步骤的作用和你将看到的内容。

不想自己动手操作终端部分？ 将设置提示词粘贴给你的助手，它会处理这两行命令，然后报告创建了哪些内容。

还不确定要构建什么？从 /opsx:explore 开始。 它是一个零风险的思考伙伴，会阅读你的代码库、权衡各种方案，并在任何产物或代码存在之前，将模糊的想法打磨成具体的计划。当思路清晰时，它会交接给 /opsx:propose。这是与 AI 协作时最重要的习惯——否则 AI 会自信满满地构建错误的东西。请参阅探索指南。

工作原理 ​

OpenSpec 帮助你和 AI 编码助手在编写任何代码之前，就构建内容达成一致。

默认快速路径（核心配置）：

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (可选)

当你还在思考要做什么时，从 /opsx:explore 开始；当你已经明确时，直接跳到 /opsx:propose。Explore 包含在默认配置中，所以你需要时它始终可用。

扩展路径（自定义工作流选择）：

text
/opsx:new ──► /opsx:ff 或 /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

默认全局配置为 core，包含 propose、explore、apply、update、sync 和 archive。你可以通过 openspec config profile 启用扩展工作流命令，然后运行 openspec update。

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/增量规格，显示新增/修改/删除的需求
design.md"怎么做"——技术方案和架构决策
tasks.md带复选框的实现清单

产物之间层层递进：

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            随着学习不断更新

在实现过程中，你随时可以返回并完善之前的产物。

增量规格如何工作 ​

增量规格是 OpenSpec 的核心概念。它们展示了相对于当前规格的变化内容。

格式 ​

增量规格使用章节来指示变更类型：

markdown
# Delta for 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)

归档时发生什么 ​

当你归档一个变更时：

  1. ADDED 需求被追加到主规格中
  2. MODIFIED 需求替换现有版本
  3. REMOVED 需求从主规格中删除

变更文件夹会移动到 openspec/changes/archive/ 中作为审计历史。

示例：你的第一个变更 ​

让我们通过为应用程序添加暗色模式来走一遍流程。

1. 启动变更（默认） ​

text
You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — 为什么做这个，什么在变化
     ✓ specs/       — 需求和场景
     ✓ design.md    — 技术方案
     ✓ tasks.md     — 实现清单
     Ready for implementation!

如果你启用了扩展工作流配置，也可以分两步完成：先 /opsx:new，然后 /opsx:ff（或逐步使用 /opsx:continue）。

2. 创建了什么 ​

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 used

tasks.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 variables

3. 实现 ​

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!

在实现过程中，如果你发现设计需要调整，只需更新产物然后继续即可。

4. 归档 ​

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
# List active changes
openspec list

# View change details
openspec show add-dark-mode

# Validate spec formatting
openspec validate add-dark-mode

# Interactive dashboard
openspec view

下一步 ​