OpenSpec

wiki/ai/entities/OpenSpec.md

分类：ai / entities · 更新：2026-06-14 00:33

OpenSpec

概述

OpenSpec 是一个开源的规格驱动开发工具（Spec-driven development），由 Fission-AI 维护。核心理念是在 AI 写代码之前，先对齐「要做什么」。GitHub 仓库 Fission-AI/OpenSpec，4.2 万+ Star，MIT 协议。

项目结构（openspec init 生成）

openspec/
├── specs/              # 真实来源 — 描述系统当前行为
│   └── <domain>/
│       └── spec.md
├── changes/            # 提议的修改（每个修改一个文件夹）
│   └── <change-name>/
│       ├── proposal.md    # 为什么做 + 做什么
│       ├── design.md      # 怎么做 — 技术方案
│       ├── tasks.md       # 实施清单 (checkbox)
│       ├── .openspec.yaml # 变更元数据
│       └── specs/         # 差量规格 (Delta Specs)
├── schemas/            # 自定义工作流 schema (可选)
└── config.yaml         # 项目配置

.openspec.yaml 配置格式

变更元数据（每个 change 文件夹内）

schema: spec-driven
created: "2025-01-23"

项目配置（openspec/config.yaml）

schema: spec-driven          # 默认 schema
context: |                    # 注入所有 artifact 的 AI prompt
  Tech stack: TypeScript, React, Node.js
  API style: RESTful
rules:                        # 按 artifact 分组的自定义规则
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format

Schema 优先级：CLI 参数 > .openspec.yaml > config.yaml > 默认 spec-driven

核心工作流（OPSX 命令）

快速路径（core profile）

/opsx:propose → /opsx:apply → /opsx:sync → /opsx:archive

完整路径

/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive

命令清单

命令	用途
/opsx:propose	一步创建变更 + 所有规划文档
/opsx:explore	探索想法，不创建 artifact
/opsx:apply	执行 tasks.md 任务清单
/opsx:sync	将差量规格合并到主规格
/opsx:archive	归档已完成变更
/opsx:verify	验证实现是否与规格匹配

差量规格（Delta Specs）— 核心创新

不重写整个规格，只描述变更：

ADDED → 追加到主规格
MODIFIED → 替换现有需求
REMOVED → 从主规格中删除

支持 29+ 种 AI 工具

包括 Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Gemini 等。

与 CLAUDE.md / AGENTS.md 的区别

CLAUDE.md 只告诉 AI 项目上下文（单文件）
OpenSpec 建立完整的「规格即代码」工作流（结构化目录 + 变更追踪 + 审计）
两者可共存：OpenSpec 在 workspace 模式下维护 AGENTS.md

安装

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init                  # 交互式
openspec init --tools claude   # 指定工具

定位

在「三件套」组合中，OpenSpec 负责「想清楚」——规格定义、需求对齐、技术方案。与 Superpowers（拆清楚）和 gstack（做清楚）形成流水线。

适合场景

中大型功能开发，需要明确需求的项目
不适合小改小修

注意

对模型能力要求高，推荐 Opus 4.5 / GPT 5.2
学习曲线不低