核心概念

本指南解释了 OpenSpec 的核心思想以及它们如何组合在一起。有关实际用法，请参阅入门指南和工作流程。

哲学

OpenSpec 围绕四个原则构建：

1
2
3
4

流式而非僵化       — 无阶段门控，做有意义的事情
迭代而非瀑布       — 边构建边学习，边进行边完善
简单而非复杂       — 轻量级设置，最小化仪式
棕地优先           — 适用于现有代码库，而不仅是绿地

这些原则为什么重要

流式而非僵化。 传统的规范系统将你锁定在阶段中：先规划，然后实施，然后完成。OpenSpec 更灵活 —— 你可以以对你有意义的方式以任何顺序创建工件。

迭代而非瀑布。 需求会变化。理解会加深。一开始看起来像是好的方法在看到代码库之后可能无法成立。OpenSpec 拥抱这个现实。

简单而非复杂。 一些规范框架需要大量设置、严格的格式或重量级流程。OpenSpec 不会妨碍你。在几秒钟内初始化，立即开始工作，仅在需要时自定义。

棕地优先。 大多数软件工作不是从零开始的 —— 它是修改现有系统。OpenSpec 的基于 delta 的方法使得指定对现有行为的更改变得容易，而不仅仅是描述新系统。

全局图景

OpenSpec 将你的工作组织成两个主要区域：

1
2
3
4
5
6
7
8
9
10
11
12
13

┌─────────────────────────────────────────────────────────────────┐
│                        openspec/                                 │
│                                                                  │
│   ┌─────────────────────┐      ┌──────────────────────────────┐ │
│   │       specs/        │      │         changes/              │ │
│   │                     │      │                               │ │
│   │  Source of truth    │◄─────│  Proposed modifications       │ │
│   │  How your system    │ merge│  Each change = one folder     │ │
│   │  currently works    │      │  Contains artifacts + deltas  │ │
│   │                     │      │                               │ │
│   └─────────────────────┘      └──────────────────────────────┘ │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Specs 是信息源 —— 它们描述了系统当前的行为。

Changes 是提议的修改 —— 它们存在于单独的文件夹中，直到你准备好合并它们。

这种分离是关键。你可以并行处理多个变更而不冲突。你可以在变更影响主规范之前审查它。当你归档变更时，其 deltas 会干净地合并到信息源中。

规范

规范使用结构化的需求和场景描述系统的行为。

结构

1
2
3
4
5
6
7
8
9

openspec/specs/
├── auth/
│   └── spec.md           # 身份验证行为
├── payments/
│   └── spec.md           # 支付处理
├── notifications/
│   └── spec.md           # 通知系统
└── ui/
    └── spec.md           # UI 行为和主题

按域组织规范 —— 对你的系统有意义的逻辑分组。常见模式：

• 按功能区域：auth/、payments/、search/
• 按组件：api/、frontend/、workers/
• 按有界上下文：ordering/、fulfillment/、inventory/

规范格式

规范包含需求，每个需求都有场景：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# Auth 规范

## Purpose
应用程序的身份验证和会话管理。

## Requirements

### Requirement: 用户身份验证
成功登录后，系统应颁发 JWT 令牌。

#### Scenario: 有效凭据
- Given 拥有有效凭据的用户
- When 用户提交登录表单
- Then 返回 JWT 令牌
- And 用户被重定向到仪表板

#### Scenario: 无效凭据
- Given 无效凭据
- When 用户提交登录表单
- Then 显示错误消息
- And 不颁发令牌

### Requirement: 会话过期
系统应在 30 分钟不活动后使会话过期。

#### Scenario: 空闲超时
- Given 已认证的会话
- When 30 分钟没有活动
- Then 会话失效
- And 用户必须重新认证

关键元素：

为什么这样构建规范

需求是"什么" —— 它们说明系统应该做什么，而不指定实现。

场景是"何时" —— 它们提供可以验证的具体示例。好的场景：

• 可测试（你可以为它们编写自动化测试）
• 覆盖快乐路径和边缘情况
• 使用 Given/When/Then 或类似的结构化格式

RFC 2119 关键词（SHALL、MUST、SHOULD、MAY）传达意图：

• MUST/SHALL — 绝对要求
• SHOULD — 推荐，但存在例外
• MAY — 可选

规范是什么（以及不是什么）

规范是行为契约，不是实施计划。

好的规范内容：

• 用户或下游系统依赖的可观察行为
• 输入、输出和错误条件
• 外部约束（安全、隐私、可靠性、兼容性）
• 可以测试或显式验证的场景

避免在规范中：

• 内部类/函数名
• 库或框架选择
• 逐步实施细节
• 详细的执行计划（这些属于 design.md 或 tasks.md）

快速测试：

• 如果实现可以在不改变外部可见行为的情况下更改，则它可能不属于规范。

保持轻量：渐进式严谨

OpenSpec 旨在避免官僚主义。使用使变更可验证的最轻量级级别。

轻量规范（默认）：

• 短的行为优先需求
• 清晰的范围和非目标
• 几个具体的验收检查

完整规范（针对更高风险）：

• 跨团队或跨存储库更改
• API/契约更改、迁移、安全/隐私关注
• 模糊性可能导致昂贵返工的更改

大多数更改应保持在轻量模式。

人类 + 代理协作

在许多团队中，人类探索并代理起草工件。预期的循环是：

1. 人类提供意图、上下文和约束。
2. 代理将其转换为行为优先的需求和场景。
3. 代理将实施细节保留在 design.md 和 tasks.md 中，而不是 spec.md。
4. 验证在实施之前确认结构和清晰度。

这使得规范对人类可读，对代理一致。

变更

变更是对系统的提议修改，打包为包含理解和实施它所需的所有内容的文件夹。

变更结构

1
2
3
4
5
6
7
8

openspec/changes/add-dark-mode/
├── proposal.md           # 为什么和什么
├── design.md             # 如何（技术方法）
├── tasks.md              # 实施清单
├── .openspec.yaml        # 变更元数据（可选）
└── specs/                # Delta 规范
    └── ui/
        └── spec.md       # ui/spec.md 中的更改

每个变更都是自包含的。它有：

• 工件 — 捕获意图、设计和任务的文档
• Delta 规范 — 指示正在添加、修改或删除什么的规范
• 元数据 — 此特定变更的可选配置

为什么变更是文件夹

将变更打包为文件夹有几个好处：

1. 所有内容在一起。 提案、设计、任务和规范都在一个地方。无需在不同位置搜索。

2. 并行工作。 多个变更可以同时存在而不冲突。在 fix-auth-bug 也在进行的同时处理 add-dark-mode。

3. 干净的历史。 归档时，变更移动到 changes/archive/ 并保留其完整上下文。你可以回头了解不仅改变了什么，还有为什么。

4. 审查友好。 变更文件夹易于审查 —— 打开它，阅读提案，检查设计，查看规范 deltas。

工件

工件是变更中指导工作的文档。

工件流程

1
2
3
4

proposal ──────► specs ──────► design ──────► tasks ──────► implement
    │               │             │              │
   为什么          什么          如何           步骤
 + 范围           更改         方法           采取

工件相互构建。每个工件为下一个提供上下文。

工件类型

Proposal（proposal.md）

提案在高层次上捕获意图、范围和方法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Proposal: 添加暗模式

## Intent
用户要求提供暗模式选项，以减少夜间使用时的眼睛疲劳并匹配系统首选项。

## Scope
范围内：
- 设置中的主题切换
- 系统首选项检测
- 在 localStorage 中持久化首选项

范围外：
- 自定义颜色主题（未来工作）
- 每页主题覆盖

## Approach
使用 CSS 自定义属性进行主题设置，使用 React 上下文进行状态管理。首次加载时检测系统首选项，允许手动覆盖。

何时更新提案：

• 范围变更（缩小或扩展）
• 意图澄清（更好地理解问题）
• 方法根本转变

Specs（specs/ 中的 delta 规范）

Delta 规范描述相对于当前规范正在改变什么。请参阅下面的 Delta Specs。

Design（design.md）

设计捕获技术方法和架构决策。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# Design: 添加暗模式

## Technical Approach
通过 React Context 管理主题状态以避免 prop drilling。CSS 自定义属性支持运行时切换而无需类切换。

## Architecture Decisions

### Decision: Context over Redux
使用 React Context 进行主题状态，因为：
- 简单的二进制状态（明/暗）
- 无复杂的状态转换
- 避免添加 Redux 依赖

### Decision: CSS 自定义属性
使用 CSS 变量而不是 CSS-in-JS，因为：
- 与现有样式表一起工作
- 无运行时开销
- 浏览器原生解决方案

## Data Flow
```
ThemeProvider (context)
       │
       ▼
ThemeToggle ◄──► localStorage
       │
       ▼
CSS Variables (applied to :root)
```

## File Changes
- `src/contexts/ThemeContext.tsx`（新）
- `src/components/ThemeToggle.tsx`（新）
- `src/styles/globals.css`（修改）

何时更新设计：

• 实现显示方法不起作用
• 发现更好的解决方案
• 依赖项或约束发生变化

Tasks（tasks.md）

任务是实施清单 —— 带有复选框的具体步骤。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Tasks

## 1. 主题基础设施
- [ ] 1.1 创建带有明暗状态的 ThemeContext
- [ ] 1.2 添加颜色的 CSS 自定义属性
- [ ] 1.3 实现 localStorage 持久化
- [ ] 1.4 添加系统首选项检测

## 2. UI 组件
- [ ] 2.1 创建 ThemeToggle 组件
- [ ] 2.2 将切换添加到设置页面
- [ ] 2.3 更新 Header 以包含快速切换

## 3. 样式
- [ ] 3.1 定义暗主题调色板
- [ ] 3.2 更新组件以使用 CSS 变量
- [ ] 3.3 测试对比度以实现无障碍

任务最佳实践：

• 在标题下对相关任务进行分组
• 使用分层编号（1.1、1.2 等）
• 保持任务足够小，以便在一个会话中完成
  • 完成任务时勾选它们

Delta 规范

Delta 规范是使 OpenSpec 适用于棕地开发的关键概念。它们描述正在改变什么而不是重述整个规范。

格式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# Auth 的 Delta

## ADDED Requirements

### Requirement: 双因素认证
系统必须支持基于 TOTP 的双因素认证。

#### Scenario: 2FA 注册
- Given 未启用 2FA 的用户
- When 用户在设置中启用 2FA
- Then 显示用于身份验证器应用程序设置的 QR 码
- And 用户必须在激活之前通过代码验证

#### Scenario: 2FA 登录
- Given 启用了 2FA 的用户
- When 用户提交有效凭据
- Then 显示 OTP 挑战
     - And 仅在有效 OTP 后登录完成

## MODIFIED Requirements

### Requirement: 会话过期
系统应在 15 分钟不活动后使会话过期。
（之前：30 分钟）

#### Scenario: 空闲超时
- Given 已认证的会话
- When 15 分钟没有活动
- Then 会话失效

## REMOVED Requirements

### Requirement: 记住我
（已弃用，改用 2FA。用户应每次重新认证。）

Delta 章节

为什么使用 Delta 而非完整规范

清晰度。 Delta 显示 exactly 正在改变什么。阅读完整规范，你必须与当前版本进行心理差异。

避免冲突。 两个变更可以触及相同的规范文件而不冲突，只要它们修改不同的需求。

审查效率。 审查者看到变更，而不是未更改的上下文。专注于重要内容。

棕地适配。 大多数工作修改现有行为。Deltas 使修改成为一等公民，而不是事后诸葛亮。

Schemas

模式定义工作流的工件类型及其依赖关系。

Schemas 如何工作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
  - id: proposal
    generates: proposal.md
    requires: []              # 无依赖关系，可以先创建

  - id: specs
    generates: specs/**/*.md
    requires: [proposal]      # 创建规范之前需要提案

  - id: design
    generates: design.md
    requires: [proposal]      # 可以与规范并行创建

  - id: tasks
    generates: tasks.md
    requires: [specs, design] # 首先需要规范和设计

工件形成依赖关系图：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

                 proposal
                (根节点)
                    │
      ┌─────────────┴─────────────┐
      │                           │
      ▼                           ▼
   specs                       design
(requires:                  (requires:
 proposal)                   proposal)
      │                           │
      └─────────────┬─────────────┘
                    │
                    ▼
                 tasks
             (requires:
             specs, design)

依赖关系是赋能者，而不是门控。 它们显示可以创建什么，而不是必须下一步创建什么。如果不需要，你可以跳过设计。你可以在设计之前或之后创建规范 —— 两者都只依赖于提案。

内置 Schemas

spec-driven（默认）

规范驱动开发的标准工作流：

1

proposal → specs → design → tasks → implement

最适合：大多数你想要在实施之前就规范达成一致的功能工作。

自定义 Schemas

为你的团队工作流创建自定义模式：

1
2
3
4
5

# 从头创建
openspec schema init research-first

# 或复制现有的
openspec schema fork spec-driven research-first

自定义模式示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []           # 先做研究

  - id: proposal
    generates: proposal.md
    requires: [research]   # 提案由研究告知

  - id: tasks
    generates: tasks.md
    requires: [proposal]   # 跳过规范/设计，直接进入任务

请参阅自定义了解创建和使用自定义模式的完整详细信息。

归档

归档通过将其 delta 规范合并到主规范并为历史记录保存变更来完成变更。

归档时发生什么

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

Before archive:

openspec/
├── specs/
│   └── auth/
│       └── spec.md ◄────────────────┐
└── changes/                         │
    └── add-2fa/                     │
        ├── proposal.md              │
        ├── design.md                │ merge
        ├── tasks.md                 │
        └── specs/                   │
            └── auth/                │
                └── spec.md ─────────┘


After archive:

openspec/
├── specs/
│   └── auth/
│       └── spec.md        # 现在包括 2FA 需求
└── changes/
    └── archive/
        └── 2025-01-24-add-2fa/    # 为历史记录保留
            ├── proposal.md
            ├── design.md
            ├── tasks.md
            └── specs/
                └── auth/
                    └── spec.md

归档过程

1. 合并 deltas。 每个 delta 规范章节（ADDED/MODIFIED/REMOVED）应用于相应的主规范。

2. 移动到归档。 变更文件夹移动到带有日期前缀的 changes/archive/ 以进行按时间顺序排序。

3. 保留上下文。 所有工件在归档中保持完整。你可以随时回头了解做出变更的原因。

为什么归档很重要

干净的状态。 活动变更（changes/）仅显示进行中的工作。已完成的工作移出路径。

审计轨迹。 归档保留每个变更的完整上下文 —— 不仅改变了什么，还有解释为什么的提案、解释如何的设计，以及显示工作的任务。

规范演进。 当归档变更时，规范有机地增长。每个归档合并其 deltas，随时间建立全面的规范。

一切如何组合在一起

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

┌─────────────────────────────────────────────────────────────────────────────┐
│                              OPENSPEC FLOW                                   │
│                                                                              │
│   ┌────────────────┐                                                         │
│   │  1. START      │  /opsx:propose (core) or /opsx:new (expanded)          │
│   │     CHANGE     │                                                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  2. CREATE     │  /opsx:ff or /opsx:continue (expanded workflow)         │
│   │     ARTIFACTS  │  Creates proposal → specs → design → tasks              │
│   │                │  (based on schema dependencies)                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  3. IMPLEMENT  │  /opsx:apply                                            │
│   │     TASKS      │  Work through tasks, checking them off                  │
│   │                │◄──── Update artifacts as you learn                      │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  4. VERIFY     │  /opsx:verify (optional)                                │
│   │     WORK       │  Check implementation matches specs                     │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐     ┌──────────────────────────────────────────────┐   │
│   │  5. ARCHIVE    │────►│  Delta specs merge into main specs           │   │
│   │     CHANGE     │     │  Change folder moves to archive/             │   │
│   └────────────────┘     │  Specs are now the updated source of truth   │   │
│                          └──────────────────────────────────────────────┘   │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

良性循环：

1. 规范描述当前行为
2. 变更提议修改（作为 deltas）
3. 实施使更改成为现实
4. 归档将 deltas 合并到规范中
5. 规范现在描述新的行为
6. 下一个变更建立在更新的规范之上

术语表

下一步

• 入门指南 - 实用的第一步
• 工作流程 - 常见模式和何时使用每个
• 命令 - 完整命令参考
• 自定义 - 创建自定义模式

Cursor IDE 专用指南

概述

Cursor IDE 使用 OpenSpec 的默认快速路径（core profile），提供简洁的四步工作流。

Cursor IDE 的四个命令

在 Cursor 中，OpenSpec 命令使用连字符格式（不同于其他 IDE 的冒号格式）：

1
2
3
4

/opsx-propose    # 创建变更提案
/opsx-explore    # 探索想法
/opsx-apply      # 实施任务
/opsx-archive     # 归档已完成的变更

Cursor 的工作流程

快速路径（需求明确时）

1

/opsx-propose ──► /opsx-apply ──► /opsx-archive

探索路径（需求不明确时）

/opsx-explore 是纯对话模式，不创建任何文件，用于在正式提案前理清思路：

1
2
3
4
5

/opsx-explore ──► /opsx-propose ──► /opsx-apply ──► /opsx-archive
     ▲
     │
  理清问题、调查代码库、讨论方案
  想清楚后再 propose

完整示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

You: /opsx-propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — 为什么要这样做，正在改变什么
     ✓ specs/       — 需求和场景
     ✓ design.md    — 技术方法
     ✓ tasks.md     — 实现清单
     准备好实施！

You: /opsx-apply

AI:  正在实施 add-dark-mode...
     ✓ 1.1 创建带有明暗状态的 ThemeContext
     ✓ 1.2 将 CSS 自定义属性添加到 globals.css
     ✓ 1.3 实现 localStorage 持久化
     ✓ 2.1 创建 ThemeToggle 组件
     ...
     所有任务完成！

You: /opsx-archive

AI:  正在归档 add-dark-mode...
     ✓ 已将规范合并到 openspec/specs/ui/spec.md
     ✓ 移动到 openspec/changes/archive/2025-01-24-add-dark-mode/
     完成！准备下一个功能。

Proposal 完成后想改进怎么办？

直接对话即可，不需要输入任何命令。 /opsx-propose 运行后，AI 已经有上下文，直接用自然语言告诉它你想怎么改就行。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

You: /opsx-propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md

You: 方案改成用 Tailwind 的 dark: 前缀，不要用 CSS 变量

AI:  好的，我来更新相关工件...
     ✓ 已更新 proposal.md（技术方案）
     ✓ 已更新 design.md
     ✓ 已更新 specs/
     ✓ 已更新 tasks.md（调整了相关任务）

You: 另外先不做系统首选项检测了，只保留手动切换

AI:  好的，缩小范围...
     ✓ 已更新 specs/（移除系统首选项需求）
     ✓ 已更新 tasks.md（删除相关任务）

You: /opsx-apply

AI:  正在实施...

什么时候该直接对话 vs 开新变更？

方案 2：启用扩展工作流（推荐用于复杂变更）

如果想要更多控制，可以启用扩展工作流：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 1. 在终端运行（不需要在 Cursor 中）
openspec config profile

# 2. 在交互式菜单中选择：
#    - Change delivery + workflows（更改交付 + 工作流）
#    - 然后在 workflow 列表中勾选：
#      ☑ propose
#      ☑ explore
#      ☑ new
#      ☑ continue
#      ☑ ff
#      ☑ apply
#      ☑ verify
#      ☑ archive

# 3. 更新 Cursor 的技能和命令
openspec update

扩展工作流额外命令：

1
2
3
4

/opsx-new         # 开始变更脚手架
/opsx-continue    # 创建下一个工件（一次一个）
/opsx-ff          # 快速前进：创建所有规划工件
/opsx-verify      # 验证实现

使用扩展工作流的示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# 开始变更
You: /opsx-new add-auth

AI:  Created openspec/changes/add-auth/
     准备创建：proposal

# 渐进式创建工件
You: /opsx-continue

AI:  正在创建 proposal...

You: /opsx-continue

AI:  正在创建 specs...

You: /opsx-continue

AI:  正在创建 design...

You: /opsx-continue

AI:  正在创建 tasks...
     所有规划工件完成！

# 或一次性完成
You: /opsx-ff

AI:  正在创建所有规划工件...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     准备实施！

方案 3：开始新变更（当改进变成不同工作时）

根据 OpenSpec 的决策指南：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

                ┌─────────────────────────────────────┐
                │     这是相同的工作吗？          │
                └──────────────┬──────────────────────┘
                               │
            ┌──────────────────┼──────────────────┐
            │                  │                  │
            ▼                  ▼                  ▼
     相同意图？       >50% 重叠？      原始可以
     相同问题？      相同范围？        在没有这些
            │                  │          变更的情况下
            │                  │          "完成"？
  ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
  │                 │  │             │   │               │
 是                否 是           否  否              是
  │                 │  │             │   │               │
  ▼                 ▼  ▼             ▼   ▼               ▼
更新              新 更新         新 更新              新

更新 vs 新变更的判断标准：

示例决策：

1
2
3
4
5
6
7
8
9
10
11

场景 1："添加暗模式" → "需要支持自定义主题"
→ 新变更（范围爆炸）
原因：从基本暗模式变成完整主题系统

场景 2："添加暗模式" → "系统首选项检测比预期难"
→ 更新（相同意图）
原因：相同目标，只是实现更复杂

场景 3："添加暗模式" → "先发布切换，稍后添加首选项"
→ 更新然后归档，然后新变更
原因：原始可以作为 MVP 完成

实际工作流程示例

场景 1：简单的功能实现（直接路径）

1
2
3
4
5
6
7
8

1. /opsx-propose add-user-profile
   → 创建变更和所有工件

2. /opsx-apply
   → 实施任务

3. /opsx-archive
   → 归档变更

场景 2：探索性工作（需要先理解问题）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

1. /opsx-explore
   AI: 你想探索什么？

2. 我想提高页面加载性能但不确定瓶颈

3. AI: 让我调查...
    发现三个瓶颈：
    1. 大的未优化图像
    2. ProductList 中的同步数据获取
    3. 来自上下文更改的重新渲染

4. 让我们解决数据获取问题

5. /opsx-propose optimize-product-list-fetching
   → 创建变更

6. /opsx-apply
   → 实施优化

7. /opsx-archive
   → 归档

场景 3：实施中发现问题（对话调整）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

1. /opsx-propose add-dark-mode
   → 创建 proposal、specs、design、tasks

2. /opsx-apply
   AI: 正在实施...

3. 实施 1.2 时发现：
   CSS 变量与现有 Tailwind 配置冲突

4. 直接对话：
   You: CSS 变量和 Tailwind 冲突了，改用 dark: 前缀

   AI: 好的，我来调整...
       ✓ 已更新 proposal.md
       ✓ 已更新 design.md
       ✓ 已更新 tasks.md（替换了冲突的任务）

5. 继续应用：
   You: /opsx-apply

   AI: 从任务 1.2 继续（已更新）...

6. 完成：
   You: /opsx-archive

场景 4：并行工作（切换上下文）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

变更 A（进行中）：
1. /opsx-propose add-dark-mode
2. /opsx:apply
   → 实施到一半...

被拉去修复错误：

3. /opsx-propose fix-login-bug
   → 创建新变更

4. /opsx-apply fix-login-bug
   → 完成修复

5. /opsx-archive fix-login-bug
   → 归档错误修复

回到原工作：

6. /opsx-apply add-dark-mode
   AI: 正在恢复 add-dark-mode...
       从任务 2.3 继续：更新 Header...

技能文件位置

Cursor 中的 OpenSpec 技能和命令位于：

1
2
3
4
5
6
7
8
9
10

.cursor/
├── skills/
│   └── openspec-*/
│       └── SKILL.md           # 技能定义
└── commands/
    └── opsx-*.md              # 命令文件
        ├── opsx-propose.md
        ├── opsx-explore.md
        ├── opsx-apply.md
        └── opsx-archive.md

常见问题

Q: 为什么 Cursor 只有四个命令？

A: Cursor 使用默认的 core profile，这是 OpenSpec 为快速、高效的工作流设计的。如果你需要更多控制，可以通过 openspec config profile 启用扩展工作流。

Q: propose 和 explore 有什么区别？

A: explore 是思考模式 —— 不创建文件，只是对话和调查。当你准备好创建实际变更时，使用 propose。

Q: 如何查看当前状态？

A: 使用 CLI 命令（在终端）：

1
2
3
4
5
6
7
8

# 列出所有变更
openspec list

# 查看特定变更的详情
openspec show add-dark-mode

# 查看工件状态
openspec status --change add-dark-mode

Q: 我可以同时使用 CLI 和 Cursor 命令吗？

A: 完全可以！它们互补：

• CLI 命令：用于状态检查、验证、模式管理
• Cursor 命令：用于创建工件、实施、归档

Q: proposal 完成后，发现需求变了怎么办？

A: 取决于变化程度：

• 小调整：直接编辑 proposal.md，然后继续应用
• 重大变化：开始新变更
• 范围爆炸：归档当前变更（作为 MVP），开始新变更处理扩展

Q: 如何回滚工件更改？

A: 工件文件（proposal.md、design.md、tasks.md）在 openspec/changes/ 目录中，像其他源代码文件一样进行版本控制（git）。

1
2
3
4
5

# 查看更改
git diff openspec/changes/add-dark-mode/proposal.md

# 撤销更改
git checkout openspec/changes/add-dark-mode/proposal.md

最佳实践

1. 从 explore 开始处理复杂问题

当你不确定方向时：

1
2
3
4

/opsx-explore
→ 讨论问题
→ 选项和权衡
→ 然后使用 /opsx-propose

2. 保持变更聚焦

每个更改一个逻辑工作单位。如果你正在做"添加功能 X 并且还重构 Y"，考虑两个单独的变更。

3. 命名变更清楚

1
2
3
4

好的：                          避免：
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes

4. 在归档前验证

如果启用了扩展工作流：

1
2
3
4

/opsx:verify
→ 检查完整性
→ 检查正确性
→ 检查一致性

即使没有 verify，也可以手动检查：

• 所有 tasks.md 中的任务都勾选了？
• 所有需求都有相应的代码？
• 设计决策反映在实现中？

5. 清理上下文

OpenSpec 从干净的上下文窗口受益。在开始实施之前：

• 清除之前的聊天历史
• 保持良好的上下文卫生

下一步

• 启用扩展工作流：如果想要更多控制，运行 openspec config profile
• 自定义配置：创建 openspec/config.yaml 添加项目特定上下文
• 查看 CLI 参考：了解更多终端命令
• 阅读工作流：了解其他工作流模式

故障排除

“命令未被识别”

确保：

1. OpenSpec 已初始化：openspec init
2. Cursor 已刷新技能：openspec update
3. 重启 Cursor IDE 以获取新技能

“变更未找到”

• 检查变更文件夹是否存在：openspec list
• 确认你在正确的项目目录

“没有准备就绪的工件”

• 运行 openspec status --change <name> 查看阻塞内容
• 创建缺失的依赖工件

自定义

OpenSpec 提供三个级别的自定义：

项目配置

openspec/config.yaml 文件是为你的团队自定义 OpenSpec 的最简单方法。它允许你：

• 设置默认模式 - 在每个命令上跳过 --schema
• 注入项目上下文 - AI 看到你的技术堆栈、约定等
• 添加每个工件规则 - 特定工件的自定义规则

快速设置

1

openspec init

这会引导你通过交互式创建配置。或手动创建一个：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

它如何工作

默认模式：

1
2
3
4
5

# 无配置
openspec new change my-feature --schema spec-driven

# 使用配置 - 模式是自动的
openspec new change my-feature

上下文和规则注入：

生成任何工件时，你的上下文和规则被注入到 AI 提示中：

1
2
3
4
5
6
7
8
9
10
11
12
13

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[模式的内置模板]
</template>

• 上下文 出现在所有工件中
• 规则 仅出现在匹配的工件中

模式解析顺序

当 OpenSpec 需要模式时，它按此顺序检查：

1. CLI 标志：--schema <name>
2. 变更元数据（变更文件夹中的 .openspec.yaml）
3. 项目配置（openspec/config.yaml）
4. 默认（spec-driven）

自定义 Schemas

当项目配置不够时，创建自己的模式并使用完全自定义的工作流。自定义模式位于你项目的 openspec/schemas/ 目录中，并与你的代码一起版本控制。

1
2
3
4
5
6
7
8
9

your-project/
├── openspec/
│   ├── config.yaml        # 项目配置
│   ├── schemas/           # 自定义模式位于此处
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # 你的变更
└── src/

复制现有模式

自定义的最快方法是复制内置模式：

1

openspec schema fork spec-driven my-workflow

这将整个 spec-driven 模式复制到 openspec/schemas/my-workflow/，你可以在其中自由编辑。

你得到什么：

1
2
3
4
5
6
7

openspec/schemas/my-workflow/
├── schema.yaml           # 工作流定义
└── templates/
    ├── proposal.md       # 提案工件模板
    ├── spec.md           # 规范模板
    ├── design.md         # 设计模板
    └── tasks.md          # 任务模板

现在编辑 schema.yaml 以更改工作流，或编辑模板以更改 AI 生成的内容。

从头创建模式

对于完全新鲜的工作流：

1
2
3
4
5
6
7
8

# 交互式
openspec schema init research-first

# 非交互式
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

模式结构

模式定义工作流中的工件及其依赖关系：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: My team's custom workflow

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document
    template: proposal.md
    instruction: |
      创建一个解释为什么需要此更改的提案。
      专注于问题，而不是解决方案。
    requires: []

  - id: design
    generates: design.md
    description: Technical design
    template: design.md
    instruction: |
      创建一个解释如何实施的设计文档。
    requires:
      - proposal    # 不能在提案存在之前创建设计

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

关键字段：

模板

模板是指导 AI 的 markdown 文件。创建该工件时，它们被注入到提示中。

1
2
3
4
5
6
7
8
9
10
11
12

<!-- templates/proposal.md -->
## Why

<!-- 解释此更改的动机。这解决了什么问题？ -->

## What Changes

<!-- 描述将要改变什么。具体说明新功能或修改。 -->

## Impact

<!-- 受影响的代码、API、依赖项、系统 -->

模板可以包括：

• AI 应该填充的章节标题
• 具有 AI 指导的 HTML 注释
• 显示预期结构的示例格式

验证你的模式

在使用自定义模式之前，验证它：

1

openspec schema validate my-workflow

这检查：

• schema.yaml 语法正确
• 所有引用的模板存在
• 无循环依赖
• 工件 ID 有效

使用你的自定义模式

一旦创建，使用你的模式：

1
2
3
4
5

# 在命令上指定
openspec new change feature --schema my-workflow

# 或在 config.yaml 中设置为默认
schema: my-workflow

调试模式解析

不确定正在使用哪个模式？用以下方法检查：

1
2
3
4
5

# 查看特定模式从哪里解析
openspec schema which my-workflow

# 列出所有模式及其来源
openspec schema which --all

输出显示它是来自你的项目、用户目录还是包：

1
2
3

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

注意： OpenSpec 还支持在 ~/.local/share/openspec/schemas/ 的用户级模式，用于跨项目共享，但推荐项目级模式在 openspec/schemas/ 中，因为它们与你的代码版本控制。

示例

快速迭代工作流

用于快速迭代的最小工作流：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Fast iteration with minimal overhead

artifacts:
  - id: proposal
    generates: proposal.md
    description: Quick proposal
    template: proposal.md
    instruction: |
      为此更改创建一个简短的提案。
      专注于什么和为什么，跳过详细的规范。
    requires: []

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

添加审查工件

复制默认值并添加审查步骤：

1

openspec schema fork spec-driven with-review

然后编辑 schema.yaml 以添加：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

- id: review
  generates: review.md
  description: Pre-implementation review checklist
  template: review.md
  instruction: |
    基于设计创建审查清单。
    包括安全、性能和测试考虑。
  requires:
    - design

- id: tasks
  # ... 现有任务配置 ...
  requires:
    - specs
    - design
    - review    # 现在任务也需要审查

另请参阅

• CLI 参考：模式命令 - 完整命令文档
• 命令 - 斜杠命令
• 工作流程 - 工作流模式
• 概念 - 核心概念

入门指南

本指南解释了在安装和初始化 OpenSpec 之后的工作原理。关于安装说明，请参阅主 README。

OpenSpec 如何工作

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

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

1

/opsx:propose ──► /opsx:apply ──► /opsx:archive

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

1

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

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

OpenSpec 创建的内容

运行 openspec init 后，你的项目将具有以下结构：

1
2
3
4
5
6
7
8
9
10
11
12
13

openspec/
├── specs/              # 信息源（系统的行为）
│   └── <domain>/
│       └── spec.md
├── changes/            # 提议的更新（每个变更一个文件夹）
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Delta 规范（正在改变什么）
│           └── <domain>/
│               └── spec.md
└── config.yaml         # 项目配置（可选）

两个关键目录：

• specs/ - 信息源。这些规范描述了系统当前的行为。按域组织（例如 specs/auth/、specs/payments/）。

• changes/ - 提议的修改。每个变更都有自己的文件夹，包含所有相关的工件。当变更完成后，其规范会合并到主 specs/ 目录中。

理解工件

每个变更文件夹都包含指导工作的工件：

工件相互构建：

1
2
3
4

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            在学习时更新

你可以在实现过程中随时回到早期工件并完善它们。

Delta 规范如何工作

Delta 规范是 OpenSpec 的关键概念。它们显示了相对于当前规范正在改变什么。

格式

Delta 规范使用章节来指示变更类型：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# Auth 的 Delta

## ADDED Requirements

### Requirement: 双因素认证
系统必须在登录期间要求第二个因素。

#### Scenario: OTP 必需
- Given 一个启用了 2FA 的用户
- When 用户提交有效凭据
- Then 显示 OTP 挑战

## MODIFIED Requirements

### Requirement: 会话超时
系统应在 30 分钟不活动后使会话过期。
（之前：60 分钟）

#### Scenario: 空闲超时
- Given 一个已认证的会话
- When 30 分钟没有活动
- Then 会话失效

## REMOVED Requirements

### Requirement: 记住我
（已弃用，改用 2FA）

归档时发生什么

当你归档变更时：

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

变更文件夹移动到 openspec/changes/archive/ 用于审计历史。

示例：你的第一个变更

让我们通过添加暗模式来演示。

1. 开始变更（默认）

1
2
3
4
5
6
7
8

You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — 为什么要这样做，正在改变什么
     ✓ specs/       — 需求和场景
     ✓ design.md    — 技术方法
     ✓ tasks.md     — 实现清单
     准备好实施！

如果你启用了扩展的工作流配置，你也可以分两步进行：/opsx:new 然后 /opsx:ff（或 /opsx:continue 增量进行）。

2. 创建的内容

proposal.md - 捕获意图：

1
2
3
4
5
6
7
8
9
10
11
12

# Proposal: 添加暗模式

## Intent
用户要求提供暗模式选项，以减少夜间使用时的眼睛疲劳。

## Scope
- 在设置中添加主题切换
- 支持系统首选项检测
- 在 localStorage 中持久化首选项

## Approach
使用 CSS 自定义属性进行主题设置，使用 React 上下文进行状态管理。

specs/ui/spec.md - 显示新需求的 Delta：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# UI 的 Delta

## ADDED Requirements

### Requirement: 主题选择
系统应允许用户在明暗主题之间选择。

#### Scenario: 手动切换
- Given 用户在任何页面上
- When 用户点击主题切换
- Then 主题立即切换
- And 首选项在会话之间持久化

#### Scenario: 系统首选项
- Given 没有保存首选项的用户
- When 应用程序加载
- Then 使用系统的首选配色方案

tasks.md - 实现清单：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Tasks

## 1. 主题基础设施
- [ ] 1.1 创建带有明暗状态的 ThemeContext
- [ ] 1.2 添加颜色的 CSS 自定义属性
- [ ] 1.3 实现 localStorage 持久化

## 2. UI 组件
- [ ] 2.1 创建 ThemeToggle 组件
- [ ] 2.2 将切换添加到设置页面
- [ ] 2.3 更新 Header 以包含快速切换

## 3. 样式
- [ ] 3.1 定义暗主题调色板
- [ ] 3.2 更新组件以使用 CSS 变量

3. 实施

1
2
3
4
5
6
7
8
9

You: /opsx:apply

AI:  正在完成任务...
     ✓ 1.1 创建了带有明暗状态的 ThemeContext
     ✓ 1.2 将 CSS 自定义属性添加到 globals.css
     ✓ 1.3 实现了 localStorage 持久化
     ✓ 2.1 创建了 ThemeToggle 组件
     ...
     所有任务完成！

在实施过程中，如果你发现设计需要调整，只需更新工件并继续。

4. 归档

1
2
3
4
5
6

You: /opsx:archive

AI:  正在归档 add-dark-mode...
     ✓ 将规范合并到 openspec/specs/ui/spec.md
     ✓ 移动到 openspec/changes/archive/2025-01-24-add-dark-mode/
     完成！准备下一个功能。

你的 delta 规范现在是主规范的一部分，记录了你的系统如何工作。

验证和审查

使用 CLI 检查你的变更：

1
2
3
4
5
6
7
8
9
10
11

# 列出活动变更
openspec list

# 查看变更详情
openspec show add-dark-mode

# 验证规范格式
openspec validate add-dark-mode

# 交互式仪表板
openspec view

下一步

• 工作流程 - 常见模式和何时使用每个命令
• 命令 - 所有斜杠命令的完整参考
• 概念 - 深入了解规范、变更和模式
• 自定义 - 让 OpenSpec 按你的方式工作

多语言指南

配置 OpenSpec 以英语以外的语言生成工件。

快速设置

将语言指令添加到你的 openspec/config.yaml：

1
2
3
4
5
6
7
8

schema: spec-driven

context: |
  Language: Portuguese (pt-BR)
  All artifacts must be written in Brazilian Portuguese.

  # 你的其他项目上下文在下面...
  Tech stack: TypeScript, React, Node.js

就是这样。所有生成的工件现在都将使用葡萄牙语。

语言示例

Portuguese (Brazil)

1
2
3

context: |
  Language: Portuguese (pt-BR)
  All artifacts must be written in Brazilian Portuguese.

Spanish

1
2
3

context: |
  Idioma: Español
  Todos los artefactos deben escribirse en español.

Chinese (Simplified)

1
2
3

context: |
  语言：中文（简体）
  所有产出物必须用简体中文撰写。

Japanese

1
2
3

context: |
  言語：日本語
  すべての成果物は日本語で作成してください。

French

1
2
3

context: |
  Langue : Français
  Tous les artefacts doivent être rédigés en français.

German

1
2
3

context: |
  Sprache: Deutsch
  Alle Artefakte müssen auf Deutsch verfasst werden.

提示

处理技术术语

决定如何处理技术术语：

1
2
3
4
5

context: |
  Language: Japanese
  Write in Japanese, but:
  - Keep technical terms like "API", "REST", "GraphQL" in English
  - Code examples and file paths remain in English

与其他上下文结合

语言设置与你的其他项目上下文一起工作：

1
2
3
4
5
6
7
8

schema: spec-driven

context: |
  Language: Portuguese (pt-BR)
  All artifacts must be written in Brazilian Portuguese.

  Tech stack: TypeScript, React 18, Node.js 20
  Database: PostgreSQL with Prisma ORM

验证

要验证你的语言配置是否工作：

1
2
3
4

# 检查说明 - 应该显示你的语言上下文
openspec instructions proposal --change my-change

# 输出将包括你的语言上下文

相关文档

• 自定义指南 - 项目配置选项
• 工作流程指南 - 完整工作流程文档

支持的工具

OpenSpec 与许多 AI 编程助手一起工作。当你运行 openspec init 时，OpenSpec 使用你活动的配置文件/工作流选择和交付模式配置选定的工具。

工作原理

对于每个选定的工具，OpenSpec 可以安装：

1. 技能（如果交付包括技能）：.../skills/openspec-*/SKILL.md
2. 命令（如果交付包括命令）：工具特定的 opsx-* 命令文件

默认情况下，OpenSpec 使用 core 配置文件，其中包括：

• propose
• explore
• apply
• archive

你可以通过 openspec config profile 然后运行 openspec update 来启用扩展工作流（new、continue、ff、verify、sync、bulk-archive、onboard）。

工具目录参考

* Codex 命令安装在全局 Codex 主目录（如果设置 $CODEX_HOME/prompts/，否则 ~/.codex/prompts/），而不是你的项目目录。

** GitHub Copilot 提示文件在 IDE 扩展（VS Code、JetBrains、Visual Studio）中被识别为自定义斜杠命令。Copilot CLI 当前不直接使用 .github/prompts/*.prompt.md。

非交互式设置

对于 CI/CD 或脚本设置，使用 --tools（以及可选的 --profile）：

1
2
3
4
5
6
7
8
9
10
11

# 配置特定工具
openspec init --tools claude,cursor

# 配置所有受支持的工具
openspec init --tools all

# 跳过工具配置
openspec init --tools none

# 为此运行覆盖配置文件
openspec init --profile core

可用工具 ID（--tools）： amazon-q、antigravity、auggie、claude、cline、codex、codebuddy、continue、costrict、crush、cursor、factory、gemini、github-copilot、iflow、kilocode、kiro、opencode、pi、qoder、qwen、roocode、trae、windsurf

依赖于工作流的安装

OpenSpec 根据选择的工作流安装工作流工件：

• 核心配置文件（默认）： propose、explore、apply、archive
• 自定义选择： 所有工作流 ID 的任何子集：
  propose、explore、new、continue、apply、ff、sync、archive、bulk-archive、verify、onboard

换句话说，技能/命令数量依赖于配置文件和交付，而不是固定的。

生成的技能名称

当由配置文件/工作流配置选择时，OpenSpec 生成这些技能：

• openspec-propose
• openspec-explore
• openspec-new-change
• openspec-continue-change
• openspec-apply-change
• openspec-ff-change
• openspec-sync-specs
• openspec-archive-change
• openspec-bulk-archive-change
• openspec-verify-change
• openspec-onboard

请参阅命令了解命令行为和CLI 参考了解 init/update 选项。

相关

• CLI 参考 — 终端命令
• 命令 — 斜杠命令和技能
• 入门指南 — 首次设置

工作流程

本指南涵盖 OpenSpec 的常见工作流程模式以及何时使用它们。有关基本设置，请参阅入门指南。有关命令参考，请参阅命令。

哲学：行动，而非阶段

传统的工作流强迫你经历阶段：先规划，然后实施，然后完成。但现实工作并不完全符合这些框框。

OPSX 采用了不同的方法：

1
2
3
4
5
6
7
8
9
10

传统（阶段锁定）：

  PLANNING ────────► IMPLEMENTING ────────► DONE
      │                    │
      │   "不能回去"      │
      └────────────────────┘

OPSX（流式行动）：

  proposal ──► specs ──► design ──► tasks ──► implement

关键原则：

• 行动，而非阶段 - 命令是你可以做的事情，而不是你被困的阶段
• 依赖关系是赋能者 - 它们显示什么是可能的，而不是下一步必须做什么

自定义： OPSX 工作流由定义工件序列的模式驱动。有关创建自定义模式的详细信息，请参阅自定义。

两种模式

默认快速路径（core 配置）

新安装默认为 core，它提供：

• /opsx:propose
• /opsx:explore
• /opsx:apply
• /opsx:archive

典型流程：

1

/opsx:propose ──► /opsx:apply ──► /opsx:archive

扩展/完整工作流（自定义选择）

如果你想要明确的脚手架和构建命令（/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:sync、/opsx:bulk-archive、/opsx:onboard），可以通过以下方式启用：

1
2

openspec config profile
openspec update

工作流程模式（扩展模式）

快速功能

当你知道要构建什么，只需要执行时：

1

/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

示例对话：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

You: /opsx:new add-logout-button

AI:  Created openspec/changes/add-logout-button/
     准备创建：proposal

You: /opsx:ff

AI:  正在创建所有规划工件...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     准备实施！

You: /opsx:apply

AI:  正在完成任务...
     ✓ 将注销按钮添加到 header
     ✓ 实现了会话清除
     ✓ 添加了确认对话框
     所有任务完成！

You: /opsx:archive

AI:  ✓ 已合并规范
     ✓ 已归档变更

最适合： 中小型功能、错误修复、简单的变更。

探索式

当需求不明确或需要先调查时：

1

/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

示例对话：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

You: /opsx:explore

AI:  你想探索什么？

You: 我想提高页面加载性能，但不确定瓶颈在哪里。

AI:  让我帮你调查...
     [分析包大小，识别慢查询，审查组件渲染模式]

     我发现了三个主要瓶颈：
     1. 大的未优化图像
     2. ProductList 中的同步数据获取
     3. 来自上下文更改的重新渲染

     你想先解决哪个？

You: 让我们先解决数据获取问题。

You: /opsx:new optimize-product-list-fetching

AI:  Created change. 准备创建：proposal

You: /opsx:continue

AI:  根据我们的探索创建提案...
     [编写提案，整合调查见解]

     准备创建：specs, design
     你接下来想要哪个？

You: /opsx:continue

AI:  正在创建规范...

最适合： 性能优化、调试、架构决策、不明确的需求。

并行变更

同时处理多个变更：

1
2
3
4
5

变更 A: /opsx:new ──► /opsx:ff ──► /opsx:apply (进行中)
                                         │
                                    上下文切换
                                         │
变更 B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

示例对话：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

You: 我正在处理 add-dark-mode 但被拉去修复错误

You: /opsx:new fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/

You: /opsx:ff

AI:  ✓ 已创建规划工件

You: /opsx:apply

AI:  正在处理 fix-login-redirect...
     [实施修复]
     所有任务完成！

You: /opsx:archive

AI:  ✓ 已归档 fix-login-redirect

You: 让我们回到暗模式

You: /opsx:apply add-dark-mode

AI:  正在恢复 add-dark-mode...
     从任务 2.3 继续：更新 Header...

最适合： 并行工作流、紧急中断、团队协作。

当有多个完成的变更时，使用 /opsx:bulk-archive：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

You: /opsx:bulk-archive

AI:  发现 3 个完成的变更：
     - add-dark-mode (所有任务完成)
     - fix-login-redirect (所有任务完成)
     - update-footer (所有任务完成)

     检查规范冲突...
     ⚠ add-dark-mode 和 update-footer 都触及 specs/ui/

     检查代码库以解决...
     两个变更都已实现。将按时间顺序应用。

     归档所有 3 个变更？

You: 是

AI:  ✓ 已归档 add-dark-mode
     ✓ 已归档 fix-login-redirect
     ✓ 已归档 update-footer
     规范合并顺序：add-dark-mode → update-footer

批量归档检测多个变更何时触及相同的规范，并通过检查实际实施的内容来解决冲突。

完成变更

推荐的完成流程：

1
2
3
4

/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              验证              提示同步
              实现              如需要

Verify: 检查你的工作

/opsx:verify 在三个维度上验证实现与工件的一致性：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

You: /opsx:verify

AI:  正在验证 add-auth...

     COMPLETENESS
     ✓ tasks.md 中的所有 12 个任务都已检查
     ✓ 规范中的所有需求都有相应的代码
     ⚠ 场景"不活动后会话超时"未测试

     CORRECTNESS
     ✓ 实现与规范意图匹配
     ✓ 场景中的边缘情况已处理
     ✓ 错误状态与规范定义匹配

     COHERENCE
     ✓ 设计决策反映在代码结构中
     ✓ 命名约定与 design.md 一致
     ⚠ 设计提到"事件驱动"但实现使用轮询

     SUMMARY
     ─────────────────────────────
     关键问题：0
     警告：2
     准备归档：是（有警告）

     建议：
     1. 为会话超时场景添加测试
     2. 考虑重构为事件驱动（如设计所述），或更新 design.md

verify 检查的内容：

Verify 不会阻止归档，但会显示你可能想要先解决的问题。

Archive: 完成变更

/opsx:archive 完成变更并将其移动到归档：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

You: /opsx:archive

AI:  正在归档 add-auth...

     工件状态：
     ✓ proposal.md 存在
     ✓ specs/ 存在
     ✓ design.md 存在
     ✓ tasks.md 存在（12/12 任务完成）

     Delta 规范：尚未同步到主规范
     → 现在要同步吗？

You: 是

AI:  ✓ 已将规范同步到 openspec/specs/auth/spec.md
     ✓ 移动到 openspec/changes/archive/2025-01-24-add-auth/

     变更归档成功。

如果规范未同步，归档会提示。它不会因未完成的任务而阻止，但会警告。

何时使用什么

/opsx:ff vs /opsx:continue

经验法则： 如果你能够预先描述完整范围，使用 /opsx:ff。如果你在过程中弄清楚，使用 /opsx:continue。

何时更新 vs 开始新变更

一个常见问题：何时更新现有变更是可以的，何时应该开始新的变更？

更新现有变更时：

• 相同意图，执行优化
• 范围缩小（MVP 优先，其余稍后）
• 学习驱动的更正（代码库不是你预期的）
• 基于实现发现的设计调整

开始新变更时：

• 意图根本改变
• 范围爆发到完全不同的工作
• 原始变更可以独立标记为"完成"
• 补丁会比阐明更混乱

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

                 ┌─────────────────────────────────────┐
                 │     这是相同的工作吗？              │
                 └──────────────┬──────────────────────┘
                                │
             ┌──────────────────┼──────────────────┐
             │                  │                  │
             ▼                  ▼                  ▼
      相同意图？       >50% 重叠？      原始可以
      相同问题？      相同范围？        在没有这些
             │                  │          变更的情况下
             │                  │          "完成"？
   ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
   │                 │  │             │   │               │
  YES               NO YES           NO  NO              YES
   │                 │  │             │   │               │
   ▼                 ▼  ▼             ▼   ▼               ▼
UPDATE            NEW  UPDATE       NEW  UPDATE          NEW

示例：“添加暗模式”

• “还需要支持自定义主题” → 新变更（范围爆发）
• “系统首选项检测比预期更难” → 更新（相同意图）
• “让我们先发布切换，稍后添加首选项” → 更新然后归档，然后新变更

最佳实践

保持变更聚焦

每个更改一个逻辑工作单元。如果你正在"添加功能 X 并且还重构 Y"，考虑两个单独的变更。

为什么重要：

• 更容易审查和理解
• 更清晰的归档历史
• 可以独立发布
• 更简单的回滚（如果需要）

为不明确的需求使用 /opsx:explore

在承诺变更之前，探索问题空间：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

You: /opsx:explore

AI:  你想探索什么？

You: 我们应该如何处理 API 的速率限制？

AI:  让我调查你当前的设置和选项...
     [研究代码库，考虑模式]

     我看到我们可以采用三种方法：
     1. 基于中间件（简单，每端点）
     2. Redis 后端（可扩展，共享状态）
     3. 每用户令牌桶（公平，复杂）

     你当前的堆栈建议 #1 或 #2。你的规模如何？

探索在创建工件之前澄清思维。

在归档前验证

使用 /opsx:verify 检查实现是否与工件匹配：

1
2
3
4
5
6
7
8
9

You: /opsx:verify

AI:  正在验证 add-dark-mode...

     ✓ tasks.md 中的所有任务都已检查
     ✓ 规范中的需求有相应的代码
     ✓ 设计决策反映在实现中

     准备归档！

在关闭变更之前捕获不匹配。

清楚地命名变更

好的名称让 openspec list 有用：

1
2
3
4
5

好的：                          避免：
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes
implement-2fa                  wip

命令快速参考

有关命令详细信息和选项，请参阅命令。

下一步

• 命令 - 完整命令参考和选项
• 概念 - 深入了解规范、工件和模式
• 自定义 - 创建自定义工作流

Harness Engineering — 缰绳工程

围绕 AI Agent 构建约束、反馈和质量保障的系统工程实践。
来源：花叔《Harness Engineering又他妈是啥？》
最后更新：2026年3月

概述

Harness（缰绳/马具）指的是套在 AI 身上让它能被引导的那整套东西——没有它，AI 就是乱跑的野马，能力再强也白搭。Harness Engineering 是围绕 AI Agent 设计这套系统的工程实践。

三层递进关系

Context 是 Harness 的一部分，Harness 还多管了约束、反馈和质量检查。

核心证据

LangChain 案例

• Terminal Bench 2.0：成绩从 52.8% → 66.5%，排名 Top 30 → Top 5
• 模型完全没换，只改了：系统提示词、工具配置、中间件钩子
• 结论：模型可能已经不是瓶颈，瓶颈是你给它搭的环境

OpenAI Codex 实验

• 3→7 个工程师，5 个月，100 万行代码 beta 产品，零行手写
• ~1500 个 PR，每人每天 3.5 个 PR，速度约传统 10 倍
• 隐忧：速度快 ≠ 质量好，长期维护成本未知

Martin Fowler 的三块拆解

1. 上下文工程（Context Engineering）

• 给模型一张地图，不是 1000 页的说明书
• 维护持续更新的代码库知识库 + agent 能实时看到的系统状态
• 上下文是稀缺资源，塞太多反而挤占干活的空间

2. 架构约束（Architectural Constraints）

• 不光靠 AI 自检，还有 linter、结构测试在旁边盯着
• 硬规则，不遵守就编译不过

3. 垃圾回收（Garbage Collection）

• 专门一个 agent 周期性运行，只干一件事：找文档矛盾和架构违规
• 一个专职找茬的 AI

Anthropic 的三 Agent 架构

灵感来自生成对抗网络（GAN）：训练一个专门的评估者让它一直挑刺，比让生成者自己检查自己管用得多。

额外发现：Claude Sonnet 4.5 有上下文焦虑——上下文太多表现反而变差，必须定期清空重来。Harness 不是越大越好。

实践要素

配置文件（活的规则）

• CLAUDE.md / .cursorrules / CONVENTIONS.md 都是 harness 的一部分
• 每次 agent 犯错，就工程化一个方案，让它再也犯不了同样的错（Mitchell Hashimoto 方法）
• 文件是活的，一直在长

Hooks（物理拦截）

• 在 agent 关键操作前后注入脚本
• 编辑文件前自动跑 linting，生成代码后自动做类型检查
• 这不是 prompt 里写的"请注意规范"，是物理上拦住它

Skills（按需加载）

• 每个 skill 是独立能力包，平时不占 context，需要时才调

让 AI 查 AI

• 写完后开新对话，把结果贴进去：“找出所有问题”
• 第二个 AI 能发现第一个漏掉的很多问题

三条起步建议

1. 给地图不给说明书 — CLAUDE.md 应该像地图（项目结构、文件关系、关键约束），不要把每步写死
2. 每次犯错加一条规则 — 空文件开始，三个月后就是你的 harness，高度定制
3. 让 AI 查 AI — 别让 AI 自己查自己，用独立的评估者

Martin Fowler 的警告

如果太早把人类从「in the loop」移到「on the loop」，将来可能没人真正懂得怎么回事，也就没人能设计好的 harness。

现在能设计好 harness 的人，都是有丰富经验的老手。问题在于：不管积累的是什么经验，足够多的经验本身就是设计 harness 的前提。没有捷径，换了个赛道而已。

与历史工程实践的联系

• 航天工程 — 60 年前 NASA 就在做类似的事：约束、反馈循环、冗余检查、异常处理
• 工业控制 — PLC 编程里的安全联锁机制就是一种 harness
• AI 圈不是发明了 harness engineering，是终于意识到自己需要学几十年前就有的工程纪律

与其他概念的关系

• OpenSpec — 规范驱动开发，是 harness 中"约束"层面的具体实践
• CLAUDE.md — Claude Code 的项目配置文件，是 harness 的核心载体之一
• .cursorrules — Cursor 的项目配置文件

AI Coding Agents 概览

本目录汇总了当前主流的 AI 编程助手和 Agent 工具。
最后更新：2026年3月

快速对比

分类说明

AI IDE（AI 原生编辑器）

深度集成 AI 能力的代码编辑器，提供沉浸式的 AI 编程体验：

• Cursor - 最流行的 AI 编辑器，支持 Cloud Agents、Composer 2、.cursorrules 配置
• Windsurf - Cascade Flow 功能强大，实时预览特色鲜明

IDE 插件 + 平台

在现有 IDE 和平台中添加 AI 能力：

• GitHub Copilot - 业界标准，深度 GitHub 集成，现在有免费计划

对话式助手

通过对话方式进行编程辅助：

• Claude - 推理能力最强，支持 CLAUDE.md 配置，Claude Code 终端工具
• ChatGPT - 通用性强，生态丰富，GPTs 商店

命令行工具

在终端中使用的 AI 编程工具：

• OpenCode - 131K+ Stars，多平台支持，免费模型
• Aider - 开源免费，终端原生，Git 集成，CONVENTIONS.md 配置

规范驱动开发

让 AI 编码助手在写代码前先对齐需求的规范框架：

• OpenSpec - 轻量级 SDD 框架，支持 20+ AI 工具，Propose → Apply → Archive 工作流

工程方法论

围绕 AI Agent 构建约束、反馈和质量保障的方法论：

• Harness Engineering - 缰绳工程：Prompt → Context → Harness 三层递进，让 AI Agent 安全高效运行的系统工程实践

Web 开发工具

基于浏览器的 AI 开发工具：

• Replit Agent - 云端 IDE，支持全栈应用快速生成

核心功能对比

项目配置文件

模型支持

选择建议

🎯 日常开发首选

• Cursor 或 Windsurf - 如果想要 AI 深度集成到编辑器
• GitHub Copilot Free - 预算有限时的入门选择

💰 预算有限

• GitHub Copilot Free - 免费计划，功能足够入门
• Aider - 开源免费，只需 API 费用
• OpenCode - 开源免费，多模型支持

🧠 复杂任务

• Claude Opus 4.6 - 超强推理，适合架构设计
• Cursor Agent 模式 - 端到端自主开发

⌨️ 终端爱好者

• OpenCode - 多平台，免费模型，社区活跃
• Aider - CLI 原生，Git 集成，高度可控
• Claude Code - Anthropic 官方终端工具

🏢 企业团队

• GitHub Copilot Business - 团队管理成熟
• Cursor Business - 隐私控制完善，企业级功能
• Windsurf Enterprise - 支持自托管

🚀 快速原型

• Replit Agent - 云端快速开发，团队协作

🎨 前端开发

• Windsurf - 实时预览，Cascade 模式
• Cursor/Windsurf - 全栈前端开发

趋势与展望 (2026)

1. Agent 化 - 从辅助工具到自主执行者的发展趋势
2. 多模型支持 - 越来越多的工具支持多种 LLM
3. 上下文增强 - RAG 技术让 AI 更好理解代码库
4. 开源化 - OpenCode、Aider 等开源工具越来越受欢迎
5. 免费计划 - GitHub Copilot Free 等免费计划降低门槛
6. 云端化 - Cloud Agents 允许可并行处理任务
7. 配置文件 - 项目级配置文件（.cursorrules、CLAUDE.md）成为标准

相关资源

• Cursor 官方文档
• GitHub Copilot 文档
• Claude API 文档
• Claude Code 文档
• Aider 文档
• OpenCode GitHub
• Replit 文档
• Windsurf 文档
• Cursor vs OpenCode 对比 ⭐ 新增

OpenSpec — 规范驱动开发 (Spec-Driven Development)

AI 编程助手的规范驱动开发框架，让人类与 AI 在写代码之前先对齐需求。
最后更新：2026年3月

概述

OpenSpec 是一个轻量级的规范层，核心理念是 先达成共识，再编写代码。它通过结构化的 Markdown 规范文档，让人类和 AI 在编码前就需求、设计和实现计划达成一致，从而解决 AI 编码中"需求模糊、结果不可预测"的问题。

• GitHub: Fission-AI/OpenSpec
• 官网: intent-driven.dev
• 许可: MIT
• 要求: Node.js 20.19.0+

核心理念

1
2
3
4
5

→ 流式而非僵化 (fluid not rigid)
→ 迭代而非瀑布 (iterative not waterfall)
→ 简单而非复杂 (easy not complex)
→ 支持棕地项目，不限于绿地 (built for brownfield not just greenfield)
→ 从个人项目到企业级可扩展 (scalable from personal projects to enterprises)

工作流程

OpenSpec 的核心是一个三阶段循环：Propose → Apply → Archive

1. Propose（提案）

通过斜杠命令让 AI 生成规范文档：

1

/opsx:propose "add-dark-mode"

AI 会自动创建 openspec/changes/add-dark-mode/ 目录，包含：

• proposal.md — 为什么要做、改变什么
• specs/ — 需求和场景
• design.md — 技术方案
• tasks.md — 实现清单

2. Apply（实施）

确认规范后，让 AI 按照任务清单执行：

1

/opsx:apply

AI 会按 tasks.md 中的清单逐步实现，完成后标记每个任务。

3. Archive（归档）

实施完成后归档，将变更合并到源规范中：

1

/opsx:archive

归档后，delta 规范合并到主规范，保持单一信息源（Single Source of Truth）。

快速开始

1
2
3
4
5
6
7
8
9

# 全局安装
npm install -g @fission-ai/openspec@latest

# 在项目中初始化
cd your-project
openspec init

# 告诉 AI 开始
/opsx:propose "your feature idea"

斜杠命令

简化工作流（推荐）

扩展工作流

通过 openspec config profile 切换到扩展模式后可用：

三种规范文档

1. Delta Specs（变更规范）

标记为 ADDED、MODIFIED、REMOVED，清晰传达提案内容，无需对比整个文档。

2. Source of Truth（源规范）

系统当前状态的唯一权威参考，所有 delta 变更最终合并到此文档。

3. Archived Specs（归档规范）

已合并的 delta 规范历史记录，保留决策脉络和审计轨迹。

支持的 AI 工具

OpenSpec 支持 20+ AI 编程助手，包括但不限于：

• Claude Code
• Cursor
• GitHub Copilot
• Windsurf
• Aider
• OpenCode
• ChatGPT
• Replit Agent

与同类工具对比

适用场景

• 需求频繁变化 — 需要快速迭代规范
• AI 编码结果不可预测 — 需要事先对齐需求
• 棕地项目 — 现有项目需要增量引入规范
• 团队协作 — 需要统一的信息源
• 功能交互复杂 — 需要检测功能间 unintended interactions

最佳实践

1. 推荐模型：使用高推理能力模型（如 Opus 4.5、GPT 5.2）效果最佳
2. 上下文管理：开始实施前清空上下文窗口，保持干净的上下文
3. 小步迭代：每次提案保持小范围、聚焦的变更
4. 及时归档：完成后尽快归档，保持源规范的准确性

CLI 常用命令

1
2
3
4
5
6
7
8
9
10
11

# 初始化项目
openspec init

# 配置 Profile
openspec config profile

# 更新 agent 指令
openspec update

# 升级 OpenSpec
npm install -g @fission-ai/openspec@latest

文档目录

• 入门

  • 入门指南 - 了解 OpenSpec 如何工作，创建第一个变更
  • 工作流程 - 常见的工作流模式和最佳实践
  • Cursor IDE 专用指南 - Cursor IDE 的四个命令和 proposal 改进方法

• 命令参考

  • 斜杠命令 - AI 助手中的斜杠命令（如 /opsx:propose）
  • CLI 参考 - 终端命令参考

• 核心概念

  • 核心概念 - 深入了解规范、变更、工件和 delta 规范
  • 支持的工具 - 支持的 AI 编程助手列表

• 高级主题

  • 自定义配置 - 自定义工作流和项目配置
  • 多语言指南 - 配置非英语语言支持

相关资源

• OpenSpec GitHub
• OpenSpec 官方文档
• OpenSpec 中文版
• OpenSpec Skills 扩展
• OpenSpec Discord