OpenSpec：让 AI 编码回归规格驱动

当我们用 AI 助手写代码时，需求常常只存在于对话里，结果是“写完才发现不对”。OpenSpec 通过一套轻量、可审计的规格驱动流程，把“先对齐、再编码”变成标准动作，不需要 API Key，也不强绑特定工具。

核心理念：把意图锁定在规格里

分层管理：1 openspec/specs/ 是当前生效的规格；1 openspec/changes/ 存放提案与任务，批准后再归档回 specs。
双向对齐：人类和 AI 先讨论、修改提案，确认 scope 后再让 AI 执行对应任务。
透明可追溯：每个变更都有提案、任务、规格差异，方便审查和复盘。

工作流一览

草拟提案 → 评审&对齐 → 执行任务 → 归档并更新规格

Proposal：描述要改动的功能/行为，以及预期的规格变更。
Tasks：可执行的工作清单，指向已对齐的规格。
Archive：完成后归档，自动把通过的 delta 合并到 1 openspec/specs/。

支持的 AI 工具

内置 slash command 的工具（选段）：Claude Code、Cursor、Windsurf、GitHub Copilot、Amazon Q、Gemini CLI、Codex、RooCode、Qoder 等。
不支持指令的工具也能通过

1	openspec/AGENTS.md

获取规则，手动让模型遵循该流程即可。

快速上手

1) 安装 CLI（需 Node.js ≥ 20.19）

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

2) 初始化项目

cd your-project
openspec init

选择正在使用的 AI 工具，OpenSpec 会自动生成对应的命令模板并写入 1 openspec/AGENTS.md。
3) 让 AI 生成首个变更

在支持 slash command 的工具中输入

1
/openspec:proposal add-profile-filters

或直接对模型说：“用 OpenSpec 创建 add-profile-filters 提案并生成 tasks、spec delta” 4) 在本地检查与评审

openspec list                   # 查看现有变更
openspec show add-profile-filters
openspec validate add-profile-filters

5) 让 AI 按任务执行，完成后归档

openspec archive add-profile-filters --yes

目录结构示例

openspec/
├─ AGENTS.md          # 给所有 AI 助手的统一指引
├─ project.md         # 项目约定、架构、技术栈
├─ specs/             # 当前生效的规格
└─ changes/
   └─ add-profile-filters/
      ├─ proposal.md  # 需求与变更意图
      ├─ tasks.md     # 执行清单
      └─ specs/       # 与源规格的差异（delta）

适用场景

存量项目迭代：已上线系统做 1→n 变更时，保持行为差异的可控与可审计。
多助手/多人协作：统一的 AGENTS.md 和变更文件夹避免信息碎片化。
安全或合规要求高：把“意图—实现—归档”链路留档，满足审计需求。

使用心得与提示

让 AI 先读 1 openspec/project.md 和相关 specs，再写 proposal，减少反复。
在提案阶段就要求 AI 写出规格 delta（对比现有行为），方便评审。
归档前跑 1 openspec validate，确保格式和引用无误。
若编辑器的 slash command 未出现，重启即可加载生成的命令文件。

OpenSpec 不替代你的框架或测试体系，而是用“先规格、后编码”的最小闭环，把 AI 助手纳入同一套工程化流程，让需求对齐、范围控制和可追溯性变得简单。当前工具链已覆盖主流 AI IDE/CLI，值得在团队中尝试落地。