介绍
# OpenSpec — Spec-Driven Development
OpenSpec 将 AI 辅助开发构建为可跟踪的变更，并通过产物（提案、规范、设计、任务）来指导实施。
## 安装
```bash # 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 ```
## 核心工作流
每个变更遵循：**new → plan → apply → verify → archive**
### 1. 创建变更
```bash # Create change folder with default schema openspec new change <name>
# With specific schema openspec new change <name> --schema tdd-driven ```
### 2. 规划（创建产物）
使用 CLI 的 `instructions` 命令获取每个产物的增强提示：
```bash # Get instructions for next artifact openspec instructions --change <name> --json
# Check progress openspec status --change <name> --json ```
**产物序列（规范驱动模式）：** 1. `proposal.md` — 原因与内容（意图、范围、方法） 2. `specs/` — 需求 + 场景 3. `design.md` — 技术方案与架构决策 4. `tasks.md` — 带复选框的实施清单
### 3. 实施
阅读 `tasks.md` 并逐项完成，标记 `[x]` 表示完成。
### 4. 验证
```bash openspec validate --change <name> --json ```
检查完整性、正确性和连贯性。
### 5. 归档
```bash openspec archive <name> --yes ```
将增量规范合并到主 `openspec/specs/` 中，并将变更移至归档。
## Agent 工作流（如何作为 AI Agent 使用）
当用户要求使用 OpenSpec 构建/迁移/重构某些内容时：
1. **检查项目状态：** ```bash openspec list --json # Active changes openspec list --specs --json # Current specs openspec schemas --json # Available schemas ```
2. **创建变更：** ```bash openspec new change <name> [--schema <schema>] ```
3. **针对每个产物**，获取说明并创建文件： ```bash openspec instructions <artifact> --change <name> --json openspec status --change <name> --json ``` 然后将产物文件写入 `openspec/changes/<name>/`。
4. **实施** `tasks.md` 中的任务。
5. **验证并归档：** ```bash openspec validate <name> --json openspec archive <name> --yes ```
## CLI 快速参考
| 命令 | 用途 | |---------|---------| | `openspec list [--specs] [--json]` | 列出变更或规范 | | `openspec show <name> [--json]` | 显示变更/规范详情 | | `openspec status --change <name> [--json]` | 产物完成状态 | | `openspec instructions [artifact] --change <name> [--json]` | 获取增强的创建说明 | | `openspec validate [name] [--all] [--json]` | 验证变更/规范 | | `openspec archive <name> [--yes]` | 归档已完成变更 | | `openspec schemas [--json]` | 列出可用模式 | | `openspec templates [--json]` | 显示模板路径 | | `openspec config` | 查看/修改设置 |
程序化/Agent 使用时请务必使用 `--json`。
## 自定义模式
模式定义产物序列。为不同的工作流创建自定义模式：
```bash # 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/<name>/schema.yaml`，模板位于 `templates/`。
有关模式结构的详细信息，请参阅 [references/schemas.md](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 场景：
```markdown ### 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` 设置默认值：
```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 ```