OpenSpec 在目前的开发语境中通常指代 Fission-AI 推出的一款面向 AI 编程助手（如 Cursor、Claude Code、GitHub Copilot）的规范驱动开发（Spec-Driven Development, SDD）工具。
什么是 OpenSpec？
OpenSpec 是一个轻量级的开源命令行工具（CLI）和工作流规范。它充当了你（人类）和AI 编程助手之间的翻译官和契约。
OpenSpec的核心目的是解决 AI 编程时随意发挥或听不懂人话的问题，通过强制先写规格说明书（Spec）再写代码，让 AI 的输出更加可控、精准。
- 痛点：通常我们直接让 AI “加一个登录功能”，AI 可能会写出不符合项目结构、遗漏边界条件的代码（所谓的 “Vibe Coding”）。
- 解决方案：OpenSpec 强制要求在写代码前，先生成一份结构化的提案（Proposal）和任务清单（Tasks）。你确认无误后，AI 才会根据这份
契约去写代码。
- 适用工具：Cursor, Claude Code, Windsurf, GitHub Copilot 等。
核心工作流 (The Workflow)
OpenSpec 的使用主要围绕三个核心命令（或步骤）进行，形成闭环：
- Proposal (提案)：告诉 AI 你想做什么，让它先写计划。
- Apply (执行)：让 AI 根据计划写代码。
- Archive (归档)：功能完成后，将这次变更的规格归档，成为项目永久文档的一部分。
如何安装和初始化
安装
OpenSpec 是一个 Node.js 工具，可以直接通过 npm 安装：
npm install -g @fission-ai/openspec
初始化项目
在你的项目根目录下运行：
这会生成一个 .openspec/ 或 openspec/ 目录，里面包含：
project.md：项目的全局上下文（技术栈、代码规范、架构原则）。这是最重要的文件，你需要根据项目实际情况修改它，AI 会依据它来工作。AGENTS.md：给 AI 看的指令集，教它如何遵守 OpenSpec 的规则。
具体使用步骤演示
假设你要在一个 React 项目中添加黑暗模式。
第一步：提出提案 (Proposal)
在 Cursor 或 Claude Code 的对话框中，输入类似以下的指令（如果你配置了 Slash Command）：
“我想添加黑暗模式支持，请创建一个 OpenSpec proposal。”
或者在终端运行 openspec proposal。
AI 会生成以下 Markdown 文件（通常在 openspec/changes/ 目录下）：
proposal.md: 描述为什么要改，改什么。design.md: 详细的设计思路（比如使用 Context API 还是 CSS 变量）。tasks.md: 一步步的执行清单（TODO List）。specs/: 具体的规格变更（新增了什么需求，修改了什么逻辑）。
你的工作：阅读这些文件。如果 AI 的设计不对（比如你想用 Tailwind 但它设计的是原生 CSS），现在就让它改文档，而不是等它写完代码再改。
第二步：执行代码 (Apply)
当你对 Proposal 满意后，告诉 AI：
“Proposal 看起来不错，请执行 Apply。”
或者运行相关命令。AI 会读取 tasks.md，一项一项地去修改项目源码。因为它已经有了详细的设计文档，写出的代码通常准确率极高。
第三步：归档 (Archive)
代码写完并通过测试后，你需要告诉 AI：
“功能已完成，请 Archive。”
OpenSpec 会将这次变更的规格（Spec）合并到项目的主规格文档中，并清空临时的变更文件夹。这样，你的项目不仅有了代码，还有了一份始终与代码同步的最新技术文档。
示例目录
openspec/
├── specs/
│ └── auth/
│ └── spec.md # 当前认证规范（如果存在）
└── changes/
└── add-2fa/ # AI创建整个结构
├── proposal.md # 为什么和什么变更
├── tasks.md # 实施清单
├── design.md # 技术决策（可选）
└── specs/
└── auth/
└── spec.md # 显示添加内容的增量
为什么要用它？
- 不再
抽卡：AI 不会随机生成代码，而是严格遵循设计文档。
- 上下文记忆：传统的 AI 聊天记录一多就会遗忘之前的要求。OpenSpec 把要求固化在 Markdown 文件里，AI 随时可以查阅。
- 自动维护文档：开发过程就是写文档的过程，项目永远有一份最新的
project.md 和规格说明。
- 无 API Key：它主要是一个本地的规范和文件结构，不依赖特定的昂贵云服务（使用你原本的 AI 订阅即可）。
总结
如果你经常觉得 AI 编程助手写出来的代码不能用或者逻辑混乱，OpenSpec 就是为了解决这个问题而生的。它用**先思考，后行动**的策略，强迫 AI 变得更加严谨和工程化。