公司要求全面采用 Claude Code 与 Deepseek 进行 AI 辅助开发，起初团队还挺兴奋——开发效率确实有了肉眼可见的提升。
然而好景不长，一系列问题很快浮出水面。
第一个问题：团队成员使用 AI 编写代码的方式五花八门。
有人直接抛出需求让 AI 生成代码，有人先让 AI 输出方案再动手，还有人边写边改。最终代码风格难以统一，Code Review 时让人头疼，修改起来甚至不如自己重写来得高效。
第二个问题：AI 完全不了解项目历史背景。
每次开启新的对话，AI 就像个“失忆症”患者。它不清楚上周刚完成了哪些功能，不明白某个字段为何如此设计，时常在已有逻辑上叠加一堆相互冲突的代码。
第三个问题：需求尚未明确就匆忙编码，返工成了家常便饭。
AI 生成代码的速度太快了，快到方向还没完全想清楚，它已经帮你输出了一大堆。后续修改起来，比从头编写还要费劲。
直到团队接触了 OpenSpec，这几个核心痛点才算真正找到了解决方案。
OpenSpec 使用分享：从初始化到实战
一、什么是 OpenSpec
OpenSpec 是一套规范驱动开发（Spec-Driven Development）的工作流工具，核心理念非常明确：先想清楚，再动手。在编写代码之前，先把需求定义清楚、方案敲定、规范对齐。
它通过 4 个命令覆盖了从探索到归档的完整生命周期：
/openspec-explore→ 思考、探索，不动代码/openspec-propose→ 把想法固化成提案（包含方案、设计、任务）/openspec-apply→ 按任务列表实际写代码/openspec-archive→ 提案完成后归档
二、安装与初始化
2.1 安装 OpenSpec
OpenSpec 通过 npm 安装，提供了三种方式，可以根据实际场景灵活选择：
方式一：全局安装（推荐，所有项目都能用）
npm install -g @fission-ai/openspec@latest
openspec --version # 验证安装成功，查看版本号安装完成后，在任何项目中都能直接使用 OpenSpec 命令。
方式二：项目级安装（只在当前项目用）
npm install --save-dev @fission-ai/openspec适合多个项目使用不同版本 OpenSpec 的场景。
方式三：npx 直接运行（不用安装，临时用）
npx @fission-ai/openspec init适合偶尔使用，省去安装和卸载的麻烦。
2.2 项目初始化：openspec init
安装完成后，进入你的项目目录，执行初始化命令：
openspec init执行后会出现交互式引导，关键一步是选择你使用的 AI 编程工具，主流的工具基本都支持：
- Claude Code
- CodeBuddy
- Cursor
- Gemini
- ……
选择完成后，按提示重启 IDE，初始化即完成。之后就可以在编程工具中使用 /openspec-* 系列命令了。
2.3 目录结构
项目初始化后，根目录下会生成 openspec/ 目录：
openspec/
├── changes/ # 存放所有提案（change）
│ ├── archive/ # 已归档的提案（初始为空）
│ │ ├── 2026-05-24-gantt-show-all-users/
│ ├── async-export-task/ # 进行中的提案
│ │ ├── specs/ # 当前提案的规格说明
│ │ ├── .openspec.yaml # 提案的基本信息
│ │ ├── design.md # 设计：如何做？前后端各做什么？有什么风险？
│ │ ├── proposal.md # 方案：为什么做？具体需求是什么？可能影响的地方
│ │ └── task.md # 任务：转化为每一个可执行的最小化任务
│ └── specs/ # 规格文档
└── config.yaml # 项目全局配置2.4 接入开发规范：config.yaml
这一步是整个方案的核心所在，也是解决「AI 不遵守团队规范」问题的关键环节。
在 config.yaml 的 context 字段中声明开发规范文档路径，AI 在执行 propose 或 apply 时会自动读取并遵循这些规范：
值得一提的是，开发规范也可以让 AI 通读你现有的代码结构，自动生成对应的代码规范，从而保持开发风格统一。
# openspec/config.yaml
context:
前端规范: "core-file/vue-arc.md" # 前端 Vue 开发规范
后端规范: "core-file/java-arc.md" # 后端 Java 开发规范
project: "./project.md" # 项目提案记录配置完成后，每次执行 /openspec-propose 或 /openspec-apply，AI 都会自动读取这两份规范文档，确保生成的方案和代码始终符合项目既定标准。
2.5 初始化提案记录：project.md
project.md 是一个轻量的提案追踪文件，解决的核心问题正是「AI 失忆」。
它记录当前项目做过哪些设计提案、每个提案的状态：
| 目录 | 日期 | 状态 | 简要说明 |
|---|---|---|---|
| 任务甘特图视图 | 2025-xx-xx | 已完成 | 为任务模块增加甘特图展示 |
| 工时热力图 | 2025-xx-xx | 进行中 | …… |
变更记录表（可选）：
| 日期 | 提案名称 | 变更内容 |
|---|---|---|
| 2025-xx-xx | 任务甘特图视图 | 新增移动端适配需求 |
在 config.yaml 中声明 project.md 路径后，AI 每次操作提案时都会自动同步这个文件。
三、四个命令的完整工作流
/openspec-explore → /openspec-propose → /openspec-apply → /openspec-archive
思考与探索 → 固化提案 → 编码实现 → 归档清理
Phase 1：/openspec-explore —— 想清楚了再动手
这是整个工作流中最关键的环节，也是和「直接让 AI 写代码」最大的区别所在。
当你有一个模糊的需求想法但不确定具体方案时，先用 explore：
/openspec-explore 我想给任务模块加一个消息通知功能，但不确定推送方案怎么选它会做什么：
- 分析现有代码结构
- 画出不同方案的对比图
- 帮你梳理各方案的优劣
- 不修改任何代码文件
等思路成熟了，告诉它「好了，帮我生成提案」，它才会调用 propose 创建正式文档。
Phase 2：/openspec-propose —— 方案固化
将 explore 阶段的想法转化为正式提案文档，包含：
- Proposal：方案描述和技术决策
- Design：说明如何实现方案
- Tasks：拆解后的具体任务清单
- Specs：涉及的接口/数据结构等技术规格
你要做的，就是审核方案内容是否正确，确认无误后再执行。
Phase 3：/openspec-apply —— 按计划编码
根据 proposal 中的任务列表逐项实现代码。这个时候 AI 会：
- 读取 config.yaml 中声明的开发规范
- 参考 project.md 了解已有提案，避免冲突
- 按任务顺序逐一编写代码
Phase 4：/openspec-archive —— 收尾归档
提案全部任务完成后执行归档：
- 标记提案状态为已完成
- 同步更新 project.md 记录
- 清理临时文件，保持工作区整洁
四、实战注意事项
4.1 规范先行，编码在后
不要跳过 config.yaml 的 context 配置。把开发规范接进去看似多了一步，但它能避免后续大量返工。这是保证 AI 生成代码质量最简单有效的方式。
4.2 project.md 是团队的「共享记忆」
即使只有一个人开发，project.md 也很有价值：
- 快速回顾「这个功能之前做过吗？」
- 避免重复提案
- 方便新人了解项目演进历史
保持它的简洁性——一张表格就够，不需要复杂格式。
4.3 充分利用 explore，别急着写代码
OpenSpec 最大的价值不在自动生成代码，而在 explore 阶段的强制思考。很多 bug 和返工本质上是因为「没想清楚就开始写了」。给 explore 阶段留足时间，让它帮你画对比图、分析现有代码、理清思路，这笔时间投入会在后面连本带利地省回来。
4.4 变更要留痕
当提案在执行过程中发生范围变更或任务调整时，及时在 project.md 的变更记录表中追加一行。复盘时能清楚理解「为什么最终做出来的和最初想的不一样」。
总结
用了 OpenSpec 之后，团队 AI 开发最明显的变化是：
- AI 不再乱跑了：每次操作都有规范约束，代码风格统一了
- 不再重复踩坑：project.md 让 AI 有了「项目记忆」
- 返工少了很多：explore 阶段把方向想清楚再动手，比「写了再改」省时间
如果你的团队也在用 AI 辅助开发，遇到类似的问题，不妨试试这套工作流。
