数智启思 - OpenSpec 中文使用指南

简介

什么是 OpenSpec？

OpenSpec 是一个轻量级的规范框架，帮助你和 AI 编码助手在写代码之前就”要做什么”达成一致。它的核心理念是：

→ 灵活而非僵化     — 无需阶段门限，按需工作
→ 迭代而非瀑布     — 边做边学，持续改进
→ 简单而非复杂     — 轻量设置，最小仪式感
→ 存量优先         — 支持现有代码库，不只是全新项目

为什么需要 OpenSpec？

AI 编码助手很强大，但当需求只存在于聊天历史中时，结果往往不可预测。OpenSpec 添加了一个轻量级的规范层，让你在写代码之前先达成共识。

核心优势：

构建前先达成共识 — 人类和 AI 在写代码前先对齐规范
保持有序 — 每个变更都有自己的文件夹，包含提案、设计、任务
灵活工作 — 随时更新任何产出物，无僵化阶段门限
兼容你的工具 — 通过斜杠命令支持 20+ AI 助手

工作流程概览

     ┌────────────────┐
     │  1. 开始变更   │  /opsx:propose (核心模式) 或 /opsx:new (扩展模式)
     └───────┬────────┘
             │
             ▼
     ┌────────────────┐
     │  2. 创建产出物 │  /opsx:ff 或 /opsx:continue
     │                │  创建 proposal → specs → design → tasks
     └───────┬────────┘
             │
             ▼
     ┌────────────────┐
     │  3. 实现任务   │  /opsx:apply
     │                │  完成清单任务，打勾标记
     └───────┬────────┘
             │
             ▼
     ┌────────────────┐
     │  4. 验证工作    │  /opsx:verify
     │                │  检查实现是否符合规范
     └───────┬────────┘
             │
             ▼
     ┌────────────────┐     ┌──────────────────────────────────────┐
     │  5. 归档变更   │────►│  增量规范合并到主规范                │
     │                │     │  变更文件夹移至 archive/              │
     └────────────────┘     │  规范成为新的事实来源                │
                            └──────────────────────────────────────┘

安装

环境要求

Node.js 20.19.0 或更高版本 — 查看版本：node --version

安装方式

npm

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 add -g @fission-ai/openspec@latest

Nix

直接运行：

nix run github:Fission-AI/OpenSpec -- init

安装到配置：

nix profile install github:Fission-AI/OpenSpec

或在 flake.nix 中添加：

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    openspec.url = "github:Fission-AI/OpenSpec";
  };

  outputs = { nixpkgs, openspec, ... }: {
    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
      buildInputs = [ openspec.packages.x86_64-linux.default ];
    };
  };
}

验证安装

openspec --version

快速开始

第一步：初始化

在项目目录中运行：

cd your-project
openspec init

这会创建一个交互式引导，帮你配置项目。

第二步：开始使用

告诉你的 AI：/opsx:propose <你想要构建的功能>

示例：

你: /opsx:propose add-dark-mode

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

第三步：实现

你: /opsx:apply

AI:  Implementing tasks...
     ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 1.3 Add CSS variables
     ✓ 1.4 Wire up localStorage
     All tasks complete!

第四步：归档

你: /opsx:archive

AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

OpenSpec 创建的文件结构

openspec/
├── specs/              # 事实来源（你的系统行为）
│   └── <domain>/
│       └── spec.md
├── changes/            # 提议的修改（每个变更一个文件夹）
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # 增量规范（改变了什么）
│           └── <domain>/
│               └── spec.md
└── config.yaml         # 项目配置（可选）

核心概念

规范（Specs）

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

结构

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

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

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

规范格式

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

# Auth Specification

## Purpose
Authentication and session management for the application.

## Requirements

### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.

#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard

#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued

### Requirement: Session Expiration
The system MUST expire sessions after 30 minutes of inactivity.

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
- AND the user must re-authenticate

关键元素：

元素	用途
`## Purpose`	该规范领域的高级描述
`### Requirement:`	系统必须具备的特定行为
`#### Scenario:`	需求的具体示例
SHALL/MUST/SHOULD	RFC 2119 关键词，表示需求强度

变更（Changes）

变更是对系统提议的修改，封装在一个文件夹中，包含理解和实现它所需的一切。

变更结构

openspec/changes/add-dark-mode/
├── proposal.md           # 为什么以及是什么
├── design.md             # 如何做（技术方案）
├── tasks.md              # 实现清单
├── .openspec.yaml        # 变更元数据（可选）
└── specs/                # 增量规范
    └── ui/
        └── spec.md       # ui/spec.md 改变了什么

每个变更都是自包含的，包含：

产出物（Artifacts） — 捕获意图、设计和任务的文档
增量规范（Delta specs） — 添加、修改或删除的内容
元数据（Metadata） — 此变更的可选配置

产出物（Artifacts）

产出物是变更中的文档，指导工作。

产出物流

proposal ──────► specs ──────► design ──────► tasks ──────► implement
    │               │             │              │
   why            what           how          steps
 + scope        changes       approach      to take

产出物相互构建，每个产出物为下一个提供上下文。

产出物类型

Proposal（proposal.md）

提案捕获意图、范围和方法。

# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage and match system preferences.

## Scope
In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage

Out of scope:
- Custom color themes (future work)
- Per-page theme overrides

## Approach
Use CSS custom properties for theming with a React context
for state management. Detect system preference on first load,
allow manual override.

Specs（增量规范）

增量规范描述相对于当前规范的变化。详见下文。

Design（design.md）

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

# Design: Add Dark Mode

## Technical Approach
Theme state managed via React Context to avoid prop drilling.
CSS custom properties enable runtime switching without class toggling.

## Architecture Decisions

### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency

### Decision: CSS Custom Properties
Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution

## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)

Tasks（tasks.md）

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

# 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
- [ ] 1.4 Add system preference detection

## 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.3 Test contrast ratios for accessibility

增量规范（Delta Specs）

增量规范是让 OpenSpec 适配存量开发的关键概念。它们描述相对于当前规范的变化。

格式

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.

#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation

#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP

## MODIFIED Requirements

### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA. Users should re-authenticate each session.)

增量部分

部分	含义	归档时发生什么
`## ADDED Requirements`	新行为	追加到主规范
`## MODIFIED Requirements`	更改的行为	替换现有需求
`## REMOVED Requirements`	弃用的行为	从主规范中删除

为什么用增量而非完整规范

清晰 — 增量准确显示变化内容
避免冲突 — 两个变更可以修改同一规范文件的不同需求
审查效率 — 审查者只看变化
适配存量 — 大多数工作是修改现有行为

模式（Schemas）

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

内置模式

spec-driven（默认）

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

proposal → specs → design → tasks → implement

适用于：大多数需要先同意规范再实现的功能工作。

自定义模式

创建自定义模式：

# 从头创建
openspec schema init research-first

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

命令参考

斜杠命令

在 AI 编码助手的聊天界面中调用（如 Claude Code、Cursor、Windsurf）。

核心模式命令（默认）

命令	用途
`/opsx:propose`	创建变更并一步生成所有规划产出物
`/opsx:explore`	思考想法，调查问题，澄清需求
`/opsx:apply`	实现任务
`/opsx:archive`	归档完成的变更

扩展模式命令

命令	用途
`/opsx:new`	开始新的变更脚手架
`/opsx:continue`	基于依赖创建下一个产出物
`/opsx:ff`	快进：一步创建所有规划产出物
`/opsx:verify`	验证实现是否符合产出物
`/opsx:sync`	将增量规范合并到主规范
`/opsx:bulk-archive`	批量归档多个变更
`/opsx:onboard`	引导式入门教程

启用扩展命令：

openspec config profile
openspec update

命令详解

/opsx:propose

一步创建变更并生成所有规划产出物。

/opsx:propose [变更名称或描述]

/opsx:explore

思考想法、调查问题、澄清需求，无需承诺为变更。

/opsx:explore [主题]

/opsx:new

开始新的变更脚手架。

/opsx:new [变更名称] [--schema <模式名称>]

/opsx:continue

在依赖链中创建下一个产出物。增量创建。

/opsx:continue [变更名称]

/opsx:ff

快进创建所有规划产出物。

/opsx:ff [变更名称]

/opsx:apply

实现任务。执行任务清单，写代码并标记完成。

/opsx:apply [变更名称]

/opsx:verify

验证实现是否匹配变更产出物。检查三个维度：

完整性 — 所有任务完成，所有需求实现
正确性 — 实现符合规范意图，处理边界情况
一致性 — 设计决策反映在代码中，模式一致

/opsx:verify [变更名称]

/opsx:sync

将变更的增量规范合并到主规范。

/opsx:sync [变更名称]

/opsx:archive

归档完成的变更。

/opsx:archive [变更名称]

/opsx:bulk-archive

批量归档多个已完成的变更。

/opsx:bulk-archive [变更名称...]

/opsx:onboard

引导式入门教程，交互式使用你的实际代码库。

/opsx:onboard

CLI 命令

通过终端使用。

设置命令

openspec init

在项目中初始化 OpenSpec。

openspec init [path] [options]

选项：

选项	描述
`--tools <list>`	非交互式配置 AI 工具。使用 `all`、`none` 或逗号分隔列表
`--force`	自动清理遗留文件，不提示
`--profile <profile>`	覆盖此运行使用的全局模式（`core` 或 `custom`）

示例：

# 交互式初始化
openspec init

# 在特定目录初始化
openspec init ./my-project

# 非交互式：为 Claude 和 Cursor 配置
openspec init --tools claude,cursor

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

# 覆盖此运行的模式
openspec init --profile core

openspec update

升级 CLI 后更新 OpenSpec 指令文件。

openspec update [path] [options]

选项：

选项	描述
`--force`	即使文件是最新的也强制更新

浏览命令

openspec list

列出项目中的变更或规范。

openspec list [options]

选项：

选项	描述
`--specs`	列出规范而非变更
`--changes`	列出变更（默认）
`--sort <order>`	按 `recent`（默认）或 `name` 排序
`--json`	JSON 格式输出

openspec view

显示交互式仪表板以浏览规范和变更。

openspec view

openspec show

显示变更或规范的详情。

openspec show [item-name] [options]

选项：

选项	描述
`--type <type>`	指定类型：`change` 或 `spec`
`--json`	JSON 格式输出
`--no-interactive`	禁用交互式提示

验证命令

openspec validate

验证变更和规范的结构问题。

openspec validate [item-name] [options]

选项：

选项	描述
`--all`	验证所有变更和规范
`--changes`	验证所有变更
`--specs`	验证所有规范
`--type <type>`	当名称模糊时指定类型
`--strict`	启用严格验证模式
`--json`	JSON 格式输出
`--concurrency <n>`	最大并行验证数（默认：6）

生命周期命令

openspec archive

归档已完成的变更并将增量规范合并到主规范。

openspec archive [change-name] [options]

选项：

选项	描述
`-y, --yes`	跳过确认提示
`--skip-specs`	跳过规范更新（适用于基础设施/工具/仅文档变更）
`--no-validate`	跳过验证（需要确认）

工作流命令

openspec status

显示变更的产出物完成状态。

openspec status [options]

选项：

选项	描述
`--change <id>`	变更名称
`--schema <name>`	模式覆盖
`--json`	JSON 格式输出

openspec instructions

获取创建产出物或应用任务的丰富指令。

openspec instructions [artifact] [options]

参数：

参数	描述
`artifact`	产出物 ID：`proposal`、`specs`、`design`、`tasks` 或 `apply`

openspec templates

显示模式中所有产出物的解析模板路径。

openspec templates [options]

openspec schemas

列出可用的工作流模式。

openspec schemas [options]

模式命令

openspec schema init

创建新的项目本地模式。

openspec schema init <name> [options]

openspec schema fork

复制现有模式到项目进行自定义。

openspec schema fork <source> [name] [options]

openspec schema validate

验证模式结构和模板。

openspec schema validate [name] [options]

openspec schema which

显示模式从哪里解析（用于调试优先级）。

openspec schema which [name] [options]

配置命令

openspec config

查看和修改全局 OpenSpec 配置。

openspec config <subcommand> [options]

子命令：

子命令	描述
`path`	显示配置文件位置
`list`	显示所有当前设置
`get <key>`	获取特定值
`set <key> <value>`	设置值
`unset <key>`	移除键
`reset`	重置为默认值
`edit`	在编辑器中打开
`profile [preset]`	交互式或通过预设配置工作流模式

工作流

两种模式

默认快速路径（core 模式）

新安装默认使用 core，提供：

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

典型流程：

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

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

如果需要显式脚手架和构建命令，启用：

openspec config profile
openspec update

工作流模式

快速功能

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

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

适用于： 小到中型功能、错误修复、直接的变更。

探索性

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

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

适用于： 性能优化、调试、架构决策、需求不明确。

并行变更

同时处理多个变更：

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

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

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

完成变更

推荐完成流程：

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

何时使用什么

`/opsx:ff` vs `/opsx:continue`

场景	使用
需求清晰，准备构建	`/opsx:ff`
探索中，想审查每一步	`/opsx:continue`
想在规范前迭代提案	`/opsx:continue`
时间压力，需要快速行动	`/opsx:ff`
复杂变更，想要控制	`/opsx:continue`

经验法则： 如果你能提前描述完整范围，使用 /opsx:ff。如果你边做边摸索，使用 /opsx:continue。

何时更新 vs 重新开始

更新现有变更：

相同意图，细化执行
范围收窄（先做 MVP，其余后续）
学习驱动的修正
基于实现发现的方案调整

开始新变更：

意图从根本上改变
范围爆炸成完全不同的工作
原始变更可以独立标记为”完成”
补丁会混淆而非澄清

自定义配置

项目配置

openspec/config.yaml 文件是自定义 OpenSpec 的最简单方式。

快速设置

openspec init

或手动创建：

# 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

工作原理

默认模式： 无需在每个命令上使用 --schema
上下文注入： AI 看到你的技术栈、约定等
每产出物规则： 特定产出物的自定义规则

模式解析顺序

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

自定义模式

当项目配置不够用时，创建完全自定义工作流的模式。

复制现有模式

最快的方式是复制内置模式：

openspec schema fork spec-driven my-workflow

从头创建模式

# 交互式
openspec schema init research-first

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

模式结构

# 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: |
      Create a proposal that explains WHY this change is needed.
      Focus on the problem, not the solution.
    requires: []

  - id: design
    generates: design.md
    description: Technical design
    template: design.md
    instruction: |
      Create a design document explaining HOW to implement.
    requires:
      - proposal

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

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

模板

模板是 AI 指导的 markdown 文件。

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

<!-- Explain the motivation for this change. What problem does this solve? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities or modifications. -->

## Impact

<!-- Affected code, APIs, dependencies, systems -->

验证模式

openspec schema validate my-workflow

多语言支持

快速设置

在 openspec/config.yaml 中添加语言指令：

schema: spec-driven

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

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

所有生成的产出物现在将使用指定语言。

语言示例

葡萄牙语（巴西）

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

西班牙语

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

简体中文

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

日语

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

法语

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

德语

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

技术术语处理

决定如何处理技术术语：

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

支持的工具

OpenSpec 支持许多 AI 编码助手。

支持的工具列表

工具	Skills 路径模式	命令路径模式
Claude Code (claude)	`.claude/skills/openspec-*/SKILL.md`	`.claude/commands/opsx/<id>.md`
Cursor (cursor)	`.cursor/skills/openspec-*/SKILL.md`	`.cursor/commands/opsx-<id>.md`
Windsurf (windsurf)	`.windsurf/skills/openspec-*/SKILL.md`	`.windsurf/workflows/opsx-<id>.md`
Cline (cline)	`.cline/skills/openspec-*/SKILL.md`	`.clinerules/workflows/opsx-<id>.md`
Continue (continue)	`.continue/skills/openspec-*/SKILL.md`	`.continue/prompts/opsx-<id>.prompt`
GitHub Copilot (github-copilot)	`.github/skills/openspec-*/SKILL.md`	`.github/prompts/opsx-<id>.prompt.md`
Amazon Q Developer (amazon-q)	`.amazonq/skills/openspec-*/SKILL.md`	`.amazonq/prompts/opsx-<id>.md`
Gemini CLI (gemini)	`.gemini/skills/openspec-*/SKILL.md`	`.gemini/commands/opsx-<id>.toml`
Trae (trae)	`.trae/skills/openspec-*/SKILL.md`	不生成（使用基于 skill 的调用）
OpenCode (opencode)	`.opencode/skills/openspec-*/SKILL.md`	`.opencode/command/opsx-<id>.md`
以及更多…

工具语法差异

不同 AI 工具使用略有不同的命令语法：

工具	语法示例
Claude Code	`/opsx:propose`, `/opsx:apply`
Cursor	`/opsx-propose`, `/opsx-apply`
Windsurf	`/opsx-propose`, `/opsx-apply`
Copilot (IDE)	`/opsx-propose`, `/opsx-apply`
Trae	基于 skill 的调用如 `/openspec-propose`

非交互式设置

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

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

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

迁移指南

发生了什么变化？

OPSX 用灵活的、基于行动的方法取代了旧的阶段锁定工作流。

方面	旧版	OPSX
命令	`/openspec:proposal`, `/openspec:apply`, `/openspec:archive`	默认：`/opsx:propose`, `/opsx:apply`, `/opsx:archive`
工作流	一次性创建所有产出物	增量或一次性创建——任选
返回	尴尬的阶段门限	自然——随时更新任何产出物
自定义	固定结构	模式驱动，完全可定制
配置	`CLAUDE.md` 标记 + `project.md`	干净的 `openspec/config.yaml`

运行迁移

# 新安装或添加新工具
openspec init

# 只想迁移和刷新现有工具
openspec update

迁移 project.md 到 config.yaml

旧版（project.md）：

# Project Context

This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.

## Conventions

- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications

新版（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
    - Reference existing patterns before inventing new ones
  design:
    - Include sequence diagrams for complex flows

关键差异

project.md	config.yaml
自由格式 markdown	结构化 YAML
一段文本	分离上下文和每产出物规则
何时使用不明确	上下文出现在所有产出物；规则只出现在匹配的产出物中
无模式选择	显式 `schema:` 字段设置默认工作流

继续现有变更

你的进行中的变更与 OPSX 命令无缝协作。

从遗留工作流有活动变更？

/opsx:apply add-my-feature

OPSX 读取现有产出物并从中断处继续。

最佳实践

保持变更聚焦

每个变更一个逻辑工作单元。如果你在做”添加功能 X 并重构 Y”，考虑分成两个单独的变更。

不清晰需求时使用 `/opsx:explore`

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

你: /opsx:explore

AI:  What would you like to explore?

你: How should we handle rate limiting for our API?

AI:  Let me investigate your current setup and options...
     [Researches codebase, considers patterns]

     I see three approaches we could take:
     1. Middleware-based (simple, per-endpoint)
     2. Redis-backed (scalable, shared state)
     3. Token bucket per user (fair, complex)

     Your current stack suggests #1 or #2. What's your scale?

归档前验证

使用 /opsx:verify 检查实现是否匹配产出物：

你: /opsx:verify

AI:  Verifying add-dark-mode...

     ✓ All tasks in tasks.md are checked
     ✓ Requirements in specs have corresponding code
     ✓ Design decisions are reflected in implementation

     Ready to archive!

清晰命名变更

好名字让 openspec list 有用：

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

获取帮助

Discord: discord.gg/YctCnvvshC
GitHub Issues: github.com/Fission-AI/OpenSpec/issues
文档: 查看各 docs/ 目录下的详细文档

简介

什么是 OpenSpec？

为什么需要 OpenSpec？

工作流程概览

安装

环境要求

安装方式

npm

pnpm

yarn

bun

Nix

验证安装

快速开始

第一步：初始化

第二步：开始使用

第三步：实现

第四步：归档

OpenSpec 创建的文件结构

核心概念

规范（Specs）

结构

规范格式

变更（Changes）

变更结构

产出物（Artifacts）

产出物流

产出物类型

增量规范（Delta Specs）

格式

增量部分

为什么用增量而非完整规范

模式（Schemas）

内置模式

自定义模式

命令参考

斜杠命令

核心模式命令（默认）

扩展模式命令

命令详解

CLI 命令

设置命令

浏览命令

验证命令

生命周期命令

工作流命令

模式命令

配置命令

工作流

两种模式

默认快速路径（core 模式）

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

工作流模式

快速功能

探索性

并行变更

完成变更

何时使用什么

/opsx:ff vs /opsx:continue

何时更新 vs 重新开始

自定义配置

项目配置

快速设置

工作原理

模式解析顺序

自定义模式

复制现有模式

从头创建模式

模式结构

模板

验证模式

多语言支持

快速设置

语言示例

技术术语处理

支持的工具

支持的工具列表

工具语法差异

非交互式设置

迁移指南

`/opsx:ff` vs `/opsx:continue`

不清晰需求时使用 `/opsx:explore`