openspec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenSpec 规范驱动开发助手

OpenSpec Spec-Driven Development Assistant

OpenSpec 是规范驱动的 AI 编程框架。核心理念：在编写代码前，与 AI 就需求达成一致。

OpenSpec is a spec-driven AI programming framework. Core concept: Align requirements with AI before writing code.

核心原则

Core Principles

流动而非僵化 - 随时处理任何工件，无阶段门控
迭代而非瀑布 - 边构建边完善理解
简单而非复杂 - 最小化设置和仪式
棕地优先 - Delta 方式修改现有系统

Flow over Rigidity - Handle any artifact at any time, no phase gates
Iteration over Waterfall - Refine understanding while building
Simplicity over Complexity - Minimize setup and ceremony
Brownfield First - Modify existing systems in a Delta approach

触发场景

Trigger Scenarios

明确触发

Explicit Triggers

用户提及 "openspec"、"opsx"
用户使用
```
/opsx:*
```
斜杠命令
用户提及 "规范驱动开发"、"spec-driven"
用户询问如何管理需求或规范文档

User mentions "openspec", "opsx"
User uses
```
/opsx:*
```
slash commands
User mentions "spec-driven development" or "spec-driven"
User asks how to manage requirements or specification documents

上下文触发

Contextual Triggers

用户开始新功能开发前（建议使用 OpenSpec）
用户抱怨 AI 理解偏差或频繁返工
用户询问如何让 AI 更准确理解需求
用户需要生成技术文档或设计文档

Before a user starts new feature development (recommend using OpenSpec)
User complains about AI misunderstanding or frequent rework
User asks how to make AI understand requirements more accurately
User needs to generate technical documents or design documents

项目阶段触发

Project Phase Triggers

项目初始化阶段（建议配置 OpenSpec）
准备重大重构时（建议先写规范）
团队协作场景（需要统一的需求描述）
复杂功能开发前（需要明确需求边界）

Project initialization phase (recommend configuring OpenSpec)
Preparing for major refactoring (recommend writing specs first)
Team collaboration scenarios (need unified requirement descriptions)
Before developing complex features (need to clarify requirement boundaries)

适用场景

Applicable Scenarios

推荐使用：

改进现有项目（棕地开发）
需要高质量实现的关键功能
团队协作开发
需要长期维护的项目

不推荐使用：

快速原型验证（0→1 探索）
一次性小脚本
需求极度不明确的创新探索

Recommended Use Cases:

Improve existing projects (brownfield development)
Critical features requiring high-quality implementation
Team collaborative development
Projects requiring long-term maintenance

Not Recommended Use Cases:

Rapid prototype verification (0→1 exploration)
One-off small scripts
Innovative exploration with extremely unclear requirements

目录结构

Directory Structure

plain

openspec/
├── config.yaml           # 项目配置（可选）
├── specs/                # 当前系统行为（事实来源）
│   ├── auth.md
│   └── api.md
├── changes/              # 活跃变更
│   └── add-feature/
│       ├── .openspec.yaml
│       ├── proposal.md
│       ├── specs/
│       ├── design.md
│       └── tasks.md
├── archive/              # 已归档变更
│   └── 2025-01-23-add-feature/
└── schemas/              # 自定义工作流（可选）
    └── my-workflow/
        ├── schema.yaml
        └── templates/

plain

openspec/
├── config.yaml           # Project configuration (optional)
├── specs/                # Current system behavior (source of truth)
│   ├── auth.md
│   └── api.md
├── changes/              # Active changes
│   └── add-feature/
│       ├── .openspec.yaml
│       ├── proposal.md
│       ├── specs/
│       ├── design.md
│       └── tasks.md
├── archive/              # Archived changes
│   └── 2025-01-23-add-feature/
└── schemas/              # Custom workflows (optional)
    └── my-workflow/
        ├── schema.yaml
        └── templates/

斜杠命令

Slash Commands

命令	功能
`/opsx:explore`	探索想法、调查问题、明确需求
`/opsx:new`	启动新变更
`/opsx:continue`	创建下一个就绪工件
`/opsx:ff`	快进 - 一次创建所有规划工件
`/opsx:apply`	实施任务，按需更新工件
`/opsx:verify`	验证实现的完整性、正确性、一致性
`/opsx:sync`	同步 delta specs 到主规范（可选）
`/opsx:archive`	归档完成的变更
`/opsx:bulk-archive`	批量归档多个变更
`/opsx:onboard`	交互式教程

Command	Function
`/opsx:explore`	Explore ideas, investigate problems, clarify requirements
`/opsx:new`	Initiate a new change
`/opsx:continue`	Create the next ready artifact
`/opsx:ff`	Fast forward - Create all planned artifacts at once
`/opsx:apply`	Implement tasks and update artifacts as needed
`/opsx:verify`	Verify completeness, correctness, and consistency of implementation
`/opsx:sync`	Sync delta specs to main specs (optional)
`/opsx:archive`	Archive completed changes
`/opsx:bulk-archive`	Bulk archive multiple changes
`/opsx:onboard`	Interactive tutorial

CLI 命令

CLI Commands

bash

openspec init                              # 初始化项目
openspec update                            # 更新指令文件
openspec list                              # 列出活跃变更
openspec show <name>                       # 查看变更详情
openspec validate <name> --strict          # 严格格式校验
openspec status --change <name>            # 查看工件状态
openspec archive <name> --yes              # 归档变更
openspec schemas                           # 列出可用 schemas
openspec schema init <name>                # 创建自定义 schema
openspec schema fork <source> <name>       # 复制现有 schema

bash

openspec init                              # Initialize project
openspec update                            # Update instruction files
openspec list                              # List active changes
openspec show <name>                       # View change details
openspec validate <name> --strict          # Strict format validation
openspec status --change <name>            # View artifact status
openspec archive <name> --yes              # Archive change
openspec schemas                           # List available schemas
openspec schema init <name>                # Create custom schema
openspec schema fork <source> <name>       # Copy existing schema

工作流模式

Workflow Modes

快速功能流

Quick Feature Flow

需求明确时使用：

plain

/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive

Use when requirements are clear:

plain

/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive

探索式流程

Exploratory Flow

需求不明确时使用：

plain

/opsx:explore → /opsx:new → /opsx:continue → ... → /opsx:apply

Use when requirements are unclear:

plain

/opsx:explore → /opsx:new → /opsx:continue → ... → /opsx:apply

增量式流程

Incremental Flow

需要更多控制时使用：

plain

/opsx:new → /opsx:continue (重复) → /opsx:apply → /opsx:archive

Use when more control is needed:

plain

/opsx:new → /opsx:continue (repeat) → /opsx:apply → /opsx:archive

工件系统

Artifact System

默认 Schema: spec-driven

Default Schema: spec-driven

依赖关系：

plain

proposal → specs → design → tasks → implement
          ↓
       design

工件状态转换：

plain

BLOCKED → READY → DONE
   ↓         ↓       ↓
缺少依赖   依赖完成   文件存在

Dependency Relationships:

plain

proposal → specs → design → tasks → implement
          ↓
       design

Artifact State Transitions:

plain

BLOCKED → READY → DONE
   ↓         ↓       ↓
Missing dependencies  Dependencies completed  File exists

工件类型

Artifact Types

proposal.md - 变更提案（Why/What/Impact）
specs/ - Delta 规范（ADDED/MODIFIED/REMOVED）
design.md - 技术设计
tasks.md - 任务清单（带复选框）

proposal.md - Change Proposal (Why/What/Impact)
specs/ - Delta Specs (ADDED/MODIFIED/REMOVED)
design.md - Technical Design
tasks.md - Task List (with checkboxes)

Delta Specs 格式

Delta Specs Format

Delta specs 只描述变更部分，使用三种标记：

markdown

undefined

Delta specs only describe changed parts, using three markers:

markdown

undefined

ADDED Requirements

Requirement: 新功能名称

Requirement: New Feature Name

系统 MUST 提供 [功能描述]。

The system MUST provide [feature description].

Scenario: 场景名称

Scenario: Scenario Name

WHEN 前置条件
THEN 预期结果
AND 额外条件

WHEN Precondition
THEN Expected result
AND Additional conditions

MODIFIED Requirements

Requirement: 修改的功能

Requirement: Modified Feature

变化说明: 具体变化
原因: 修改原因
影响范围: 受影响区域

Change Description: Specific changes
Reason: Reason for modification
Impact Scope: Affected areas

REMOVED Requirements

Requirement: 废弃的功能

Requirement: Deprecated Feature

Reason: 废弃原因
Migration: 迁移路径

undefined

Reason: Deprecation reason
Migration: Migration path

undefined

格式要求

Format Requirements

Delta 分区使用英文标题（ADDED/MODIFIED/REMOVED）
需求必须包含 MUST/SHALL/SHOULD 关键词
场景使用英文 Gherkin 关键字（GIVEN/WHEN/THEN/AND）
每个 Requirement 至少一个 Scenario
REMOVED 必须提供 Reason 和 Migration

Delta sections use English headings (ADDED/MODIFIED/REMOVED)
Requirements must include MUST/SHALL/SHOULD keywords
Scenarios use English Gherkin keywords (GIVEN/WHEN/THEN/AND)
Each Requirement has at least one Scenario
REMOVED sections must provide Reason and Migration

项目配置

Project Configuration

config.yaml

yaml

schema: spec-driven # 默认 schema

context: | # 注入所有工件的上下文
  Tech stack: TypeScript, React, Node.js
  Testing: Vitest
  Style: ESLint + Prettier

rules: # 按工件的特定规则
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format
  design:
    - Include sequence diagrams

yaml

schema: spec-driven # Default schema

context: | # Context injected into all artifacts
  Tech stack: TypeScript, React, Node.js
  Testing: Vitest
  Style: ESLint + Prettier

rules: # Specific rules per artifact
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format
  design:
    - Include sequence diagrams

Schema 优先级

Schema Priority

CLI 标志：
```
--schema <name>
```
变更元数据：
```
.openspec.yaml
```
项目配置：
```
openspec/config.yaml
```
默认值：
```
spec-driven
```

CLI flag:
```
--schema <name>
```
Change metadata:
```
.openspec.yaml
```
Project configuration:
```
openspec/config.yaml
```
Default value:
```
spec-driven
```

自定义 Schema

Custom Schema

创建新 Schema

Create New Schema

bash

openspec schema init my-workflow

bash

openspec schema init my-workflow

或基于现有 schema

Or based on existing schema

openspec schema fork spec-driven my-workflow

undefined

openspec schema fork spec-driven my-workflow

undefined

Schema 结构

Schema Structure

yaml

undefined

yaml

undefined

openspec/schemas/my-workflow/schema.yaml

name: my-workflow version: 1 description: 自定义工作流

artifacts:

id: proposal generates: proposal.md template: proposal.md requires: []
id: tasks generates: tasks.md template: tasks.md requires: [proposal]

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

undefined

name: my-workflow version: 1 description: Custom workflow

artifacts:

id: proposal generates: proposal.md template: proposal.md requires: []
id: tasks generates: tasks.md template: tasks.md requires: [proposal]

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

undefined

模板示例

Template Example

markdown

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

markdown

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

Why

What Changes

Impact

undefined

undefined

验证命令

Verification Command

/opsx:verify

检查三个维度：

Completeness - 所有任务完成，需求已实现
Correctness - 匹配规范意图，处理边界情况
Coherence - 设计决策反映在代码中

/opsx:verify

checks three dimensions:

Completeness - All tasks completed, requirements implemented
Correctness - Matches specification intent, handles edge cases
Coherence - Design decisions reflected in code

更新与迭代

Updates and Iterations

何时更新现有变更

When to Update Existing Changes

相同意图，优化执行
范围缩小（MVP 优先）
学习驱动的修正

Same intent, optimized execution
Scope reduction (MVP first)
Learning-driven corrections

何时启动新变更

When to Initiate New Changes

意图根本改变
范围爆炸性增长
原始变更可独立完成

Fundamental change in intent
Explosive scope growth
Original change can be completed independently

判断启发式

Judgment Heuristics

plain

相同意图？ → YES: UPDATE / NO: NEW
>50% 重叠？→ YES: UPDATE / NO: NEW
原始能完成？→ NO: UPDATE / YES: NEW

plain

Same intent? → YES: UPDATE / NO: NEW
>50% overlap?→ YES: UPDATE / NO: NEW
Original can be completed?→ NO: UPDATE / YES: NEW

执行长任务的注意事项

Notes for Executing Long Tasks

及时更新任务文件 - 完成任务后立即更新
```
tasks.md
```
并行子代理 - 启动多个子代理分模块完成任务
中文回复 - 始终用中文回复用户
重读任务要求 - 上下文合并后重新阅读规范
连续执行 - 一次性完成
```
tasks.md
```
全部任务
禁止批处理脚本 - 使用具体的文件编辑，不用脚本批量修改
主从代理调度：
- 主代理：阅读全部任务，分配子代理，监听反馈
- 子代理：严格按主代理要求完成任务

Update task files promptly - Update
```
tasks.md
```
immediately after completing a task
Parallel sub-agents - Launch multiple sub-agents to complete tasks by module
Reply in Chinese - Always respond to users in Chinese
Re-read task requirements - Re-read specifications after context merging
Continuous execution - Complete all tasks in
```
tasks.md
```
at once
No batch scripts - Use specific file edits instead of batch script modifications
Master-slave agent scheduling:
- Master agent: Read all tasks, assign to sub-agents, monitor feedback
- Sub agents: Strictly complete tasks as required by the master agent

故障排除

Troubleshooting

命令不可用

Command Unavailable

bash

undefined

bash

undefined

检查安装

Check installation

openspec --version

重新安装

Reinstall

npm install -g @fission-ai/openspec@latest

刷新指令

Refresh instructions

openspec update

undefined

openspec update

undefined

工件状态问题

Artifact State Issues

bash

undefined

bash

undefined

查看状态

View status

openspec status --change <name> --json

验证格式

Validate format

openspec validate <name> --strict

undefined

openspec validate <name> --strict

undefined

归档失败

Archive Failure

先运行
```
openspec validate <name> --strict
```
检查
```
specs/
```
目录是否有内容
解决 Git 冲突后重试

First run
```
openspec validate <name> --strict
```
Check if the
```
specs/
```
directory has content
Resolve Git conflicts and retry

环境变量

Environment Variables

```
OPENSPEC_CONCURRENCY
```
- 并行验证数（默认: 6）
```
OPENSPEC_TELEMETRY=0
```
- 禁用遥测
```
NO_COLOR
```
- 禁用颜色输出

```
OPENSPEC_CONCURRENCY
```
- Number of parallel verifications (default: 6)
```
OPENSPEC_TELEMETRY=0
```
- Disable telemetry
```
NO_COLOR
```
- Disable color output

参考资源

Reference Resources

OpenSpec 仓库: https://github.com/Fission-AI/OpenSpec
OPSX 工作流: https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md
CLI 参考: https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md
自定义配置: https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md

OpenSpec Repository: https://github.com/Fission-AI/OpenSpec
OPSX Workflow: https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md
CLI Reference: https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md
Custom Configuration: https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md