1. 前言
OpenSpec 是一种**规范驱动（spec‑driven）**的开源开发框架，主要面向 AI 编程助手（如 Claude Code、GitHub Copilot、Cursor 等）而设计。它通过在「共识规范 → AI 执行 → 自动验证」的闭环流程，帮助团队在 AI 参与的代码开发过程中明确需求、降低指令歧义、提升代码可追溯性与可维护性。
核心理念与工作流
- 共识规范（Spec）
- 先由人类与 AI 共同撰写结构化的需求规范（包括功能描述、输入/输出、边界条件、测试用例等）。
- AI 执行
- AI 根据规范自动生成代码、文档或变更提案。
- 自动验证
- 框架内置的验证器会依据规范中的测试用例对生成的代码进行自动化检查，确保实现符合预期。
- 迭代与归档
- 通过审查、计划、实现、归档等步骤形成完整的变更历史，便于后续审计与迭代。
适用场景
- 新项目
- 功能增强（迭代项目）
- 多人协作
该项目最有价值的场景是功能增强和多人协助开发，尤其是大型项目很多都是基于原有项目扩展和改造。之前由于模型上下文的问题导致很多企业级项目以及一些老旧项目升级改造 AI 就变得难以搞定。另外 AI 开发的项目多人协作也是比较难搞定的。这个项目刚好解决这两个问题。
2. 项目实战
被修改项目下载
我们先下载一个开源项目，下面拿 jimeng-free-api-all 项目作为案例介绍。
使用 git clone 这个项目：
git clone https://github.com/zhizinan1997/jimeng-free-api-all
完成代码下载后，使用 VSCode 打开这个项目。
安装 OpenSpec
我们在终端命令行输入下面命令安装 OpenSpec：
npm install -g @fission-ai/openspec@latest
输入下面命令确保安装成功：
openspec --version
如果安装失败出现错误（一般是 Windows 环境），可以切换使用 pnpm 命令安装：
pnpm install -g @fission-ai/openspec@latest
按上述方式确保 OpenSpec 安装完成。
openspec init
这个目的主要是在项目中创建一个新的 openspec/ 目录结构，方便后面基于此来控制项目。
openspec init
OpenSpec 支持多种开发工具，这里使用 Claude Code。
这个文件夹主要有以下几个文件和内容：
openspec/
├── specs/ # 规范目录（存放各类正式规范文档）
│ └── auth/ # 认证相关规范子目录
│ └── spec.md # 当前认证规范文档（若存在）
└── changes/ # 变更目录（存放规范的修改提案与增量内容）
└── add-2fa/ # 新增双因素认证（2FA）的变更子目录（由 AI 创建完整结构）
├── proposal.md # 变更提案文档（说明为何修改、修改内容）
├── tasks.md # 实施任务清单（记录需完成的具体开发/修改任务）
├── design.md # 技术设计文档（技术方案决策，可选）
└── specs/ # 变更对应的规范增量目录
└── auth/ # 变更涉及的认证规范子目录
└── spec.md # 规范增量文档（仅展示新增/修改的内容，即差异部分）