OpenSpec 完全指南：让 AI 编码可预测的规范框架

一、AI 编程的"甜蜜陷阱"

随着 AI 编程助手日趋智能，开发者往往在"无需动脑、不用写文档"的诱惑下上手，但随之而来的是输出无序、需求跑偏、维护困难等隐患——这正是所谓的"甜蜜陷阱"。

---

二、规范驱动开发

以"明确做什么、为什么做"为前提，引入结构化规范文档，让 AI 从"规范"而非零散提示中读取需求，从而输出更可控、更易维护的代码。

---

三、为什么选用 OpenSpec

OpenSpec 是一款轻量、灵活的 AI 辅助开发规范工具，具有以下核心优势：

• 轻量灵活：无刚性阶段门，随时迭代，避免繁文缛节
• 工具自由：支持 20+ AI 编码助手（如 Claude Code、Cursor、Windsurf 等）
• 可预测性：标准化文档模板，减少返工
• 组织有序：每个变更独立文件夹，便于管理与追溯

项目地址：gitcn.org/projects/10…

---

四、不用 spec 与用 OpenSpec 的对比

维度	无规范	有 OpenSpec
Token 消耗	多次返工，额外提示消耗高	标准模板+上下文注入，降低 30%–50%
编码效果	风格不一、逻辑混乱、难维护	风格统一、Bug 率降低、维护便捷
开发效率	反复沟通，效率低	输出精准，效率提升 ≥ 40%
团队协作	沟通成本高，新人难上手	模板+流程，新人快速入门
可维护性	代码意图不明，维护困难	规范文档留档，意图清晰

---

五、快速开始

5.1 安装要求

系统要求：Node.js 20.19.0+

# 全局安装
npm install -g @fission-ai/openspec@latest

# 或使用 pnpm / yarn / bun
pnpm add -g @fission-ai/openspec
yarn global add @fission-ai/openspec
bun install -g @fission-ai/openspec

5.2 初始化项目

# 进入项目目录
cd your-project

# 初始化 OpenSpec
openspec init

示例交互（向 AI 请求 config.yaml）：

我是项目新手，请帮我写 @openspec/config.yaml 一份标准可直接使用的配置文件。
项目说明：

• 类型：ELN/FCM 设备数据采集程序
• 语言：C#
• 内容：多设备通信、数据采集、协议解析、日志、配置、调试
  要求：YAML 语法正确、有中文注释、包含项目元信息、模块划分、阶段管理、文档归档、任务管理、AI 辅助……

5.3 配置工作流

默认模式（Core Profile）：4 个核心命令

命令	说明
/opsx:propose	创建变更提案
/opsx:explore	探索方案
/opsx:apply	实现任务
/opsx:archive	归档变更

扩展模式（Expanded Profile）：更多命令

# 切换到扩展模式
openspec config profile expanded
openspec update

---

六、OPSX 工作流详解

6.1 核心理念

以"行动"为中心，文档赋能但非强制，支持随时创建、实现、更新、归档。

6.2 核心工作流（Core Profile）

步骤 1：探索想法（可选）

/opsx:explore 如何为移动应用处理认证

步骤 2：创建变更

/opsx:propose add-dark-mode

自动生成文件结构：

openspec/changes/add-dark-mode/
├── proposal.md
├── specs/
├── design.md
└── tasks.md

步骤 3：实现任务

/opsx:apply

步骤 4：归档

/opsx:archive

6.3 扩展工作流（Expanded Profile）关键操作

命令	说明
/opsx:new [change-name]	创建变更脚手架
/opsx:continue	逐个生成文档
/opsx:ff	快速推进
/opsx:verify	验证实现符合规范
/opsx:sync	同步状态
/opsx:bulk-archive	批量归档
/opsx:onboard	新成员引导

---

七、项目配置

7.1 配置文件（openspec/config.yaml）示例

# openspec/config.yaml
context: |
  团队：后端组
  代码审查：至少 2 人批准
  部署：自动 CI/CD
  监控：Datadog 告警

rules:
  proposal:
    - 包含产品负责人批准
    - 识别依赖团队
  design:
    - 架构审查会议记录
    - 性能基准测试计划

---

八、文档模板参考

8.1 变更提案（proposal.md）

# 变更提案：{功能名称}

## 问题陈述
描述当前存在的问题或需求背景。

## 目标
明确变更要达成的目标（可衡量）。

## 范围
- 包含：需要实现的功能点
- 不包含：明确排除的内容

## 风险与回滚计划
- 潜在风险：列举可能的风险
- 回滚计划：风险发生时的回滚方案

8.2 需求规范（specs/）

• 场景描述、验收标准
• 推荐使用 Given/When/Then 格式

8.3 设计文档（design.md）

• 架构设计
• 接口定义
• 数据设计
• 安全与性能

8.4 实现任务（tasks.md）

# 实现任务：{功能名称}

## 任务列表

### 任务 1：组件开发
- [ ] 1.1 创建主题上下文提供者
  - 文件：src/context/ThemeContext.tsx
  - 测试：src/context/ThemeContext.test.tsx

## 完成标准
- [ ] 所有任务完成
- [ ] 测试通过
- [ ] 代码审查通过

---

九、命令参考

9.1 Core Profile

命令	说明
/opsx:propose [change-name]	创建变更提案
/opsx:explore [topic]	探索方案
/opsx:apply	实现当前任务
/opsx:archive	归档已完成变更

9.2 Expanded Profile

命令	说明
/opsx:new [change-name]	创建变更脚手架
/opsx:continue	继续生成文档
/opsx:ff	快速推进
/opsx:verify	验证实现
/opsx:sync	同步状态
/opsx:bulk-archive	批量归档
/opsx:onboard	新成员引导

---

十、最佳实践

10.1 文档编写

• 注入项目上下文，保持简洁
• AI 初稿后人工审查
• 使用 Given/When/Then 编写场景
• 功能完成后及时归档

10.2 工作流选择

场景	推荐模式
小型 / 个人项目	Core Profile
大型 / 团队协作	Expanded Profile

10.3 模型选择

推荐使用高推理能力模型：

• Claude Opus 4.5
• GPT-5.2

---

十一、团队协作

11.1 团队流程

产品经理 → 提案 → 技术负责人审查 → 开发实现 → 测试验证 → 归档

11.2 审查清单

提案审查：

• 问题陈述清晰
• 目标可衡量
• 范围明确
• 风险与回滚方案完整

设计审查：

• 架构合理
• 接口定义清晰
• 安全考虑充分
• 性能目标明确

---

十二、与 AI 工具集成

12.1 支持工具

支持 20+ 编码助手，包括：Claude Code、Cursor、Windsurf、Codex 等。

12.2 技能文件示例

---
name: openspec-propose
description: Create a new OpenSpec change proposal
---
# OpenSpec Propose Skill
# ... 技能内容

12.3 提示词技巧

类型	示例
好	"基于 openspec/config.yaml 的上下文，为用户认证模块添加 JWT 刷新令牌支持"
差	"添加登录功能"

---

十三、更新与维护

13.1 更新 OpenSpec

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

13.2 版本兼容

版本	要求
v1.x	Node.js 20.19.0+
v2.x	OPSX 工作流

13.3 退出遥测

export OPENSPEC_TELEMETRY=0
export DO_NOT_TRACK=1

---

十四、故障排查

14.1 常见问题

问题	解决方案
技能未被检测	运行 openspec update
命令不工作	检查版本并重新安装
配置不生效	确保文件路径为 openspec/config.yaml

14.2 性能优化（大项目）

openspec sync --incremental
openspec bulk-archive --before 2026-01-01

---

十五、总结

15.1 核心价值

• 可预测性：规范驱动，减少 AI 输出偏差
• 组织性：每个变更独立管理，清晰可追溯
• 灵活性：无强制流程，按需使用
• 工具自由：支持主流 AI 编码助手
• 轻量级：学习成本低，快速上手

15.2 适用场景

适用	不适用
新功能开发	简单 Bug 修复
重构	快速原型
复杂 Bug 修复	纯探索性开发
团队协作	—

15.3 快速上手步骤

# 1. 安装
npm install -g @fission-ai/openspec

# 2. 初始化
openspec init

# 3. 创建第一个变更
/opsx:propose your-feature

加入社区：discord.gg/YctCnvvshC

---

参考资料

资源	链接
OpenSpec GitHub	github.com/Fission-AI/…
官方文档	github.com/Fission-AI/…
npm 包	www.npmjs.com/package/@fi…
Discord 社区	discord.gg/YctCnvvshC
X/Twitter	x.com/0xTab

---

本文基于 OpenSpec v2.x 编写，功能与命令可能随版本更新而变化，请参考官方文档获取最新信息。