基于项目的实践经验总结。
OpenSpec 是一个规范驱动开发（Spec-Driven Development, SDD）框架，专为 AI 编程助手设计。它通过在编写代码之前先定义规范，确保人与 AI 对需求达成一致。
传统开发流程通常是：需求 → 直接编码 → 测试 → 交付。
规范驱动开发的流程是：需求 → 编写规范 → 验证规范 → 编码实现。
这种方式的优势在于：
| 理念 | 含义 |
|---|---|
| 流动而非僵化 | 文档可以随时更新，没有严格的阶段门槛 |
| 迭代而非瀑布 | 支持增量添加需求，逐步完善 |
| 简单而非复杂 | 只需要 Markdown 文件，无复杂工具链 |
| 兼顾存量与新建项目 | 既适用于已有代码库（Brownfield），也适用于全新项目（Greenfield） |
术语解释：
- Brownfield（存量项目）：指已经存在的、有历史代码的项目。OpenSpec 可以逐步引入，不必重构现有代码。
- Greenfield（新建项目）：指从零开始的新项目。OpenSpec 可以从一开始就建立规范体系。
本章节将介绍如何在本地环境中安装 OpenSpec CLI 工具，涵盖从环境检查到多平台包管理器安装的完整步骤，以确保后续操作的顺利执行。
检查 Node.js 版本：
node --version
使用 npm 安装：
# 全局安装最新版的 openspec
npm install -g @fission-ai/openspec@latest
使用其他包管理器：
# pnpm（推荐，速度更快）
pnpm add -g @fission-ai/openspec@latest
# yarn
yarn global add @fission-ai/openspec@latest
# bun
bun install -g @fission-ai/openspec@latest
# 查看版本号
openspec --version
# 查看帮助信息
openspec --help
安装成功后，你将看到类似输出(或者主动执行 openspec --version 查看版本号)：
1.3.1
自 v1.3.0 起，为了避免在某些终端（如 PowerShell）中出现编码问题，Shell 自动补全功能改为手动开启（Opt-in）。
如果你希望在终端中使用 openspec 的命令补全，可以运行以下命令生成并安装补全脚本（支持 bash、zsh、fish 等）：
# 查看补全命令帮助
openspec completion --help
项目初始化是引入 OpenSpec 流程的第一步，通过生成标准化的目录结构和 AI 配置文件，为后续的规范驱动开发奠定基础，并自动完成与 IDE 和大模型工具的对接。
openspec init 是 OpenSpec 的入口命令，在项目根目录执行后，它会：
--tools 参数跳过交互）openspec/ 工作目录（含 config.yaml、changes/、specs/）# 进入你的项目目录
cd your-project
# 执行初始化命令
openspec init
openspec init 默认是交互式的，会询问你要配置哪些 AI 工具：
? Which AI tools do you want to configure? (Press <space> to select)
❯◉ Claude Code
◯ Cursor
◯ GitHub Copilot
◯ Cline
◯ Windsurf
...
使用空格键选择，回车键确认。
Qoder 用户提示：如果你使用的是 Qoder IDE，请选择 Qoder。OpenSpec v1.2.0 对 Qoder 提供原生支持，会自动在
.qoder/commands/opsx/和.qoder/skills/目录生成对应的命令和 Skills 文件。
如果需要在脚本或 CI/CD 环境中使用，可以跳过交互式配置：
# 跳过所有工具配置
openspec init --tools none
# 配置所有支持的 AI 工具
openspec init --tools all
# 只配置特定工具（逗号分隔）
openspec init --tools claude,cursor
# 配置 Qoder
openspec init --tools qoder
常用工具标识符列表：
| 工具名称 | --tools 参数值 |
|---|---|
| Claude Code | claude |
| Qoder | qoder |
| Cursor | cursor |
| JetBrains Junie | junie |
| Lingma IDE | lingma |
| ForgeCode | forgecode |
| IBM Bob | bob |
| GitHub Copilot | github-copilot |
| Cline | cline |
| Windsurf | windsurf |
| Amazon Q Developer | amazon-q |
| Gemini CLI | gemini |
| Continue | continue |
| Roo Code | roocode |
完整列表：运行
openspec init --help可查看当前版本支持的所有工具标识符。
your-project/
├── openspec/ # OpenSpec 工作目录
│ ├── config.yaml # 项目配置（技术栈、约定规则等，注入 AI 请求）
│ ├── changes/ # 变更提案目录（每个功能/变更一个文件夹）
│ └── specs/ # 主规范目录（已归档的规范）
├── .qoder/ # Qoder 专属目录（示例）
│ ├── commands/opsx/ # /opsx 斜杠命令（供 IDE 直接调用）
│ │ ├── propose.md
│ │ ├── explore.md
│ │ ├── apply.md
│ │ └── archive.md
│ └── skills/ # Agent Skills（AI 自动检测并加载）
│ ├── openspec-propose/SKILL.md
│ ├── openspec-explore/SKILL.md
│ ├── openspec-apply-change/SKILL.md
│ └── openspec-archive-change/SKILL.md
└── ... (项目其他文件)
注意：
openspec init会根据你选择的 AI 工具，在对应目录生成命令和 Skills 文件。例如，选择 Claude Code 则生成.claude/commands/opsx/和.claude/skills/，选择 Qoder 则生成.qoder/commands/opsx/和.qoder/skills/。
| 文件/目录 | 用途 | 是否必需 |
|---|---|---|
config.yaml |
项目背景、技术栈、约束条件、每类文档的规则注入 | 推荐填写 |
changes/ |
存放活跃的变更提案 | 必需 |
specs/ |
存放已归档的规范 | 可选 |
与旧版的区别：v1.0.0 起，
openspec/AGENTS.md和openspec/project.md已移除。项目上下文统一写入openspec/config.yaml的context:字段，该字段会被注入到每一次 AI 规划请求中，比旧方式更可靠。
config.yaml 结构示例：
schema: spec-driven
context: |
Tech stack: TypeScript, React, Node.js
Testing: Jest with React Testing Library
API: RESTful, documented in docs/api.md
We maintain backwards compatibility for all public APIs
rules:
proposal:
- Include rollback plan for risky changes
specs:
- Use Given/When/Then format for scenarios
design:
- Include sequence diagrams for complex flows
tasks:
- Break tasks into max 2-hour chunks
在 OpenSpec 中，所有的功能开发、Bug 修复、架构变更都以“变更提案（Change）”为单位进行管理。
方式一：使用斜杠命令（Slash Commands，推荐，一步完成）:
/opsx:propose <description>
这个命令会：
add-user-auth）openspec/changes/<name>/proposal.md、design.md、specs/、tasks.md 所有文档方式二：仅创建变更目录（扩展工作流 Profile 下使用）:
斜杠命令：
/opsx:new <change-name>
等价 CLI 命令：
# 仅初始化变更目录结构，不创建任何初始文档
openspec new change <change-name>
仅初始化变更目录结构，不创建任何文档；适合配合 /opsx:continue 逐步手动生成文档时使用。
命名建议：使用 kebab-case（短横线分隔），名称应简洁明了地描述变更内容。
# 好的命名示例
add-user-authentication
add-payment-module
fix-login-timeout
# 不好的命名示例
feature1 # 太模糊
addUserAuth # 应使用 kebab-case
以下示例展示了如何使用斜杠命令快速初始化一个核心业务模块的变更，并由 AI 自动生成全套的骨架文档。
/opsx:propose "实现 AI Infrastructure CMDB 核心功能"
AI 将自动创建变更并生成所有规划文档：
✓ Created change directory: openspec/changes/ai-infra-cmdb-core/
✓ Created proposal.md
✓ Created design.md
✓ Created specs/ directory
✓ specs/accelerator-management/spec.md
✓ Created tasks.md
✓ Created .openspec.yaml
Change 'ai-infra-cmdb-core' created successfully!
openspec/changes/<change-name>/
├── .openspec.yaml # 变更元数据（ID、状态、创建时间等，由 CLI 自动管理）
├── proposal.md # 提案文档【必填】描述 Why 和 What
├── design.md # 技术设计文档（架构、数据模型、API 设计等）
├── tasks.md # 实现任务清单（按里程碑组织的待办事项）
└── specs/ # 规范目录（存放能力规范文件）
├── <capability-1>/
│ └── spec.md # 能力规范（使用 Requirement + Scenario 格式）
├── <capability-2>/
│ └── spec.md
| 文件 | 作用 | 是否必需 | 格式要求 |
|---|---|---|---|
proposal.md |
说明“为什么做”和“做什么” | 必需 | 必须包含 ## Why 和 ## What Changes（验证器强制检查）；推荐包含 ## Capabilities（AI 工作流所需） |
specs/<capability>/spec.md |
详细的需求和验收场景 | 必需 | 必须使用 Delta Header + Requirement + Scenario 格式 |
design.md |
技术实现方案 | 推荐 | 无严格格式要求 |
tasks.md |
实现任务清单 | 推荐 | 无严格格式要求 |
提案 (斜杠命令) → 编写规范 → 验证 (validate) → 实现 (apply) → 归档 (archive)
/opsx:propose <description>（一步生成所有规划文档）openspec validate <name>/opsx:apply 按照 tasks.md 执行开发/opsx:archive 将变更中的规范增量（Delta）合并回 openspec/specs/ 主规范目录，并清理 openspec/changes/ 下的临时目录，标志着该功能规范已正式「上线」OpenSpec 强调文档的结构化和规范化，通过明确定义 proposal.md 的提案架构和 spec.md 的能力场景契约，确保 AI 助手和开发人员能够无歧义地解析需求并生成可靠的代码。请务必遵循这些格式，否则 openspec validate 会失败。
模板文件：OpenSpec 内置了所有文档模板，可通过
openspec templates命令查看各模板路径，或直接使用/opsx:propose//opsx:new斜杠命令自动生成完整文档。
核心要求： proposal.md 必须包含 ## Why 和 ## What Changes 两个验证器强制检查的必需章节；推荐包含 ## Capabilities 章节，作为 AI 自动生成 specs/<name>/spec.md 文件的关键输入。
OpenSpec 的设计理念是“先想清楚为什么做，再决定做什么，再明确影响哪些能力”：
## Why - 说明变更的背景、问题和动机（验证器强制检查）## What Changes - 说明具体要添加、修改或删除什么（验证器强制检查）## Capabilities - 列出 New / Modified Capabilities，驱动 specs/<name>/spec.md 文件的生成（推荐，AI 工作流所需）内置模板路径可通过
openspec templates命令查看；/opsx:propose斜杠命令会自动生成填充好的完整提案。
必需章节结构：
proposal.md 结构：
├── ## Why 【必需 - 验证器强制检查】
│ ├── ### Background（背景）
│ ├── ### Problem Statement（问题描述）
│ └── ### Alternatives Considered（备选方案）
├── ## What Changes 【必需 - 验证器强制检查】
│ ├── ### New Resources Added（新增资源）
│ └── ### New Capabilities（功能点简述，自然语言概括即可）
├── ## Capabilities 【推荐 - AI 工作流所需，驱动 spec 文件生成】
│ ├── ### New Capabilities（kebab-case 标识符列表，每项对应 specs/<name>/ 目录）
│ └── ### Modified Capabilities（已有能力的 requirement 变更）
├── ## Impact（影响范围）
├── ## Scope（范围，可选）
│ ├── ### In Scope
│ └── ### Out of Scope
├── ## Goals（成功标准，可选）
└── ## References（参考链接，可选）
注意：章节标题必须完全匹配 ## Why 和 ## What Changes（区分大小写）。
核心要求： specs/ 必须使用能力文件夹（capability folders），每个能力一个文件夹。
specs/
├── accelerator-management/ # 能力一：加速器管理
│ └── spec.md
├── training-job-lifecycle/ # 能力二：训练任务生命周期
│ └── spec.md
├── inference-service/ # 能力三：推理服务
│ └── spec.md
└── relationship-management/ # 能力四：关系管理
└── spec.md
重要规则：
核心要求： 必须使用 Delta Header + Requirement + Scenario 格式。
| 元素 | 格式 | 示例 |
|---|---|---|
| Delta Header | ## ADDED/MODIFIED/REMOVED Requirements |
## ADDED Requirements |
| 需求标题 | ### Requirement: <标题> |
### Requirement: GPU 自动发现 |
| 场景标题 | #### Scenario: <标题> |
#### Scenario: NVIDIA GPU 发现 |
| 场景内容 | Gherkin 格式 | Given/When/Then |
Delta Header 选择说明：
| Delta Header | 适用场景 |
|---|---|
## ADDED Requirements |
本次变更新增的能力或需求 |
## MODIFIED Requirements |
对已有规范中某个 Requirement 的修改 |
## REMOVED Requirements |
明确废弃或删除的需求 |
内置模板路径可通过
openspec templates查看。
必需格式结构：
spec.md 结构：
├── # 能力名称
├── ## Overview（概述，推荐）
│ - 能力简介
│ - 解决的问题
└── ## ADDED/MODIFIED/REMOVED Requirements 【必需】
├── ### Requirement: <标题>
│ ├── **Priority**: P0/P1/P2
│ ├── **Rationale**: ...
│ └── #### Scenario: <标题>
│ └── Given/When/Then
以下示例展示核心 Requirement + Scenario 结构。完整示例（含
## Overview段落）参见examples/openspec/changes/v1-mvp/specs/domain-model/spec.md（电商领域模型规范）：
## ADDED Requirements
### Requirement: 商品实体定义
系统 SHALL 定义商品实体，包含唯一标识、名称、价格和库存。
**Priority**: P0 (Critical)
**Rationale**: 商品是电商系统的核心实体，是所有交易的基础。
#### Scenario: 创建有效商品
Given 需要创建新商品
When 提供商品信息 { id, name, priceCents, stock }
Then 商品实体创建成功
And id 格式为 prod_xxxx
And priceCents >= 0
And stock >= 0
❌ 错误示例：
## ADDED Requirements
### REQ-001: GPU Discovery # 错误：使用了自定义编号
System SHALL discover GPUs.
#### Scenario: Discovery # 错误：场景标题太模糊
✅ 正确写法：
## ADDED Requirements
### Requirement: GPU 自动发现 # 正确：使用标准格式
系统应自动发现集群中的 GPU 设备。
**Priority**: P0 (Critical)
**Rationale**: 核心功能需求。
#### Scenario: NVIDIA GPU 发现 # 正确：场景标题具体
Given 一个包含 NVIDIA GPU 节点的 Kubernetes 集群
When 发现代理部署到集群
Then 所有 NVIDIA GPU 被枚举并记录到 CMDB
技术设计文档没有严格的格式要求，但建议包含以下章节。
内置模板路径可通过
openspec templates查看。
建议章节结构：
| 章节名称 | 建议内容 |
|---|---|
| Architecture Overview | 系统整体架构图（建议使用 Mermaid 或 ASCII 图）及层次关系说明 |
| Core Components | 核心模块列表，每个模块的职责、边界和内部实现要点 |
| Data Model | 关键实体的字段定义、类型、约束及实体间关系 |
| API Design | 接口路由、请求/响应格式、错误码规范 |
| Integration Patterns | 与外部系统/模块的集成方式，包括事件、队列、同步调用等 |
| Technology Stack | 所选技术及库、选型理由和备选方案对比 |
| Security | 身份认证、权限控制、数据加密、输入校验等安全设计要点 |
| Deployment | 环境要求、部署步骤、回滚方案 |
任务清单用于将设计拆解为可执行的实现步骤。建议按里程碑组织，使用 GitHub 风格的 Markdown 任务列表，以便在 IDE 中直接勾选。
内置模板路径可通过
openspec templates查看。
建议章节结构：
- [x] / - [ ] 标记完成进度，方便 IDE 内直观查看。示例：
## Milestone 1 - Domain Model
### Definition of Done
- 完成所有 P0 Requirement 的实现
- `openspec validate v1-mvp` 验证通过
- 单元测试覆盖所有领域实体
### Tasks
- [x] 定义 Product 实体类型（id、name、priceCents、stock）
- [x] 定义 Cart / CartItem 实体类型
- [ ] 定义 Order / OrderItem 实体类型
- [ ] 实现领域实体的编排验证逻辑
## Milestone 2 - Service Layer
### Definition of Done
- 所有服务方法均有对应集成测试
### Tasks
- [ ] 实现 CatalogService.getProduct / listProducts
- [ ] 实现 CartService.addItem / removeItem
- [ ] 实现 OrderService.checkout
proposal.md 必需章节：
├── ## Why 【必需 - 验证器强制检查】
│ ├── ### Background
│ ├── ### Problem Statement
│ └── ### Alternatives Considered
├── ## What Changes 【必需 - 验证器强制检查】
│ ├── ### New Resources Added
│ └── ### New Capabilities
└── ## Capabilities 【推荐 - AI 工作流所需，驱动 spec 文件生成】
├── ### New Capabilities
└── ### Modified Capabilities
specs/[capability]/spec.md 必需格式：
├── # 能力名称
├── ## Overview（推荐）
└── ## ADDED/MODIFIED/REMOVED Requirements 【必需】
├── ### Requirement: <标题>
│ ├── **Priority**: P0/P1/P2
│ ├── **Rationale**: ...
│ └── #### Scenario: <标题>
│ └── Given/When/Then
| 模板 | 对应内置文件（通过 openspec templates 查看完整路径） |
用途 |
|---|---|---|
| proposal.md 模板 | schemas/spec-driven/templates/proposal.md |
提案文档模板 |
| spec.md 模板 | schemas/spec-driven/templates/spec.md |
能力规范模板 |
| design.md 模板 | schemas/spec-driven/templates/design.md |
技术设计模板 |
| tasks.md 模板 | schemas/spec-driven/templates/tasks.md |
任务清单模板 |
在完成规范文档编写后，通过严格的本地校验流程可以提前拦截格式与结构问题，确保文档完全符合 OpenSpec 语法规范，从而为后续的 AI 自动化执行提供准确无误的输入。
完成文档编写后，使用验证命令检查格式是否正确：
# 验证指定的变更文档是否符合格式要求
openspec validate <change-name>
验证成功时显示：
Change '<change-name>' is valid
验证失败时会显示具体错误信息。
错误信息：
✗ [ERROR] file: Change must have at least one delta. No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one "#### Scenario:" block. Tip: run "openspec change show <change-id> --json --deltas-only" to inspect parsed deltas.
原因：specs/ 目录结构不正确，或者缺少有效的 Delta Header。
解决方案：
确保 specs/ 下有能力文件夹：
specs/
└── your-capability/ # 能力文件夹
└── spec.md # 规范文件
确保 spec.md 中有 Delta Header：
## ADDED Requirements
### Requirement: 某个需求
...
常见错误：
specs/
└── spec.md # ❌ 错误：直接放在 specs/ 根目录
错误信息：
✗ [ERROR] cap1/spec.md: Delta sections ## ADDED Requirements were found, but no requirement entries parsed. Ensure each section includes at least one "### Requirement:" block (REMOVED may use bullet list syntax).
原因：需求标题格式不正确。
错误示例：
## ADDED Requirements
### REQ-001: GPU Discovery # ❌ 错误：使用了自定义编号
### GPU Discovery # ❌ 错误：缺少 "Requirement:" 前缀
### requirement: GPU Discovery # ❌ 错误："requirement" 应首字母大写
正确格式：
## ADDED Requirements
### Requirement: GPU 自动发现 # ✓ 正确格式
错误信息：
✗ [ERROR] cap1/spec.md: ADDED "test" must include at least one scenario
原因：每个需求必须至少有一个场景。
错误示例：
### Requirement: GPU 自动发现
系统应自动发现 GPU 设备。
# ❌ 没有场景块
正确格式：
### Requirement: GPU 自动发现
系统应自动发现 GPU 设备。
**Priority**: P0 (Critical)
**Rationale**: 核心功能需求。
#### Scenario: NVIDIA GPU 发现
Given 一个包含 NVIDIA GPU 节点的 Kubernetes 集群
When 发现代理部署到集群
Then 所有 NVIDIA GPU 被枚举并记录到 CMDB
如果验证失败但不确定原因，可以查看解析后的结构：
# 查看解析后的 Delta 结构信息
openspec show <change-name> --json --deltas-only
这会输出 JSON 格式的解析结果，帮助你了解 OpenSpec 是如何解析你的文档的。
# 查看当前变更的状态与文档完成进度
openspec status --change <change-name>
提示：自 v1.3.0 起，如果当前不存在任何变更，
openspec status命令会优雅地退出（提示无变更），而不再抛出致命错误。
输出示例：
Change: ai-infra-cmdb-core
Schema: spec-driven
Progress: 1/4 artifacts complete
[x] proposal
[ ] design
[ ] specs
[-] tasks (blocked by: design, specs)
在运行 openspec validate 之前，请确认：
## Why 章节## What Changes 章节## ADDED/MODIFIED/REMOVED Requirements）### Requirement: <标题> 格式#### Scenario: <标题> 块OpenSpec CLI 提供了一套完整的命令行工具，用于管理从项目初始化、变更提案创建、规范验证到最终归档的全生命周期。本节整理了日常开发中最常用的命令及其典型使用场景。
| 命令 | 说明 | 示例 |
|---|---|---|
openspec init |
初始化 OpenSpec 项目 | openspec init --tools qoder |
openspec new change <name> |
仅创建变更目录结构 | openspec new change add-user-auth |
openspec update |
更新 AI 技能和命令文件 | openspec update |
| 命令 | 说明 | 示例 |
|---|---|---|
openspec view |
打开终端交互界面 | openspec view |
openspec status --change <name> |
查看变更状态 | openspec status --change user-auth |
openspec validate <name> |
验证变更文档格式 | openspec validate user-auth |
openspec list --changes |
列出所有变更 | openspec list --changes |
openspec list --specs |
列出所有规范 | openspec list --specs |
openspec show <name> |
显示变更详情 | openspec show user-auth --json --deltas-only |
| 命令 | 说明 | 示例 |
|---|---|---|
openspec archive <name> |
归档已完成的变更（将 Delta 合并至 specs/ 主目录并清理 changes/ 临时目录） |
openspec archive user-auth |
| 命令 | 说明 | 示例 |
|---|---|---|
openspec config list |
查看当前配置 | openspec config list |
openspec config profile |
设置工作流 Profile | openspec config profile |
openspec templates |
查看内置文档模板的绝对路径 | openspec templates |
openspec schemas |
列出可用 Schema | openspec schemas |
openspec --version |
查看版本号 | openspec --version |
openspec --help |
查看帮助信息 | openspec --help |
openspec [options] <command>
选项：
-V, --version 显示版本号
-h, --help 显示帮助信息
--no-color 禁用彩色输出
注意：
--json是各命令的独立选项，不是全局选项。例如openspec show <name> --json或openspec validate --json。
常用命令快速参考：
# 初始化项目
openspec init --tools none
# 创建变更目录（仅创建目录，不生成文档）
openspec new change <name>
# 列出所有变更 / 规范
openspec list --changes
openspec list --specs
# 验证变更
openspec validate <name>
# 查看状态
openspec status --change <name>
# 归档变更
openspec archive <name>
# 更新工具文件
openspec update
基于多个项目的实际落地经验，本节提炼了在编写提案、设计规范场景以及与 AI 助手协同工作时的最佳实践策略，帮助团队规避常见陷阱，最大化释放规范驱动开发的效能。
编写提案的核心在于清晰传达业务意图与系统边界。一份优秀的提案能够让团队成员与 AI 迅速理解项目背景，并为后续的技术实现划定明确的验收范围。
❌ 不好的 Why 章节：
## Why
我们需要添加用户认证功能。
✅ 好的 Why 章节：
## Why
### Background
当前系统没有用户认证功能，任何人都可以访问所有数据和功能。
这导致：
- 无法追踪操作日志的责任人
- 敏感数据缺乏保护
- 无法实现细粒度的权限控制
### Problem Statement
系统需要一个安全可靠的用户认证机制，支持：
- 用户名密码登录
- 第三方 OAuth 登录（GitHub、Google）
- 会话管理和安全退出
### Alternatives Considered
1. **自建认证系统**：完全控制，但开发维护成本高
2. **使用 Auth0**：功能完善，但费用较高
3. **使用 Keycloak**：开源免费，支持多种协议 ✓ 已选择此方案
规范编写旨在建立清晰的需求契约。合理的模块划分与适中的需求粒度不仅能提升文档的可读性，还能为 AI 提供精确的上下文。
场景描述是连接业务语言与技术验证的桥梁。采用标准的 Gherkin 语法能够消除歧义，确保每个场景都能转化为明确的可执行测试。
| 关键字 | 用途 | 示例 |
|---|---|---|
Given |
前置条件，描述系统初始状态 | Given 用户已登录系统 |
When |
触发动作 | When 用户点击"提交订单"按钮 |
Then |
预期结果 | Then 订单状态变为"待支付" |
And |
连接多个条件或结果 | And 用户收到订单确认邮件 |
Scenario: 使用信用卡支付订单
Given 用户已登录系统
And 购物车中有 2 件商品，总价 299 元
And 用户已绑定信用卡
When 用户选择"信用卡支付"并确认
Then 订单创建成功
And 从信用卡扣除 299 元
And 用户收到支付成功通知
And 库存减少 2 件
Scenario: 支付
Given 系统
When 支付
Then 成功
问题：
规范驱动并非僵化的瀑布流，而是拥抱变化的增量过程。在迭代开发中，保持文档与代码的同步更新，是维持系统一致性的关键。
openspec validate 确保格式正确openspec archive 归档变更充分发挥大模型潜力的关键在于合理利用工作流指令和上下文管理。通过结构化的交互模式，可以有效降低 AI 的幻觉并提升代码生成质量。
OpenSpec 1.0+ 引入了全新的 OPSX 工作流，替换了旧版的阶段锁定模式。所有命令均通过 openspec init 安装到 AI 工具对应目录。
默认 Core 配置（常用 4 个命令）:
| 命令 | 作用 |
|---|---|
/opsx:propose <description> |
一步创建变更并智能生成所有规划文档（AI 基于描述自动推断 kebab-case 目录名并填充 proposal/design/specs/tasks） |
/opsx:explore |
进入探索模式，思考问题、调查代码库，不写代码 |
/opsx:apply |
按照 tasks.md 实现任务 |
/opsx:archive |
完成并归档当前变更 |
扩展工作流命令（通过 openspec config profile 开启）
| 命令 | 作用 |
|---|---|
/opsx:new |
仅初始化变更目录结构，不创建文档 |
/opsx:continue |
按依赖顺序创建下一个文档（逐步模式） |
/opsx:ff |
快进生成所有规划文档（一步到位） |
/opsx:verify |
验证实现是否与规范一致 |
/opsx:sync |
将 Delta Spec 合并到主规范（不归档） |
/opsx:bulk-archive |
批量归档多个已完成的变更 |
/opsx:onboard |
带教 15 分钟全流程引导，适合新手上手 |
迁移说明：旧版命令（
/openspec:proposal、/openspec:apply、/openspec:archive）已在 v1.0.0 移除。修复映射关系：
/openspec:proposal→/opsx:propose/openspec:apply→/opsx:apply/openspec:archive→/opsx:archive
/opsx:explore 思考，明确后再 /opsx:propose将 OpenSpec 融入团队现有的研发流程中，需要建立配套的审查机制与文档维护习惯，从而确保规范体系在长期协作中不被破坏。
在 PR 审查时，检查 OpenSpec 文档：
本附录提供了 OpenSpec 支持的第三方生态工具列表、系统高级配置说明以及常见问题的详细解答，供开发者在遇到特定需求或环境适配时参考。
OpenSpec 支持 20+ AI 编程助手，以下是常用工具：
| 工具 | 类型 | 支持程度 |
|---|---|---|
| Claude Code | CLI + IDE | 完全支持 |
| Qoder | IDE | 完全支持 |
| Cursor | IDE | 完全支持 |
| JetBrains Junie | IDE 插件 | 完全支持 |
| Lingma IDE | IDE 插件 | 完全支持 |
| ForgeCode | IDE 插件 | 完全支持 |
| IBM Bob | IDE 插件 | 完全支持 |
| GitHub Copilot | IDE 插件 | 完全支持 |
| Cline | VS Code 插件 | 完全支持 |
| Windsurf | IDE | 完全支持 |
| Amazon Q Developer | IDE 插件 | 完全支持 |
| Gemini CLI | CLI | 完全支持 |
| Continue | IDE 插件 | 完全支持 |
| Aider | CLI | 支持（命令行工具，不支持 openspec init 自动生成指令） |
| Roo Code | VS Code 插件 | 完全支持 |
OpenSpec 收集匿名使用统计数据，用于改进产品。如需禁用：
# 方法一：设置环境变量
export OPENSPEC_TELEMETRY=0
# 方法二：使用通用遥测禁用标志
export DO_NOT_TRACK=1
# 方法三：在 shell 配置文件中永久设置
echo 'export OPENSPEC_TELEMETRY=0' >> ~/.zshrc # Zsh
echo 'export OPENSPEC_TELEMETRY=0' >> ~/.bashrc # Bash
在使用 OpenSpec 的过程中，团队通常会在规范边界、AI 协作边界以及规范演进等方面遇到一些典型困惑，以下整理了最常见的实践问题与解答，帮助开发团队更准确地理解 Spec 驱动的核心理念。
OpenSpec 与 OpenAPI 在软件开发生命周期中扮演着不同但互补的角色，前者侧重于业务行为约束，后者侧重于接口技术契约。
| 特性 | OpenSpec | OpenAPI/Swagger |
|---|---|---|
| 主要用途 | 需求规范驱动开发 | API 接口文档 |
| 文档类型 | Markdown | YAML/JSON |
| 验证方式 | CLI 验证 + AI 理解 | 语法验证 |
| 适用阶段 | 开发前期（需求定义） | 开发中期（接口定义） |
| 目标用户 | 产品经理 + 开发者 + AI | 开发者 + 前端 |
两者可以配合使用：先用 OpenSpec 定义需求和场景，再用 OpenAPI 定义接口细节。
引入 OpenSpec 不需要推翻重来，可以通过渐进式的增量方式（Brownfield-first）平滑融入现有代码库。
openspec init --tools none 初始化配置。AI 在执行过程中偏离规范通常是由于上下文未正确加载或约束条件不够明确，可以通过以下方式校准行为。
openspec update 刷新 Skills 和命令文件。openspec/config.yaml 的 rules: 字段添加具体的强制性约束条件。/opsx:apply 让 AI 从详细的任务清单（Tasks）开始逐步实现，而不是直接丢给 AI 宽泛的编写代码指令。OpenSpec 的变更目录设计天然支持并行工作流，但需要合理管理依赖关系。
可以同时进行多个变更。每个变更都是独立的文件夹，互不干扰。但为了降低合并冲突的风险，建议：
OpenSpec 强调“外部可观察行为”，但这不仅限于前端界面的变化，也包含系统间交互与持久化状态的改变。对于纯内部逻辑（例如某条件变化仅反映在数据库中），可通过以下方式处理以保持规范的一致性。
design.md 或 tasks.md 中。为了保证业务逻辑的准确性与规范的稳定性，团队应当采用人工主导设计、AI 辅助生成的协同模式。
复杂业务逻辑往往导致 Spec 难以阅读，此时需要通过架构拆分与表达方式优化来维持文档的清晰度与可维护性。
文档版本: 2.2 最后更新: 2026-05-07 基于 Issue #7 补充常见问题与解答，优化文档结构