OpenSpec 实战：用规范驱动开发破解 AI 编程协作难题

1.前言

什么是 规范(Spec)驱动开发?

我们可以知道规范驱动开发的流程

为什么要用 Spec?

OpenSpec 是一种 **规范驱动（spec‑driven）**‍ 的开源开发框架，主要面向 AI 编程助手 （如 Claude Code、GitHub Copilot、Cursor 等）而设计。它通过在「共识规范 → AI 执行 → 自动验证」的闭环流程，帮助团队在 AI 参与的代码开发过程中明确需求、降低指令歧义、提升代码可追溯性与可维护性。

核心理念与工作流

1. 共识规范（Spec） 先由人类与 AI 共同撰写结构化的需求规范（包括功能描述、输入/输出、边界条件、测试用例等）。
2. AI 执行 AI 根据规范自动生成代码、文档或变更提案。
3. 自动验证 框架内置的验证器会依据规范中的测试用例对生成的代码进行自动化检查，确保实现符合预期。
4. 迭代与归档 通过审查、计划、实现、归档等步骤形成完整的变更历史，便于后续审计与迭代。

它为 AI 编程工具（Claude Code、Cursor、Codex、OpenCode、windsurf 等）提供一种标准化的方式：

• 让 AI 生成、跟踪、验证、归档 功能变更；

• 把"功能需求 → 任务分解 → 实现 → 验收" 全流程结构化；

• 实现 AI 与人协同开发 的一致性。

🧠 核心理念：

"让 AI 先写清楚规范（spec）再写代码" 而不是盲目凭 prompt 去写。

适用场景

1 新项目、

2 功能增强（迭代项目）

3、多人协作。

这个项目最有价值的我个人觉的应该是功能增强 和多人协助开发，尤其是大型项目很多都是基于原有项目扩展和改造。之前由于模型上下文的问题导致很多企业级项目以及一些老旧项目升级改造AI 就变得难以搞定。另外AI 开发的项目多人协作也是比较难搞定的。这个项目刚好解决这个2个问题。今天小编就带大家通过一个实战的项目来体验感受一下这个规范驱动开发的框架。

2 项目实战

1.去https://www.trae.cn/下载trae, 安装到本地

2.安装OpenSpec

我们在终端命令行输入下面命令安装OpenSpec

先决条件

Node.js >= 20.19.0

步骤 1：全局安装 CLI

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

验证安装：

openspec --version

步骤 2：在项目中初始化 OpenSpec

导航到您的项目目录：

cd my-project

openspec init

初始化过程中会发生： 系统会让你选择所用的 AI 工具（Claude Code / Cursor / OpenCode / Codex）； 自动在项目中创建 openspec/ 目录； 生成托管文件 AGENTS.md，用于不同 AI 工具共享说明； 为所选 AI 工具自动配置 /openspec 的斜杠命令（slash commands）。

这个文件夹主要有以下几个文件和内容

openspec/
├── specs/                  # 规范目录（存放各类正式规范文档）
│   └── auth/               # 认证相关规范子目录
│       └── spec.md         # 当前认证规范文档（若存在）
└── changes/                # 变更目录（存放规范的修改提案与增量内容）
    └── add-2fa/            # 新增双因素认证（2FA）的变更子目录（由AI创建完整结构）
        ├── proposal.md     # 变更提案文档（说明为何修改、修改内容）
        ├── tasks.md        # 实施任务清单（记录需完成的具体开发/修改任务）
        ├── design.md       # 技术设计文档（技术方案决策，可选）
        └── specs/          # 变更对应的规范增量目录
            └── auth/       # 变更涉及的认证规范子目录
                └── spec.md # 规范增量文档（仅展示新增/修改的内容，即差异部分）

看到openspec根目录下有AGENTS.md、project.md。这个就是项目修改变更的依据 有了它 ，AI 就不会乱输入，尤其是对于变更项目这个是比较友好的。

AGENTS.md、project.md 默认的这2个文件是英文的我们把他翻译成中文。

OpenSpec 支持多种开发工具，我这里使用Qwen Code

这个目的主要是在项目中创建一个新的 openspec/ 目录结构，这个方便后面基于这个来控制项目

显示的过程如下:

中文转换

我们输入下面提示词

请帮我把openspec文件夹下AGENTS.md、project.md  内容翻译成中文

再把另外2个文件也转换成中文的.

请帮我把AGENTS.md和QWEN.md 内容翻译成中文

需求收集整理

openspec 主要的流程如下：

1. 起草一份变更提案，明确你期望的规范更新内容。
2. 与 AI 助手一同审核该提案，直至各方达成一致。
3. 执行任务，过程中需参考已达成共识的规范文档。
4. 对该变更进行归档，将已批准的更新内容合并回基准规范文档中。

使用

• 主动方式

使用 AI 编程工具的 自定义命令，比如 cursor,windsurf, auggie 等

/openspec:proposal 创建需求

/openspec:apply 执行需求

/openspec:archive 归档需求

• 被动方式

使用关键词，比如 spec, proposal 等触发创建规格文件

开发

接下来我们需要简单来完成一个需求

/openspec:proposal 请基于雪花id的知识以及雪花.md的内容，帮我完成功能开发。
请不要先代码，先把需求整理好，结合原来的项目梳理项目新增的变革需求。

输出如下:

再次执行:

/openspec:apply

项目归档

上面的新增加的需求变更已经完成。接下来我们需要执行第三命令/openspec:archive，对执行新增功能进行归档操作方便后面修改新功能对归档文档进行阅读。

我们同样执行下面命令

/openspec:archive

AI 执行完成后我们看到下面归档信息

本次新增需求就开发完成了。上面的文档信息和修改的代码提交代码仓库，其他小伙伴也可以依据已经修改的功能继续开发新的功能点了。

什么时候该使用Spec？

Openspec 规范驱动的原理是什么？

怎么触发的

执行完 openspec init 之后 会生成几个重要的文件(命令/工作流)

Agents.md

openspec-apply.md

openspec-proposal

怎么使用

• 使用关键词触发，比如 proposal,spec 之类的

• 使用 slash command(需要 AI 编程工具支持）指定触发， claude code 比较特殊，"/"命令后，收入输入，不要直接 enter 键

• 引用文件到对话框中，主要针对不支持 Agents.md 、Claude.md以及 slash command的工具

生成格式

• 执行 openspec init 命令后，会生成如下的目录结构

  openspec/
  ├── project.md # 项目约定
  ├── specs/ # 当前真实情况 - 已构建的内容
  │ └── [capability]/ # 单一聚焦能力
  │ ├── spec.md # 需求和场景
  │ └── design.md # 技术模式
  ├── changes/ # 提案 - 应该变更的内容
  │ ├── [change-name]/
  │ │ ├── proposal.md # 为什么、什么、影响
  │ │ ├── tasks.md # 实施检查清单
  │ │ ├── design.md # 技术决策（可选；见标准）
  │ │ └── specs/ # 增量变更
  │ │ └── [capability]/
  │ │ └── spec.md # ADDED/MODIFIED/REMOVED
  │ └── archive/ # 已完成的变更

proposal.md：

## Why（为什么）
[关于问题/机会的 1-2 句话]

## What Changes（变更内容）
- [变更项目列表]
- [用 **BREAKING** 标记破坏性变更]

## Impact（影响）
- 受影响的规范：[列出能力]
- 受影响的代码：[关键文件/系统]

spec.md

## ADDED Requirements（新增需求）
### Requirement: 新功能
系统应当提供...

#### Scenario: 成功案例
- **WHEN** 用户执行操作
- **THEN** 预期结果

## MODIFIED Requirements（修改需求）
### Requirement: 现有功能
[完整的修改后需求]

## REMOVED Requirements（移除需求）
### Requirement: 旧功能
**Reason（原因）**: [为什么移除]
**Migration（迁移）**: [如何处理]

如果影响多个能力，在 changes/[change-id]/specs/<capability>/spec.md 下创建多个增量文件 - 每个能力一个。

tasks.md：

## 1. 实施
- [ ] 1.1 创建数据库模式
- [ ] 1.2 实现 API 端点
- [ ] 1.3 添加前端组件
- [ ] 1.4 编写测试

在需要时创建 design.md：

如果满足以下任何条件，则创建 design.md；否则省略：

• 跨领域变更（多个服务/模块）或新的架构模式

• 新的外部依赖或重大数据模型变更

• 安全、性能或迁移复杂性

• 在编码前需要技术决策的歧义

最小 design.md 骨架：

## Context（背景）
[背景、约束、利益相关者]

## Goals / Non-Goals（目标/非目标）
- Goals（目标）：[...]
- Non-Goals（非目标）：[...]

## Decisions（决策）
- Decision（决策）：[什么和为什么]
- Alternatives considered（考虑的替代方案）：[选项 + 理由]

## Risks / Trade-offs（风险/权衡）
- [风险] → 缓解

## Migration Plan（迁移计划）
[步骤、回滚]

## Open Questions（开放问题）
- [...]

• Spec 驱动不是帮你解决 "业务/逻辑/算法" 难题

它不是解决难题，是建立规范，产生文档，记录变更