SuperAPI AI 工具集

openspec

编程与开发

查看项目

更新于 10-16 07:29

技能介绍

用途

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。
  • 关于收费、价格、平台支持范围等信息,资料中暂未提供。