OpenSpec 规范驱动 AI 编码工作流

OpenSpec 是 Fission-AI 出的开源规范驱动开发框架，配套 AI 编码 Agent（Claude Code、Cursor、Codex 等），用 /opsx:propose、/opsx:apply、/opsx:archive 等命令把"想法→提案→设计→任务→实施→归档"做成可追踪的工作流。设计哲学是"流动而非僵化、迭代而非瀑布、为棕地与绿地皆可用、从个人项目到企业可扩展"。

Skill Documentation

摘要

OpenSpec（Fission-AI/OpenSpec）是开源的规范驱动开发框架，与 Claude Code / Cursor / Codex 等 AI 编码 Agent 配套。它通过 `/opsx:propose` / `/opsx:apply` / `/opsx:archive` 等命令把"想法 → 提案 → 设计 → 任务 → 实施 → 归档"做成可追踪的工作流，每一步产出可审阅的 markdown。设计哲学是"流动而非僵化、迭代而非瀑布、为棕地与绿地皆可用、从个人项目到企业可扩展"。GitHub Trending 在 2026 年 9 月 +298 颗星，是 Agentic Engineering 时代的"左半边规划"工具。

SEO 关键词分布

OpenSpec 关键词自然分布：规范驱动开发 SDD、Fission-AI、OpenSpec workflow、artifact-guided、proposal design tasks、棕地重构、AI 编码工作流、Claude Code 集成、Cursor 集成、Codex 集成、Slash 命令、AI Agent 编排。H2/H3 段落分别承担"是什么 / 怎么用 / 何时用"三类查询意图。

是什么 / 解决什么问题

OpenSpec 是规范驱动开发的"工作流底座"。它把 SDD 从"开工前的脚手架"反向变成"可执行的规格"，生成 spec / design / plan 三类文档，由 Agent 按规格推进。它的设计哲学是"fluid not rigid / iterative not waterfall / easy not complex / built for brownfield not just greenfield / scalable from personal projects to enterprises"——Agent 可以边做边改规格，因为适应变化极便宜，价值从"锁死形态"转向"随需演进"。

安装与验证

第一步：环境准备。Node.js 20+ 用于 npx 安装，已有 AI 编码 Agent（Claude Code / Cursor / Codex / Antigravity 等任一）。

第二步：装到项目。

# 一次性安装（项目级）
npx install @fission-ai/openspec
# 或全用户级（推荐）
npm install -g @fission-ai/openspec

第三步：初始化项目。

cd your-project
openspec init
# 按提示选集成 Agent（Claude Code / Cursor / Codex / Antigravity）
# 生成 openspec/changes/ 和 openspec/specs/ 目录结构

第四步：第一次跑通。

# 在 Agent 会话里：
/opsx:explore "我想加 dark mode 但不确定怎么做"
/opsx:propose add-dark-mode

验证标准：第一次 `/opsx:propose` 应在 30 秒内生成 `openspec/changes/add-dark-mode/{proposal.md,design.md,tasks.md,specs/}` 四个文件。

三种典型场景 + 命令样例

**场景 A：棕地项目加新功能**。接手 6 个月的 React 老项目，想加 dark mode 但怕破坏现有代码。

You: /opsx:explore
AI:  What would you like to explore?
You: I want dark mode but I'm not sure how to do it cleanly.
AI:  Let me look at your styling setup...
     Cleanest path here: CSS variables + a small theme context,
     with system-preference detection. No new dependencies.
You: Yes, let's do it.

You: /opsx:propose add-dark-mode
AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ design.md — how we'll implement it
     ✓ tasks.md — concrete steps to ship it
     ✓ specs/dark-mode.md — the resulting spec

**场景 B：跨职能项目多人协作**。产品 / 后端 / 前端 / QA 各管一段，每个变更的 spec / design / tasks 是单一来源。

/opsx:propose upgrade-payment-api
/opsx:apply  # Agent 按 tasks.md 推进，自动写代码 + 测试
/opsx:archive  # 完成后归档到 openspec/specs/，新人可追溯历史决策

**场景 C：技术选型评估**。新库选 React vs Vue，先写规格让 Agent 比对，再决定。

You: /opsx:explore "should we adopt Vue 3?"
AI:  Let me look at the codebase to see what fits best...
You: /opsx:propose evaluate-vue3-adoption

FAQ

OpenSpec 和 Spec Kit、planning-with-files 的区别?

Spec Kit（GitHub 官方）是 SDD 早期实现，命令 `specify init` + `specify`；planning-with-files 是更轻量的 4 个 planning 文件驱动。OpenSpec 在它们基础上做了三件事：(1) artifact-guided workflow（proposal/design/tasks/specs 各一份 markdown）；(2) 棕地优先——既存代码也能加 OpenSpec 流程；(3) `/opsx:propose "your idea"` 一句启动，与 Claude/Cursor/Codex 集成顺滑。

OpenSpec 会让 Agent 变慢吗?

不会。它的工作流是"对话时轻量引导"+"归档时一份 markdown"，不是"每次跑前都跑完整 5 阶段审批"。你用 `/opsx:propose` 启动一个变更，Agent 一次性生成 4 个 markdown；用 `/opsx:apply` 按 tasks 推进；中间任何修改都可以走 `/opsx:revise`。

它能跟现有 Git 工作流集成吗?

能。OpenSpec 不绑定 git，但强烈建议把 `openspec/` 目录 commit 到仓库。每次 `/opsx:archive` 后产生的 spec 历史就是项目的"组织记忆"，新人 onboarding 看 git log + openspec/specs/ 即可理解历史决策。

适合谁 + 故障排除

适合：(a) 接手 / 重构老项目的工程师；(b) 多人协作想让决策可追溯的团队；(c) 想从 vibe coding 升级到 intent-captured workflow 的个人；(d) 把 AI Agent 用于企业级项目、需要治理与审计的组织。

故障排除：

1. **`/opsx:propose` 输出文件不完整**：确认 Agent 加载了 OpenSpec skill（重启 Agent 会话），或 `openspec init` 时选择了对应 Agent 集成。

2. **tasks.md 与实际工作脱节**：用 `/opsx:revise` 更新规格再继续，不要直接改代码绕开规格。

3. **归档后还想修改**：用 `/opsx:revive` 重新激活已归档的 change，进入新一轮 propose / apply。

4. **多 Agent 并行冲突**：OpenSpec 默认按 change 串行；并行需手动锁定 `openspec/changes/<name>/.lock`。

5. **Windows 长路径报错**：启用 Win32 长路径支持（`fsutil` 改 LongPathsEnabled），或用 WSL。

MIT 协议，Discord 活跃（`discord.gg/YctCnvvshC`），作者 @0xTab 在 X 跟进 issue。

模型对照说明

> **michael 用户告知**: 本 Skill 在 AIMS 平台使用平台已支持的真实大模型（与原 README 推荐对照）

| 项 | 说明 |

|---|---|

| **原仓库 README 推荐** | Claude Code / Cursor / GitHub Copilot |

| **AIMS 平台实际使用** | **`gpt-4.1`** |

| **AIMS 平台可用替代** | gpt-5.1-codex / claude-sonnet-4.6 / claude-opus-4.7 |

| **对齐度** | 中等一致 (README 推 Claude；AIMS 用 gpt-4.1 因工程导向) |

AIMS 平台已支持的国外大模型清单（按短 id 列出，本 Skill 调用时可用）

• **OpenAI 系列**: gpt-5.6 / gpt-5.5 / gpt-5.4-pro / gpt-5.1 / gpt-5 / gpt-4.1 / gpt-4o / gpt-4o-mini / gpt-3.5-turbo / gpt-oss-120b / gpt-latest / o1 / o3-pro / o4-mini
• **Anthropic 系列**: claude-opus-5 / claude-opus-4.8 / claude-opus-4.7 / claude-opus-4.6 / claude-opus-4.5 / claude-opus-4.1 / claude-sonnet-5 / claude-sonnet-4.6 / claude-sonnet-4.5 / claude-haiku-4.5 / claude-3-haiku / claude-fable-5
• **Google 系列**: gemini-3.5-flash / gemini-3.1-pro-preview / gemini-2.5-pro / gemini-2.5-flash / gemini-2.5-flash-lite / gemma-4-31b-it / gemma-3-27b-it / gemma-3-12b-it
• **Meta 系列**: llama-4-maverick / llama-4-scout / llama-3.3-70b-instruct / llama-3.1-70b-instruct / llama-3.2-1b-instruct
• **Mistral 系列**: mistral-large-2512 / mistral-medium-3.5 / mistral-small-3.2-24b-instruct / codestral-2508

AIMS 平台已支持的国内大模型清单（按短 id）

• **MiniMax 系列**: MiniMax-m3 / MiniMax-m2.7 / MiniMax-m2.5 / MiniMax-m2 / MiniMax-m1 / MiniMax-speech-02-hd
• **Qwen 系列**: qwen3-max / qwen3-vl-plus / qwen-max / qwen-plus / qwen-turbo / qwen-vl-max / qwen-coder-plus / qwen-deep-research-2025-12-15 / qwen-flash / qwen-long
• **DeepSeek 系列**: deepseek-r1-distill-llama-70b / deepseek-r1-distill-llama-8b / deepseek-r1-distill-qwen-32b / deepseek-r1-distill-qwen-14b / deepseek-r1-distill-qwen-7b / deepseek-r1-distill-qwen-1.5b

> 💡 **如何切换模型**: 使用 AIMS `aims.update_skill` 传 `skill_id + model_name + call_price_fen` 即可在上述任意支持的模型间切换（短 id 直接传，无需前缀）。