什么是 OpenSpec？
OpenSpec 是一个规范驱动的 AI 辅助开发工具，旨在帮助开发团队通过结构化的工作流管理需求变更和代码实现。
核心理念
传统的 AI 编程助手通常是无状态的对话模式 —— 每次会话都需要重新描述上下文，容易产生需求遗漏或执行偏差。OpenSpec 通过引入 「规范即真相」 的机制，让 AI 始终基于明确的规格文档进行工作。
简单来说，OpenSpec 回答了两个关键问题：
- 系统现在是什么样的？ → specs/ 目录
- 我们打算改什么？ → changes/ 目录
安装
前置条件：Node.js 20.19.0 或更高版本
npm install -g @fission-ai/openspec@latest
初始化
进入你的项目目录并执行初始化：
cd your-project
openspec init
初始化过程中，OpenSpec 会询问你使用的 AI 编辑器。选择你需要的编辑器后，系统会自动生成：
- openspec/ 目录（包含项目配置）
- 对应 AI 编程工具的主流配置文件
💡 提示：部分 AI 工具中可通过 /init 命令生成对应配置文件。
初始化之后ai会询问你使用什么ai 编辑器，选择你需要的，就会在当前目录下生成openspec目录和对应AI编程的主流配置文件，你在使用编程工具的时候/init也会有对应的配置文件
让ai帮你写一下openspec/config.yaml的配置文件，文件里面的context会注入到就是在每次回话的时候告诉ai对应的技术栈，rules 则是针对特定工件类型的额外要求。
schema: spec-driven
# Project context (optional)
# This is shown to AI when creating artifacts.
# Add your tech stack, conventions, style guides, domain knowledge, etc.
# Example:
# context: |
# Tech stack: TypeScript, React, Node.js
# We use conventional commits
# Domain: e-commerce platform
# Per-artifact rules (optional)
# Add custom rules for specific artifacts.
# Example:
# rules:
# proposal:
# – Keep proposals under 500 words
# – Always include a "Non-goals" section
# tasks:
# – Break tasks into chunks of max 2 hours
配置 config.yaml
建议让 AI 协助编写 openspec/config.yaml 配置文件。配置包含两个关键部分：
|
配置项 |
说明 |
作用 |
|
context |
项目上下文信息 |
每次会话时注入给 AI，说明技术栈、开发规范等 |
|
rules |
各类型工件的额外要求 |
针对 proposal、tasks 等特定工件类型定义规则 |
配置示例：
schema: spec-driven
# 项目上下文 —— 每次对话时注入给 AI
context: |
Tech stack: TypeScript, React, Node.js
We use conventional commits
Domain: e-commerce platform
# 工件规则 —— 针对特定类型工件的约束
rules:
proposal:
– Keep proposals under 500 words
– Always include a "Non-goals" section
tasks:
– Break tasks into chunks of max 2 hours
项目目录结构
openspec/
├── specs/ # 系统当前行为的「源真相」—— 「系统现在是什么样的」
├── changes/ # 每个变更的独立工作目录 —— 「我们打算改什么」
├── archive/ # 已完成变更的归档目录 —— 「历史记录」
└── config.yaml # 项目配置文件
使用流程
OpenSpec 遵循 Propose → Apply → Archive 的三步工作流：
1. 提出变更需求
/opsx:propose <需求描述>
执行该命令后，OpenSpec 会自动生成完整的规划文档（位于 changes/ 目录下）。
关键步骤：检查生成的规划文档，确认需求描述是否清晰。如有不明确之处，可手动修改相应文档。
2. 执行变更任务
/opsx:apply
在执行过程中，OpenSpec 会根据不同场景自动调用 Superpower 技能来辅助完成。
3. 归档变更记录
/opsx:archive
变更完成后执行此命令，将任务归档至 archive/ 目录，保留完整的历史记录。
流程示意图
/opsx:propose → /opsx:apply → /opsx:archive
↓ ↓ ↓
生成规划文档 执行变更任务 归档历史记录
