OpenSpec — 规范驱动开发

OpenSpec 将 AI 辅助的开发过程组织成可追踪的变更，其中包含指导实施的工件（提案、规范、设计、任务）。

设置

# Install globally
npm install -g @fission-ai/openspec@latest

# Initialize in a project
cd /path/to/project
openspec init --tools claude

# Update after CLI upgrade
openspec update

核心工作流

每个变更遵循以下流程：新建 → 规划 → 应用 → 验证 → 归档

1. 启动变更

# Create change folder with default schema
openspec new change <name>

# With specific schema
openspec new change <name> --schema tdd-driven

2. 规划（创建工件）

使用命令行界面指令命令，以获取针对每个工件的增强提示：

# Get instructions for next artifact
openspec instructions --change <name> --json

# Check progress
openspec status --change <name> --json

工件序列（规范驱动模式）：

1. proposal.md— 原因与内容（意图、范围、方法）
2. specs/— 需求 + 场景（Given/When/Then）
3. design.md— 技术方案与架构决策
4. tasks.md— 带复选框的实施清单

3. 实施

阅读tasks.md并逐项处理，标记[x]为已完成。

4. 验证

openspec validate --change <name> --json

检查完整性、正确性和一致性。

5. 归档

openspec archive <name> --yes

将增量规范合并到主目录openspec/specs/并将变更移至归档。

代理工作流程（如何作为AI代理使用）

当用户要求使用OpenSpec构建/迁移/重构某物时：

1. 检查项目状态：

   openspec list --json           # Active changes
   openspec list --specs --json   # Current specs
   openspec schemas --json        # Available schemas
   

2. 创建变更：

   openspec new change <name> [--schema <schema>]
   

3. 对于每个工件，获取说明并创建文件：

   openspec instructions <artifact> --change <name> --json
   openspec status --change <name> --json
   

   然后将工件文件写入openspec/changes/<名称>/。

4. 实现来自tasks.md的任务.

5. 验证并归档：

   openspec validate <name> --json
   openspec archive <name> --yes
   

命令行界面快速参考

始终使用--json用于编程/代理用途。

自定义模式

模式定义了工件序列。为不同的工作流程创建自定义模式：

# Fork built-in schema
openspec schema fork spec-driven my-workflow

# Create from scratch
openspec schema init my-workflow

# Validate
openspec schema validate my-workflow

模式文件位于openspec/schemas/<名称>/schema.yaml模板位于templates/目录中。

关于模式结构的详细信息，请参阅references/schemas.md文件。

项目结构

project/
├── openspec/
│   ├── config.yaml          # Project config (default schema, context, rules)
│   ├── specs/               # Source of truth — current system behavior
│   ├── changes/             # Active changes (one folder each)
│   │   └── <change-name>/
│   │       ├── .openspec.yaml
│   │       ├── proposal.md
│   │       ├── specs/       # Delta specs (what's changing)
│   │       ├── design.md
│   │       └── tasks.md
│   └── schemas/             # Custom schemas
└── .claude/skills/          # Auto-generated Claude integration

规范格式

规范使用RFC 2119关键词（SHALL/MUST/SHOULD/MAY）配合Given/When/Then场景：

### 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

增量规范

变更不会重写规范——它们描述增量（ADDED/MODIFIED/REMOVED），这些增量在归档时会合并到主规范中。

配置

openspec/config.yaml设置默认值：

schema: spec-driven      # or tdd-driven, rapid, custom
context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Jest
rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format