openspec使用手册

Shawn_Shawn2026-04-13 21:27

安装

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

nodejs版本要求：>= 20.19.0

  1. 安装命令
css 复制代码 
npm install -g @fission-ai/openspec@latest
  1. 初始化项目
bash 复制代码 
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
提案文档] SPECS[specs/
能力规范] DESIGN[design.md
设计文档] TASKS[tasks.md
任务清单] ARCHIVE[archive/
历史归档] end subgraph "AI 工具集成" CMD[Commands
斜杠命令] SKILL[Skills
技能模块] INST[agent-instructions.md
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 分享意图
/openspec:proposal| P2[2. 审核与对齐] P2 -->|反馈循环| Feed{需要修改?} Feed -->|是| P2 Feed -->|否| P3[3. 实施任务] P3 -->|AI 按规范编写代码
/openspec:apply| P4[4. 归档并更新规范] P4 -->|/openspec:archive| End([结束]) subgraph 输出 O1[proposal.md
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

安装位置
perl 复制代码 
<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>

使用流程：

生成的文件结构：

bash 复制代码 
<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

安装位置
objectivec 复制代码 
<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 元数据
< 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
描述需求] 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

目录结构详解

完整目录结构

yaml 复制代码 
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
描述需求] 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目录的作用

职责

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

归档格式
bash 复制代码 
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 理解现有系统能力

规范创建指南

项目级规范

创建步骤
bash 复制代码 
# 1. 初始化项目
cd your-project
openspec init

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

# 3. 编辑项目上下文
vim openspec/project-context.md
project-context.md 模板
xml 复制代码 
# 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比较合适。

模块级规范

创建步骤
sql 复制代码 
# 创建模块变更
openspec new change user-management-module

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

最佳实践

提案编写最佳实践

✅ 推荐做法
markdown 复制代码 
## 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
协作技巧
  1. /opsx:proposal执行完命令后，生成proposal.md, design.md, task.md和spec.md文件
  2. 人工去review一下这些文件，主要看看design和task是否合理，可以修改，修改spec.md，看看规范是否合理
  3. review完成之后再进行/opsx:appy <task_name>
  4. 最后再archive

高阶功能

安装额外的workflow:

openspec config profile

openspec update

参考手册：

github.com/Fission-AI/...

实战案例

相关推荐
刀法如飞4 小时前
AI Agent实战：我用Gemini批量完成了《道德经》解读
程序员·aigc·ai编程
小虎AI生活4 小时前
7 个理由 +3 步安装：Gemma 4 外贸选型与部署全攻略
ai编程
C澒4 小时前
IntelliPro 企业级产研协作平台：前端智能生产模块设计与落地
前端·ai编程
Cosolar5 小时前
Nanobot 深度解析：超轻量级通用 AI Agent 运行时的架构设计与实战指南
gpt·llm·ai编程
孟健5 小时前
我把Hermes里23个Agent全切到GLM-5.1：执行力比GPT强，但有个硬伤
ai编程
Cosolar5 小时前
Nanobot：超轻量个人 AI 智能体
chatgpt·langchain·llm
爱吃的小肥羊6 小时前
2026 最新 Codex 如何使用指南：ChatGPT 订阅、CLI 安装、App 登录全流程
aigc·ai编程
OpenTiny社区6 小时前
重磅预告｜OpenTiny 亮相 QCon 北京，共话生成式 UI 最新技术思考
前端·开源·ai编程
小村儿6 小时前
Harness Engineering：为什么你用 AI 越用越累？
前端·后端·ai编程
热门推荐
01GitHub 镜像站点022026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元03一周AI热点速览（2026.03.31-04.06）：GPT-6曝光、谷歌开源Gemma 4、资本狂飙与模型军备竞赛04基于 Docker 部署 Hermes Agent 并接入飞书机器人的完整指南05免费！不限量！用opencode接入英伟达（NVIDIA）大模型，轻松打造你的 AI 编程助手06Oh My Codex 快速使用指南07从限购到畅通：GLM-5.1 Coding Plan接入攻略08CodeBuddy与WorkBuddy深度对比：腾讯两款AI工具差异及实操指南09LLM Wiki：让大模型替你打理知识库的完整指南10AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析