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

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

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

工作流一览

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

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

支持的 AI 工具

内置 slash command 的工具（部分）：Claude Code、Cursor、Windsurf、GitHub Copilot、Amazon Q、Gemini CLI、Codex、RooCode、Qoder 等。

不支持指令的工具也可通过 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 会自动生成对应的命令模板并写入 openspec/AGENTS.md。

3. 让 AI 生成首个变更

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

---

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