OpenSpec 简明教程

1. 是什么

OpenSpec 是一个规范驱动开发 工具,专为 AI 编码助手设计。核心理念很简单:写代码前,先让人类和 AI 对"要做什么"达成一致。

它解决的是"凭感觉聊天"式开发的痛点------需求散落在聊天记录里,AI 容易遗漏需求或偏离预期。OpenSpec 通过轻量级的规范流程,把模糊提示变成可审查、可落地的工程计划。

核心结构:

ini 复制代码
openspec/
├── specs/        # 已实现的功能(真相之源)
└── changes/      # 待实现的提案
    └── [变更名]/
        ├── proposal.md   # 为什么要做、做什么
        ├── design.md     # 技术方案
        ├── tasks.md      # 实施清单
        └── specs/        # 规范增量(补丁)

2. 快速上手

环境要求: Node.js 20.19.0 或更高版本

安装与初始化:

bash 复制代码
# 全局安装
npm install -g openspec-cn/openspec

# 进入项目目录
cd your-project

# 初始化
openspec init

初始化会创建 openspec/ 目录结构,并根据你的 AI 工具配置对应的斜杠命令。

3. 核心工作流

OpenSpec 采用四步工作流,全程通过斜杠命令与 AI 交互:

命令 阶段 功能
/opsx:new 规划 创建新变更,生成首个工件模板
/opsx:ff 规划 "快进"------一次性生成所有规划文档
/opsx:apply 实施 按任务清单实现代码
/opsx:archive 收尾 归档已完成变更,更新主规范

实操示例(以"添加深色模式"为例):

bash 复制代码
# 1. 创建变更
/opsx:new add-dark-mode
→ 创建 openspec/changes/add-dark-mode/

# 2. 生成全部规划文档
/opsx:ff
→ ✓ proposal.md  ✓ specs/  ✓ design.md  ✓ tasks.md

# 3. 开始实施
/opsx:apply
→ 逐步完成 tasks.md 中的任务清单

# 4. 归档
/opsx:archive
→ 移至 changes/archive/,更新 specs/

4. 命令速查

斜杠命令(AI 对话)

命令 读/写 用途
/opsx:explore 只读 探索想法、调研问题
/opsx:new 写入 创建新变更
/opsx:continue 写入 逐个创建工件
/opsx:ff 写入 一次性创建所有工件
/opsx:apply 写入 按任务清单实现代码
/opsx:verify 只读 验证实现与规范的一致性
/opsx:archive 写入 归档已完成变更

CLI 命令(终端)

命令 用途
openspec list 列出进行中的变更
openspec list --specs 列出所有规范
openspec show [item] 查看变更/规范详情
openspec validate [item] 验证变更/规范格式
openspec archive <id> --yes 非交互式归档

5. 关键原则

1. 棕地优先 ------ 不要求从零开始,与存量项目完美兼容

2. 规范即真相 ------ specs/ 是已实现功能的唯一真相源,changes/ 是待实施的提案

3. 增量变更 ------ 每个变更独立成文件夹,归档后合并回主规范,历史清晰可追溯

4. 人在回路 ------ AI 生成提案后必须经过人工审查确认,再进入实施阶段

6. 支持的工具

OpenSpec 支持 20+ AI 编码助手,包括:

  • 原生斜杠命令:Claude Code、Cursor、GitHub Copilot、Windsurf、CodeBuddy
  • AGENTS.md 兼容 :其他工具可读取 openspec/AGENTS.md 获取工作流指引
相关推荐
码事漫谈31 分钟前
# 2027年,AI终于要开始“干活”了
后端
小满zs1 小时前
Go语言第二十一章(Gin上传文件)
后端·go
JavaGuide3 小时前
Cloudflare 开源的这套神级安全审计 Skill 太好用了!
前端·后端
学长毕设4 小时前
基于SpringBoot社区快递驿站物流配送系统-附源码
java·spring boot·后端
Resean02234 小时前
Spring 源码分析(七)AOP 原理(上):代理的创建
java·后端·spring
Tangq一定可以的4 小时前
Spring AI Advisor 详解 - 给大模型调用加上“切面“,日志/过滤/记忆一键搞定
java·后端·spring
小巫编程室5 小时前
我造了一个 Java 能力包:让 AI 直接调用你的业务代码
java·前端·后端
十有八七5 小时前
手搓 Agent(五):学会翻书——RAG,先查资料再回答
前端·人工智能·后端
Swot5 小时前
产品 RAG 知识库与 AI 顾问 设计与实现
前端·后端
深入云栈6 小时前
Netty 4.2.x 源码深度解析 (二十四):池化内存分配 —— PoolArena、PoolChunk 与 PoolSubpage
java·后端·架构