OpenSpec 实战：用规范驱动开发优化 AI 编程协作

访问 https://www.trae.cn/ 下载并安装到本地。

2.1 安装 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 驱动不是帮你解决'业务/逻辑/算法'难题

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