openspec使用手册安装 claude code的安装：https://code.claude.com/docs/z

安装

claude code的安装：code.claude.com/docs/zh-CN/…

nodejs版本要求：>= 20.19.0

安装命令

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

2. 初始化项目

cd your-project
openspec init

简介与背景

什么是 OpenSpec？

OpenSpec 是一个专为 AI 智能体（如 Claude Code、Cursor、Windsurf 等）设计的开源、轻量级规范驱动开发框架和命令行工具（CLI）。它通过"提案-审查-实施-归档"工作流，解决 AI 编程中的需求偏移与不可预测性问题 [1][2]。

为什么需要 OpenSpec？

问题	OpenSpec 解决方案
需求不明确	强制在 proposal.md 中说明"为什么"和"改什么"
设计思路不明确	通过 design.md 说明详细的设计实现方案
AI 过度实现	通过 tasks.md 限定具体实施范围
规范缺失	specs/ 作为系统行为的单一真相来源
变更难追溯	changes/archive/ 保留所有历史提案和决策
团队协作冲突	变更提案在实施前集中审核，避免重复工作

架构设计

整体架构

graph TB
    subgraph "用户层"
        U[开发者]
        AI[AI 助手]
    end
  
    subgraph "OpenSpec 核心"
        CLI[CLI 工具]
        VAL[验证引擎]
        ARCH[归档引擎]
    end
  
    subgraph "数据层"
        PROP[proposal.md<br/>提案文档]
        SPECS[specs/<br/>能力规范]
        DESIGN[design.md<br/>设计文档]
        TASKS[tasks.md<br/>任务清单]
        ARCHIVE[archive/<br/>历史归档]
    end
  
    subgraph "AI 工具集成"
        CMD[Commands<br/>斜杠命令]
        SKILL[Skills<br/>技能模块]
        INST[agent-instructions.md<br/>AI 指导文件]
    end
  
    U --> CLI
    CLI --> VAL
    VAL --> PROP
    VAL --> SPECS
    AI --> CMD
    AI --> SKILL
    AI --> INST
    INST --> PROP
    CMD --> PROP
    SKILL --> PROP
    PROP --> DESIGN
    DESIGN --> TASKS
    TASKS --> ARCH
    ARCH --> ARCHIVE
    SPECS --> ARCH
  
    style CLI fill:#4ecdc4
    style SPECS fill:#45b7d1
    style ARCHIVE fill:#96ceb4

核心组件

CLI 工具

提供命令行接口，支持：

项目初始化 (openspec init)
创建变更提案 (openspec new change)
验证规范 (openspec validate)
归档变更 (openspec archive)

文档系统

proposal.md：说明"为什么做"和"做什么"
design.md：技术设计和架构决策
tasks.md：实施任务清单
specs/ ：能力规范（Delta Specs & Main Specs）

AI 集成层

通过 Commands 和 Skills 与 AI 工具集成，提供：

/openspec:proposal - 创建提案
/openspec:apply - 应用规范
/openspec:archive - 归档变更

核心工作流

四步工作流

flowchart TD
    Start([开始]) --> P1[1. 起草变更提案]
    P1 -->|与 AI 分享意图<br/>/openspec:proposal| P2[2. 审核与对齐]
  
    P2 -->|反馈循环| Feed{需要修改?}
    Feed -->|是| P2
    Feed -->|否| P3[3. 实施任务]
  
    P3 -->|AI 按规范编写代码<br/>/openspec:apply| P4[4. 归档并更新规范]
    P4 -->|/openspec:archive| End([结束])
  
    subgraph 输出
        O1[proposal.md<br/>tasks.md]
        O2[锁定意图]
        O3[可预测的代码]
        O4[更新真相来源]
    end
  
    P1 -.-> O1
    P2 -.-> O2
    P3 -.-> O3
    P4 -.-> O4
  
    style P1 fill:#ff9a9e
    style P2 fill:#ffecd2
    style P3 fill:#a8edea
    style P4 fill:#d299c2

工作流详解

阶段	动作	产出
1. 提案	AI 生成变更文件结构	proposal.md + design.md + tasks.md + spec 增量
2. 审查	人工审核、迭代修改	锁定意图
3. 实施	AI 严格按 tasks.md 编码	可预测的代码
4. 归档	将变更合并进 specs/	更新"真相来源"

操作手册

Commands 与 Skills

Commands

安装位置

<your_project>/
├── .claude/
│   └── commands/
│       └── openspec/
│           ├── proposal.md    # 创建提案命令
│           ├── apply.md       # 应用规范命令
│           └── archive.md     # 归档变更命令
└── .cursor/
    └── commands/
        └── opsx/
            ├── proposal.md
            ├── apply.md
            └── archive.md

核心命令

`/opsx:proposal` - 创建提案

用途：生成变更提案文档，包含提案、设计和任务清单。

用法：/opsx:proposal <your_prompt>

使用流程：

生成的文件结构：

<your_project>openspec/changes/user-auth/ # user_auth是openspec生成的一个task_name
├── .openspec.yaml           # 元数据
├── proposal.md              # 提案文档
├── design.md                # 技术设计
├── tasks.md                 # 任务清单
└── specs/
    └── auth/
        └── spec.md          # 认证能力规范

`/opsx:apply` - 应用规范

用途：严格按规范实现代码。

用法：/opsx:apply <task_name>

流程：

`/opsx:archive` - 归档变更

用途：将已完成的变更归档，更新主规范库。

用法：/opsx:archive <task_name>

流程：

sequenceDiagram
    participant U as 用户
    participant AI as AI 助手
    participant FS as 文件系统
  
    U->>AI: /openspec:archive user-auth
    AI->>FS: 合并 delta specs 到 main specs
    AI->>FS: 移动 changes/user-auth 到 archive/
    AI->>FS: 更新 specs/auth/spec.md
    AI->>U: 归档完成

Skills

安装位置

<your_project>/
├── .claude/
│   └── skills/
│       └── openspec/
│           └── SKILL.md      # OpenSpec 技能定义
└── .cursor/
    └── skills/
        └── openspec/
            └── SKILL.md

Skills 与 Commands 的区别

特性	Commands	Skills
触发方式	`/命令名`	自动识别或手动调用
加载方式	即时加载	懒加载（按需）
适用场景	明确的操作步骤	上下文感知的智能行为
上下文占用	较大	较小（初始只加载元数据）

4.2.3 Skills 工作原理

flowchart LR
    Start[用户请求] --> Load{Skill 相关?}
    Load -->|是| Meta[加载 SKILL.md 元数据<br/>< 1KB]
    Load -->|否| Normal[正常处理]
  
    Meta --> Decide{任务匹配?}
    Decide -->|是| Full[加载完整 SKILL.md]
    Decide -->|否| Normal
  
    Full --> Exec[执行 Skill 指令]
    Exec --> Result[返回结果]
    Normal --> Result
  
    style Meta fill:#e8f5e9
    style Full fill:#c8e6c9

完整使用流程

graph TD
    Start([开始新功能开发]) --> New[openspec new change feature-name]
    New --> Prop[openspec:proposal<br/>描述需求]
  
    Prop --> Review{审核提案}
    Review -->|需要修改| Edit[编辑文档]
    Edit --> Review
  
    Review -->|通过| Validate[openspec validate feature-name]
    Validate --> Valid{验证通过?}
    Valid -->|否| Fix[修复格式问题]
    Fix --> Validate
  
    Valid -->|是| Apply[openspec:apply]
    Apply --> Test{测试通过?}
    Test -->|否| Debug[调试修复]
    Debug --> Test
  
    Test -->|是| Archive[openspec archive feature-name]
    Archive --> End([完成])
  
    style New fill:#e1f5fe
    style Prop fill:#fff3e0
    style Apply fill:#e8f5e9
    style Archive fill:#f3e5f5

目录结构详解

完整目录结构

your-project/
├── .openspec/                      # OpenSpec 内部配置（自动生成）
│   └── config.json
│
├── openspec/                       # OpenSpec 工作目录
│   ├── AGENTS.md                   # AI 代理指导文件
│   ├── project.md                  # 项目上下文
│   │
│   ├── changes/                    # 活跃的变更提案
│   │   ├── feature-auth/           # 变更：用户认证
│   │   │   ├── .openspec.yaml      # 元数据
│   │   │   ├── proposal.md         # 提案文档
│   │   │   ├── design.md           # 技术设计
│   │   │   ├── tasks.md            # 任务清单
│   │   │   └── specs/              # Delta Specs（变更规范）
│   │   │       └── auth/
│   │   │           └── spec.md
│   │   │
│   │   └── feature-payment/        # 变更：支付功能
│   │       └── ...
│   │
│   ├── specs/                      # Main Specs（主规范库）
│   │   ├── auth/                   # 已归档：认证能力
│   │   │   └── spec.md
│   │   ├── user-management/        # 已归档：用户管理
│   │   │   └── spec.md
│   │   └── payment/                # 已归档：支付能力
│   │       └── spec.md
│   │
│   └── archive/                    # 历史归档
│       ├── 2024-01-15-feature-auth/
│       │   ├── proposal.md
│       │   ├── design.md
│       │   ├── tasks.md
│       │   └── specs/
│       └── 2024-02-20-feature-payment/
│           └── ...
│
├── .claude/                        # Claude Code 配置
│   ├── commands/
│   │   └── openspec/
│   │       ├── proposal.md
│   │       ├── apply.md
│   │       └── archive.md
│   └── skills/
│       └── openspec/
│           └── SKILL.md
│

changes目录的作用

职责

存放活跃的变更提案，每个功能/变更一个文件夹。

生命周期

graph TD
    Start([开始新功能开发]) --> New[openspec new change feature-name]
    New --> Prop[openspec:proposal<br/>描述需求]
  
    Prop --> Review{审核提案}
    Review -->|需要修改| Edit[编辑文档]
    Edit --> Review
  
    Review -->|通过| Validate[openspec validate feature-name]
    Validate --> Valid{验证通过?}
    Valid -->|否| Fix[修复格式问题]
    Fix --> Validate
  
    Valid -->|是| Apply[openspec:apply]
    Apply --> Test{测试通过?}
    Test -->|否| Debug[调试修复]
    Debug --> Test
  
    Test -->|是| Archive[openspec archive feature-name]
    Archive --> End([完成])
  
    style New fill:#e1f5fe
    style Prop fill:#fff3e0
    style Apply fill:#e8f5e9
    style Archive fill:#f3e5f5

使用场景

场景	操作
新功能开发	`openspec new change feature-name`
Bug 修复	`openspec new change fix-bug-xxx`
重构	`openspec new change refactor-module`
架构变更	`openspec new change architecture-update`

archive目录的作用

职责

存放已归档的历史变更，保留完整的决策历史和演进记录。

归档格式

archive/
└── YYYY-MM-DD-change-name/        # 归档时间 + 变更名称
    ├── proposal.md                 # 原提案文档
    ├── design.md                   # 原设计文档
    ├── tasks.md                    # 原任务清单
    └── specs/                      # 原 Delta Specs

双重规格系统

OpenSpec 最精妙的设计之一：Delta Specs vs Main Specs。

对比

特性	Delta Specs (changes/specs/)	Main Specs (openspec/specs/)
中文名	变更规格（拟议）	主规格（真理之源）
状态	Draft（草稿/拟议中）	Live（生效中/已发布）
含义	"我希望系统变成什么样"	"系统现在是什么样"
生命周期	随变更创建，归档即消失（合并）	永久存在，随项目演进
Git 类比	Feature Branch（功能分支）	Main Branch（主分支）
作用	指导 AI 完成本次开发任务	指导 AI 理解现有系统能力

规范创建指南

项目级规范

创建步骤

# 1. 初始化项目
cd your-project
openspec init

# 2. 创建第一个变更
openspec new change project-setup

# 3. 编辑项目上下文
vim openspec/project-context.md

project-context.md 模板

# Project Context

## Purpose
<!-- 项目目的和目标 -->

## Technology Stack
<!-- 技术栈 -->


## Architecture
<!-- 架构设计 -->


## Constraints
<!-- 约束条件 -->

## Conventions
<!-- 代码规范 -->

## Git Conventions
<!-- git规范 -->

## UT Conventions
<!-- git规范 -->

## Dependencies
<!-- 关键依赖 -->

如果团队规定都在应用openspec，那么维护project-context.md也行。但如果团队并没有强制要求openspec，可能会用spec kit工具，或者其他Skills，或者混用，那么仅维护project-context.md是不够的。建议还是维护CLAUDE.md比较合适。

模块级规范

创建步骤

# 创建模块变更
openspec new change user-management-module

# 这会生成：
# openspec/changes/user-management-module/specs/user-management/spec.md

最佳实践

提案编写最佳实践

✅ 推荐做法

## Why

### Background
当前系统没有用户认证功能，任何人都可以访问所有数据和功能。
这导致：
- 无法追踪操作日志的责任人
- 敏感数据缺乏保护
- 无法实现细粒度的权限控制

### Problem Statement
系统需要一个安全可靠的用户认证机制，支持：
- 用户名密码登录
- 第三方 OAuth 登录（GitHub、Google，微信）
- 会话管理和安全退出
- 支持手机号、邮箱 验证码登录

### Alternatives Considered
1. **自建认证系统**：完全控制，但开发维护成本高
2. **使用 Auth0**：功能完善，但费用较高
3. **使用 Keycloak**：开源免费，支持多种协议 ✓ 已选择此方案

❌ 避免的做法

添加用户认证功能。

使用流程

Commands 使用

命令	用途	示例
`/opsx:proposal`	创建新的变更提案	`/opsx:proposal 添加用户认证功能`
`/opsx:apply`	应用变更规范到代码实现	`/opsx:apply user-auth`
`/opsx:archive`	归档已完成的变更	`/opsx:archive user-auth`

协作技巧

/opsx:proposal执行完命令后，生成proposal.md, design.md, task.md和spec.md文件
人工去review一下这些文件，主要看看design和task是否合理，可以修改，修改spec.md，看看规范是否合理
review完成之后再进行/opsx:appy <task_name>
最后再archive

高阶功能

安装额外的workflow:

openspec config profile

openspec update

参考手册：

github.com/Fission-AI/…

openspec使用手册

安装

简介与背景

什么是 OpenSpec？

为什么需要 OpenSpec？

架构设计

整体架构

核心组件

CLI 工具

文档系统

AI 集成层

核心工作流

四步工作流

工作流详解

操作手册

Commands 与 Skills

Commands

安装位置

核心命令

/opsx:proposal - 创建提案

/opsx:apply - 应用规范

/opsx:archive - 归档变更

Skills

安装位置

Skills 与 Commands 的区别

4.2.3 Skills 工作原理

完整使用流程

目录结构详解

完整目录结构

changes目录的作用

职责

生命周期

使用场景

archive目录的作用

职责

归档格式

双重规格系统

对比

规范创建指南

项目级规范

创建步骤

project-context.md 模板

模块级规范

创建步骤

最佳实践

提案编写最佳实践

✅ 推荐做法

❌ 避免的做法

使用流程

Commands 使用

协作技巧

高阶功能

实战案例

`/opsx:proposal` - 创建提案

`/opsx:apply` - 应用规范

`/opsx:archive` - 归档变更