OpenSpec：让 AI 编码助手从"乱猜"到"照单执行"
元信息
- 来源：腾讯云开发者社区
- URL：https://cloud.tencent.cn/developer/article/2651304
- 采集时间：2026-04-19
- 分类：开发工具 / AI 编程
核心概念
什么是 OpenSpec？
OpenSpec 是一个轻量级、开源的**规格驱动开发（Spec-Driven Development, SDD）**框架，通过结构化的 Markdown 文件帮助人类和 AI 编码助手在写代码之前就达成一致。
解决的核心问题
- 上下文丢失：AI 的记忆是会话级别的，新开对话就忘记之前的架构决策
- 需求漂移：没有明确规格约束，AI 容易过度实现或欠拟合
- 不可追溯：代码里看不出当初做决策的理由
- 协作成本高：团队成员告诉 AI 的上下文不一致
核心思想
把"我们要做什么、为什么做、怎么做"写成结构化的 Markdown 文件，和代码一起存进 Git 仓库。AI 助手从仓库读取持久化的规格文档，然后照单执行。
文件结构
your-project/
├── AGENTS.md ← AI 助手的项目说明书
└── openspec/
├── changes/ ← 进行中的变更（待办队列）
│ └── add-dark-mode/ ← 一个变更对应一个文件夹
│ ├── proposal.md ← 变更说明（为什么做，做什么）
│ ├── specs/ ← 需求规格（Given/When/Then 场景）
│ ├── design.md ← 技术设计（怎么做）
│ └── tasks.md ← 任务清单（AI 执行步骤）
├── archive/ ← 已完成的变更归档
└── specs/ ← 主规格文档（持续更新的"活文档"）
三阶段工作流
阶段一：规划（Propose）
- 定义变更 → 写提案 → 梳理规格 → 技术设计 → 任务拆分
- 命令：
/opsx:new <name>或/opsx:ff（快进生成全部文档）
阶段二：实现（Apply）
- AI 读取规格文档 → 按 tasks.md 逐步实现 → 打勾确认
- 命令：
/opsx:apply
阶段三：归档（Archive）
- 变更文件夹移入 archive/ → 规格合并到主 specs/ → 开启下一个变更
- 命令：
/opsx:archive
核心文档说明
proposal.md
回答四个问题：
- 问题是什么？
- 解决方案是什么？
- 做什么/不做什么？（In Scope / Out of Scope）
- 风险是什么？
specs/
使用 Given/When/Then 格式写清楚验收条件：
## Scenario: 用户切换到深色模式
Given 用户在浅色模式下
When 用户点击主题切换按钮
Then 页面立即切换为深色配色方案
And 用户的选择被保存到 localStorage
design.md
技术方案文档：怎么做，用什么技术，关键决策是什么
tasks.md
AI 实现时的步骤清单，打勾制度，做一步标一步：
## Phase 1: Theme Infrastructure
- [ ] 1.1 创建 ThemeContext 和 ThemeProvider
- [ ] 1.2 创建 useTheme() Hook
- [ ] 1.3 添加 localStorage 持久化逻辑
安装方式
方式一：使用 Vercel Skills 工具（推荐）
# 安装全套 OpenSpec 技能
npx skills add partme-ai/openspec-skills
# 指定安装到特定 AI 工具
npx skills add partme-ai/openspec-skills --agent cursor
npx skills add partme-ai/openspec-skills --agent claude-code
方式二：直接安装 CLI 工具
# 需要 Node.js 20.19.0 或更高版本
npm install -g @fission-ai/openspec@latest
# 验证安装
openspec --version
核心命令速查
| 命令 | 功能 |
|---|---|
openspec init |
在当前项目初始化 OpenSpec |
/opsx:new <name> |
创建新变更 |
/opsx:ff |
快进：一键生成所有规划文档 |
/opsx:continue |
生成下一个规划文档（分步模式） |
/opsx:apply |
执行 tasks.md 中的所有任务 |
/opsx:archive |
归档已完成的变更 |
/opsx:verify |
验证实现是否符合规格 |
openspec validate |
校验规格文档完整性 |
最佳实践
✅ 变更名称要小而精确
- 好：
add-oauth-token-refresh、fix-login-redirect-loop - 差：
stuff、updates、wip
✅ 提案要能在 2 分钟内读完
快速对齐，回答四个核心问题即可
✅ specs 写场景，不写感觉
- ❌ 差：主题切换应该流畅、好用
- ✅ 好：页面在 200ms 内完成主题切换，无明显闪烁
✅ 任务要小，小到可以独立验证
细粒度的任务让 AI 的每一步都可验证
✅ 规划稳定后再开始实现
在执行 /opsx:apply 之前，读一遍文档，改掉不对的地方
✅ 规划和实现分开对话
长对话会积累噪音，新开对话上下文更干净
✅ 做完就归档，保持队列整洁
openspec/changes/ 应该只有当前正在做的工作
常见误区
❌ 误区一：OpenSpec 只适合新项目
真相：专门为存量项目设计，openspec init 不会碰现有代码
❌ 误区二：有了 OpenSpec 就不用思考了
真相：OpenSpec 把"思考"前置了，不是消除了。/opsx:ff 生成的是草稿，需要人工审核
❌ 误区三：一个变更做所有事
正确做法：单次变更控制在 1-3 天的工作量内
❌ 误区四：归档前不用测试
正确做法：先测试、先合并代码，确认没问题再归档
❌ 误区五：把 OpenSpec 当成文档工具
真相：OpenSpec 文件是活的执行规格，用于引导 AI 实现，不是事后补的文档
支持的 AI 工具
支持 20+ AI 编码助手：
- Cursor
- Claude Code
- GitHub Copilot
- Windsurf
- RooCode
- Cline
- Amazon Q
- Codex
- Gemini CLI
- 等等...
通过统一的斜杠命令（/opsx:*）触发相同的工作流，团队协作无缝衔接。
与其他工具对比
| 工具 | 定位 | 复杂度 | 工具绑定 |
|---|---|---|---|
| OpenSpec | 轻量 SDD 框架 | ⭐⭐ | 否，20+ 工具通用 |
| BMAD | 多 Agent 协作系统 | ⭐⭐⭐⭐⭐ | 否 |
| Spec Kit | 重型规格管理 | ⭐⭐⭐⭐ | 否 |
| Kiro (AWS) | AI IDE 原生 SDD | ⭐⭐⭐ | 是（绑定 Kiro IDE 和 Claude） |
| 只写 Prompt | 无框架 | ⭐ | 否 |
OpenSpec 的甜蜜点：够轻、够灵活、够通用。
核心价值
- 对人类：规格即文档，一目了然知道在做什么、做了什么
- 对 AI：有明确的输入（spec）和输出（tasks），照单执行而不是自由发挥
- 对团队：规格活在仓库里，人人可见，协作摩擦大幅降低
有用的链接
- 官网：https://openspec.pro/
- GitHub：https://github.com/Fission-AI/OpenSpec
- Skills 生态：https://skills.sh/
- Discord 社区：https://discord.gg/openspec
总结
OpenSpec 提供的是一套对人类友好、对 AI 友好、对团队友好的工作框架。它让 AI 编码助手从"聪明的随机数生成器"变成"可靠的工程师"。
核心理念：带着规格上路，比漫无目的地催 AI 要快得多、稳得多。