SillySpec

Appearance

OpenSpec 使用手册 ​

版本: Latest (2026-03 更新) GitHub: https://github.com/Fission-AI/OpenSpecStars: ~32.5K ⭐ NPM: @fission-ai/openspec 协议: MIT

一、简介 ​

OpenSpec 是一个轻量级的规范驱动开发（Spec-Driven Development, SDD）框架，专为 AI 编码助手设计。它的核心理念是：先让人类和 AI 对齐需求，再动手写代码。

哲学：

  • 流动不僵化（fluid not rigid）
  • 迭代不瀑布（iterative not waterfall）
  • 简单不复杂（easy not complex）
  • 适合改造项目（built for brownfield）
  • 从个人到企业可扩展（scalable）

二、核心概念 ​

OpenSpec 围绕 Change（变更）组织一切：

openspec/
├── changes/
│   ├── add-dark-mode/
│   │   ├── proposal.md    — 为什么要做、改什么
│   │   ├── specs/         — 需求和场景
│   │   ├── design.md      — 技术方案
│   │   └── tasks.md       — 实现清单
│   └── archive/           — 已完成的变更
└── config/                — 项目配置

三、安装 ​

bash
# 安装（需要 Node.js 20.19+）
npm install -g @fission-ai/openspec@latest

# 在项目中初始化
cd your-project
openspec init

四、核心工作流 ​

4.1 提出新功能（Propose） ​

/opsx:propose "给网站加个深色模式"

AI 自动生成完整的变更目录：

  • ✓ proposal.md — 为什么做、改什么
  • ✓ specs/ — 需求和场景
  • ✓ design.md — 技术方案
  • ✓ tasks.md — 实现清单

4.2 实现代码（Apply） ​

/opsx:apply

AI 按照 tasks.md 逐项实现：

  • ✓ 1.1 添加主题上下文
  • ✓ 1.2 创建切换组件
  • ✓ 2.1 添加 CSS 变量
  • ✓ 2.2 接入 localStorage

4.3 归档（Archive） ​

/opsx:archive

变更归档到 .sillyspec/changes/archive/2025-01-23-add-dark-mode/，规范沉淀到项目中。

4.4 验证（Verify） ​

/opsx:verify

验证实现是否符合规范。

五、高级工作流 ​

初始化时选择 expanded workflow：

bash
openspec config profile  # 选择 expanded profile
openspec update          # 应用

新增命令：

  • /opsx:new — 开始新变更
  • /opsx:continue — 继续未完成的变更
  • /opsx:ff — 快进到下一步
  • /opsx:sync — 同步规范状态
  • /opsx:bulk-archive — 批量归档
  • /opsx:onboard — 新成员入门引导

六、CLI 命令 ​

bash
openspec init          # 初始化项目
openspec update        # 更新 AI 指令和斜杠命令
openspec config        # 管理配置

七、支持的 AI 工具 ​

OpenSpec 支持 20+ AI 编码助手，包括：

  • Claude Code
  • GitHub Copilot
  • Cursor
  • Windsurf
  • Amp
  • Cline
  • Gemini CLI
  • Kilo Code
  • 以及更多...

八、增量修改支持（核心优势） ​

OpenSpec 特别擅长处理小改动，使用 delta 格式：

yaml
# 不需要重写整个规范
ADDED:
  - 新增的组件
MODIFIED:
  - 修改的样式
REMOVED:
  - 删除的功能

vs 其他工具处理小改动：

  • Spec-Kit：需要 /speckit.clarify workaround
  • Kiro/BMad：杀鸡用牛刀
  • OpenSpec：天然支持

九、仪表盘（Dashboard） ​

OpenSpec 提供实时仪表盘，跟踪规范驱动开发的进度。

十、多语言支持 ​

OpenSpec 支持多种编程语言的项目。

十一、隐私与遥测 ​

  • 仅收集命令名和版本号（匿名）
  • 不收集参数、路径、内容或个人信息
  • CI 环境自动禁用
  • 手动禁用：export OPENSPEC_TELEMETRY=0

十二、最佳实践 ​

  1. 模型选择：推荐 Opus 4.5 和 GPT 5.2
  2. 上下文管理：开始实现前清空上下文
  3. 小改动直接 PR：bug fix、typo 不需要走完整流程
  4. 大改动先 propose：新功能、重构先走规范流程
  5. 定期 update：openspec update 保持最新

十三、常见问题 ​

Q: OpenSpec 和 Superpowers 有冲突吗？ A: 没有，它们互补。OpenSpec 管需求规范，Superpowers 管工程流程。

Q: 已有项目能用吗？ A: 可以，OpenSpec 专门为 brownfield（现有项目）设计。

Q: 支持团队协作吗？ A: 支持，规范文件提交到 Git，团队成员可以 review 和同步。

十四、参考资料 ​

文档整理时间：2026-03-20 | 基于 OpenSpec 最新版