用途
OpenSpec 技能用于以规格驱动的方式管理开发工作流,核心工具是 openspec CLI。它把“当前已构建的事实”(specs/)与“计划要做的变更”(changes/)分开管理,让团队在动手实现前先写清提案、任务和规格差异,实现后再归档并同步规格。
主要能力
- 三阶段工作流:创建变更(Creating Changes)、实现变更(Implementing Changes)、归档变更(Archiving Changes)。
- 变更提案脚手架:在 openspec/changes/<id>/ 下生成 proposal.md、tasks.md、design.md(按需)以及按能力划分的 delta 规格。
- 规格差异(delta)书写:支持 ## ADDED / MODIFIED / REMOVED / RENAMED Requirements,每个需求至少包含一个 #### Scenario:。
- 校验:openspec validate [change-id] --strict 检查变更或规格是否合规。
- 归档:部署后将 changes/[name]/ 移动到 changes/archive/YYYY-MM-DD-[name]/,并在能力变化时更新 specs/。
- 项目初始化与更新:openspec init [path]、openspec update [path]。
- 调试辅助:openspec show [change] --json --deltas-only 等。
使用方式
常用命令:
openspec list # 列出进行中的变更
openspec list --specs # 列出规格
openspec show [item] # 显示变更或规格
openspec validate [item] # 校验变更或规格
openspec archive <change-id> [--yes|-y] # 部署后归档
openspec init [path] # 初始化 OpenSpec
openspec update [path] # 更新指令文件
openspec show [change] --json --deltas-only
openspec validate [change] --strict
可用标志:--json、--type change|spec、--strict、--no-interactive、--skip-specs、--yes/-y。
目录结构:
openspec/
├── project.md # 项目约定
├── specs/ # 当前事实——已构建的内容
│ └── [capability]/
│ ├── spec.md # 需求与场景
│ └── design.md # 技术模式
├── changes/ # 提案——应该变更的内容
│ ├── [change-name]/
│ │ ├── proposal.md # 原因、内容、影响
│ │ ├── tasks.md # 实现清单
│ │ ├── design.md # 技术决策(可选)
│ │ └── specs/ # 差异变更
│ │ └── [capability]/
│ │ └── spec.md # ADDED/MODIFIED/REMOVED
│ └── archive/ # 已完成的变更
创建变更提案的决策树:
新请求?
├─ 修复规格行为的缺陷? → 直接修复
├─ 拼写/格式/注释? → 直接修复
├─ 新功能/能力? → 创建提案
├─ 破坏性变更? → 创建提案
├─ 架构变更? → 创建提案
└─ 不明确? → 创建提案(更稳妥)
proposal.md 模板:
# Change: [简要描述]
## Why
[1-2 句说明问题/机会]
## What Changes
- [要点列表]
- [破坏性变更标记 **BREAKING**]
## Impact
- Affected specs: [列出能力]
- Affected code: [关键文件/系统]
规格差异模板:
## ADDED Requirements
### Requirement: New Feature
The system SHALL provide...
#### Scenario: Success case
- **WHEN** user performs action
- **THEN** expected result
## MODIFIED Requirements
### Requirement: Existing Feature
[完整的修改后需求]
## REMOVED Requirements
### Requirement: Old Feature
**Reason**: [移除原因]
**Migration**: [如何处理]
tasks.md 模板:
## 1. Implementation
- [ ] 1.1 Create database schema
- [ ] 1.2 Implement API endpoint
- [ ] 1.3 Add frontend component
- [ ] 1.4 Write tests
design.md(按需创建)适用于:跨领域变更或新架构模式;新增外部依赖或重大数据模型变更;安全、性能或迁移复杂度;需要技术决策消解的歧义。其结构包括 Context、Goals / Non-Goals、Decisions、Risks / Trade-offs、Migration Plan、Open Questions。
规格文件格式要点:场景必须使用 #### 标题,例如:
#### Scenario: User login success
- **WHEN** valid credentials provided
- **THEN** return JWT token
错误写法包括用列表项、加粗或 ### 表示场景。每个需求必须至少有一个场景。规范性需求使用 SHALL/MUST。
ADDED 与 MODIFIED 的区别:ADDED 是独立的新能力;MODIFIED 改变现有需求的行为,必须粘贴完整的更新后需求(标题加场景);RENAMED 仅改名,若同时改行为则用 RENAMED + MODIFIED。常见陷阱是 MODIFIED 未包含原有文本,导致归档时细节丢失。
适用场景
- 新功能或新能力。
- 破坏性变更(API、schema)。
- 架构变更。
- 性能优化。
- 安全模式更新。
以下情况可跳过提案:修复缺陷以恢复规格行为、拼写/格式/注释、非破坏性依赖更新、配置变更、针对现有行为的测试。
限制
- 实现前需先获得提案批准,未批准不应开始实现。
- 校验依赖严格的格式:场景必须用 #### Scenario:,需求必须至少有一个场景,否则会报错或静默解析失败。
- MODIFIED 必须包含完整需求文本,否则归档时可能丢失细节。
- 归档时若能力发生变化需更新 specs/;仅工具类变更可用 openspec archive <change-id> --skip-specs --yes。
- 关于收费、价格、平台支持范围等信息,资料中暂未提供。