OpenSpec — Spec-Driven Development
OpenSpec structures AI-assisted development into trackable changes with artifacts (proposal, specs, design, tasks) that guide implementation.
Setup
CODEBLOCK0
Core Workflow
Each change follows: new → plan → apply → verify → archive
1. Start a Change
CODEBLOCK1
2. Plan (Create Artifacts)
Use the CLI instructions command to get enriched prompts for each artifact:
CODEBLOCK2
Artifact sequence (spec-driven schema):
- 1.
proposal.md — Why and what (intent, scope, approach) - INLINECODE2 — Requirements + scenarios (Given/When/Then)
- INLINECODE3 — Technical approach and architecture decisions
- INLINECODE4 — Implementation checklist with checkboxes
3. Implement
Read tasks.md and work through items, marking [x] as complete.
4. Verify
CODEBLOCK3
Checks completeness, correctness, and coherence.
5. Archive
CODEBLOCK4
Merges delta specs into main openspec/specs/ and moves change to archive.
Agent Workflow (How to Use as an AI Agent)
When the user asks to build/migrate/refactor something with OpenSpec:
- 1. Check project state:
CODEBLOCK5
- 2. Create the change:
CODEBLOCK6
- 3. For each artifact, get instructions and create the file:
openspec instructions <artifact> --change <name> --json
openspec status --change <name> --json
Then write the artifact file to
openspec/changes/<name>/.
- 4. Implement tasks from
tasks.md.
- 5. Validate and archive:
CODEBLOCK8
CLI Quick Reference
| Command | Purpose |
|---|
| INLINECODE10 | List changes or specs |
| INLINECODE11 |
Show change/spec details |
|
openspec status --change <name> [--json] | Artifact completion status |
|
openspec instructions [artifact] --change <name> [--json] | Get enriched creation instructions |
|
openspec validate [name] [--all] [--json] | Validate changes/specs |
|
openspec archive <name> [--yes] | Archive completed change |
|
openspec schemas [--json] | List available schemas |
|
openspec templates [--json] | Show template paths |
|
openspec config | View/modify settings |
Always use --json for programmatic/agent use.
Custom Schemas
Schemas define artifact sequences. Create custom ones for different workflows:
CODEBLOCK9
Schema files live in openspec/schemas/<name>/schema.yaml with templates in templates/.
For schema structure details, see references/schemas.md.
Project Structure
CODEBLOCK10
Spec Format
Specs use RFC 2119 keywords (SHALL/MUST/SHOULD/MAY) with Given/When/Then scenarios:
CODEBLOCK11
Delta Specs
Changes don't rewrite specs — they describe deltas (ADDED/MODIFIED/REMOVED) that merge into main specs on archive.
Config
INLINECODE22 sets defaults:
CODEBLOCK12
OpenSpec — 规范驱动开发
OpenSpec 将 AI 辅助开发组织为可追踪的变更，并附带指导实施的工作产物（提案、规范、设计、任务）。
安装
bash
全局安装
npm install -g @fission-ai/openspec@latest
在项目中初始化
cd /path/to/project
openspec init --tools claude
CLI 升级后更新
openspec update
核心工作流
每个变更遵循：新建 → 规划 → 实施 → 验证 → 归档
1. 启动变更
bash
使用默认模式创建变更文件夹
openspec new change <名称>
使用特定模式
openspec new change <名称> --schema tdd-driven
2. 规划（创建工作产物）
使用 CLI 的 instructions 命令获取每个工作产物的增强提示：
bash
获取下一个工作产物的指令
openspec instructions --change <名称> --json
检查进度
openspec status --change <名称> --json
工作产物顺序（规范驱动模式）：
- 1. proposal.md — 为什么做以及做什么（意图、范围、方法）
- specs/ — 需求 + 场景（给定/当/那么）
- design.md — 技术方案和架构决策
- tasks.md — 带复选框的实施清单
3. 实施
阅读 tasks.md 并逐项完成，将 [x] 标记为已完成。
4. 验证
bash
openspec validate --change <名称> --json
检查完整性、正确性和一致性。
5. 归档
bash
openspec archive <名称> --yes
将增量规范合并到主 openspec/specs/ 中，并将变更移至归档。
智能体工作流（如何作为 AI 智能体使用）
当用户要求使用 OpenSpec 构建/迁移/重构某些内容时：
- 1. 检查项目状态：
bash
openspec list --json # 活跃的变更
openspec list --specs --json # 当前规范
openspec schemas --json # 可用的模式
- 2. 创建变更：
bash
openspec new change <名称> [--schema <模式>]
- 3. 对于每个工作产物，获取指令并创建文件：
bash
openspec instructions <工作产物> --change <名称> --json
openspec status --change <名称> --json
然后将工作产物文件写入 openspec/changes/<名称>/。
- 4. 实施 tasks.md 中的任务。
- 5. 验证并归档：
bash
openspec validate <名称> --json
openspec archive <名称> --yes
CLI 快速参考
| 命令 | 用途 |
|---|
| openspec list [--specs] [--json] | 列出变更或规范 |
| openspec show <名称> [--json] |
显示变更/规范详情 |
| openspec status --change <名称> [--json] | 工作产物完成状态 |
| openspec instructions [工作产物] --change <名称> [--json] | 获取增强的创建指令 |
| openspec validate [名称] [--all] [--json] | 验证变更/规范 |
| openspec archive <名称> [--yes] | 归档已完成的变更 |
| openspec schemas [--json] | 列出可用的模式 |
| openspec templates [--json] | 显示模板路径 |
| openspec config | 查看/修改设置 |
对于程序化/智能体使用，始终使用 --json。
自定义模式
模式定义了工作产物序列。为不同工作流创建自定义模式：
bash
派生内置模式
openspec schema fork spec-driven my-workflow
从头创建
openspec schema init my-workflow
验证
openspec schema validate my-workflow
模式文件位于 openspec/schemas/<名称>/schema.yaml，模板位于 templates/。
有关模式结构的详细信息，请参见 references/schemas.md。
项目结构
project/
├── openspec/
│ ├── config.yaml # 项目配置（默认模式、上下文、规则）
│ ├── specs/ # 事实来源 — 当前系统行为
│ ├── changes/ # 活跃的变更（每个变更一个文件夹）
│ │ └── <变更名称>/
│ │ ├── .openspec.yaml
│ │ ├── proposal.md
│ │ ├── specs/ # 增量规范（正在变更的内容）
│ │ ├── design.md
│ │ └── tasks.md
│ └── schemas/ # 自定义模式
└── .claude/skills/ # 自动生成的 Claude 集成
规范格式
规范使用 RFC 2119 关键词（应/必须/应当/可以）配合给定/当/那么场景：
markdown
需求：用户认证
系统在成功登录后必须签发 JWT 令牌。
场景：有效凭据
- - 给定 拥有有效凭据的用户
- 当 用户提交登录表单
- 那么 返回 JWT 令牌
增量规范
变更不会重写规范 — 它们描述增量（已添加/已修改/已移除），在归档时合并到主规范中。
配置
openspec/config.yaml 设置默认值：
yaml
schema: spec-driven # 或 tdd-driven、rapid、custom
context: |
技术栈：TypeScript、React、Node.js
测试：Jest
rules:
proposal:
- 包含回滚计划
specs:
- 使用给定/当/那么格式
