openspec-overview

OpenSpec 是一个 AI-native 的 spec-driven development 工具。它在 AI coding agent 和项目代码之间插入一个可被程序消费的规范层，使 human-AI 协作从”口头对齐”升级为”可累积的结构化规格”。

---

一、原理

1.1 核心管线

源文件 (.md) → Markdown Parser → 结构化 spec 对象 → Zod Validator → 可消费数据
                                                        ↑
                                                   运行时安检门

OpenSpec 的 spec 文件是数据源而非文档终态——archive、validate、status 三个命令都会 parse 它。对比 TypeScript 类型（编译时消失），Zod Schema 在运行时持续生效，保证 spec 文件”程序可消费”。

1.2 三个核心子系统

Artifact Graph 引擎 — 将工作流从约定升级为系统约束。Schema YAML 定义 artifact 依赖（proposal → specs/design → tasks），转换成有向无环图后，Kahn 算法计算拓扑顺序。/opsx:continue 调用时，引擎根据文件系统上已完成的 artifact 计算下一个可执行的。proposal 未完成前，specs 的状态始终为 blocked。

Markdown Parser + Zod 校验 — Parser 从 spec 文件中提取 ### Requirement: 和 #### Scenario: 的层级结构，产出结构化对象。Zod 在 parser 产出后介入验证结构完整性——scenario 缺少 WHEN、requirement 缺失、格式不合法，Zod 直接报错，而非让错误静默传播到 archive 阶段。#### Scenario: 必须是 4 个 # 不是约定，是 parser 的格式依赖。

Delta Apply 引擎 — Archive 时将 change 的 delta specs 合并回主 specs 目录。ADDED 追加新 requirement，MODIFIED 完整替换对应 requirement，REMOVED 删除。

---

二、使用

2.1 快速使用

安装

npm install -g @fission-ai/openspec@latest

初始化

openspec init

检测 AI 工具 → 生成对应 SKILL.md → 创建 openspec/ 目录 + config.yaml。每个项目一次。

2.2 使用流程

/opsx:propose 描述
        │
        ▼
  内部自动解析、写spec,design,tasks
        │
        ▼
  提示 /opsx:apply 开始实现

或者逐步推进

/opsx:new 描述                     ← 交互式替代
        │
        ▼
  创建目录 → 展示 proposal 模板 → 停
        │
        ▼
  /opsx:continue → 写 specs → 停
        │
        ▼
  /opsx:continue → 写 design → 停
        │
        ▼
  /opsx:continue → 写 tasks → 停
        │
        ▼
  提示 /opsx:apply 开始实现

2.3 目录结构

openspec/
├── specs/              ← 累积的"真理源"（archive 时 delta 合并至此）
│   └── user-auth/
│       └── spec.md     ← 完整当前规格
├── changes/            ← 活跃 change
│   └── add-login/
│       ├── .openspec.yaml
│       ├── proposal.md       ← Why / What Changes / Capabilities / Impact
│       ├── specs/user-auth/spec.md   ← delta (ADDED/MODIFIED/REMOVED)
│       ├── design.md         ← 技术方案（可选）
│       └── tasks.md          ← checkbox 清单，apply 阶段 parse 进度
├── changes/archive/    ← 已归档
└── config.yaml         ← schema + context + rules

2.4 命令速查

commands	作用
openspec init	项目初始化
openspec list	列出活跃 changes（–specs 列出 specs）
openspec status	tasks.md checkbox 进度
openspec validate <name>	校验格式
openspec show <name>	查看 change/spec
openspec archive <name>	合并 delta + 移至 archive

skills	作用
/opsx:propose	一步生成全部 artifact
/opsx:apply	按 tasks.md 逐项实现
/opsx:archive	归档并合并 delta
/opsx:explore	探索/思考，不生成代码
/opsx:new	交互式创建，逐个 artifact 确认
/opsx:continue	继续写下一个 artifact
/opsx:ff	快速模式，一步全部
/opsx:verify	验证实现是否符合 spec

2.5 配置

# openspec/config.yaml
schema: spec-driven
context: |                # 项目背景，AI 读 instructions 时注入
  Tech stack: ...
rules:                    # 针对各 artifact 的约束
  specs: ...
  design: ...
  tasks: ...

context 和 rules 是给 AI 的约束，模板由 openspec init 自动生成，内容由开发者填入

---

三、与 Superpowers 的差异

相关笔记详见superpowers-overview

3.1 定位

	OpenSpec	Superpowers
关注层	需求→规格的结构化与累积	交付流程的纪律性控制
启动方式	openspec init + /opsx:propose	会话启动自动注入
强制方式	系统约束（Schema YAML + Kahn 拓扑）	硬断言门禁式
Spec	有生命周期，随项目累积演进	写入后静置，由文件数累积

3.2 互补关系

Superpowers 解决”如何有质量地交付”（流程纪律），OpenSpec 解决”规格如何随项目成长”（结构累积）。两者互补而非竞争，可在同一项目中共存

需求池
  │
  ▼
OpenSpec:      /opsx:propose
  │
  ▼
Superpowers:   /subagent-driven-development or /execute-plan ...
  │
  ▼
OpenSpec:      /opsx:archive
  │
  ▼
交付