编程语言Node.jsAI
OpenSpec 实战：用规范驱动开发优化 AI 编程协作
OpenSpec 是一种面向 AI 编程助手的规范驱动开源开发框架，通过共识规范、AI 执行、自动验证的闭环流程，帮助团队明确需求并降低指令歧义。文章介绍了其核心理念、适用场景及项目实战步骤，包括环境配置、初始化命令、文件结构说明以及使用斜杠命令进行需求提案、执行与归档的具体操作。最后阐述了规范驱动的原理，强调其核心价值在于建立规范、产生文档并记录变更，而非直接解决业务逻辑难题。
OpenSpec 是一种面向 AI 编程助手的规范驱动开源开发框架，通过共识规范、AI 执行、自动验证的闭环流程，帮助团队明确需求并降低指令歧义。文章介绍了其核心理念、适用场景及项目实战步骤，包括环境配置、初始化命令、文件结构说明以及使用斜杠命令进行需求提案、执行与归档的具体操作。最后阐述了规范驱动的原理，强调其核心价值在于建立规范、产生文档并记录变更，而非直接解决业务逻辑难题。
我们可以了解规范驱动开发的流程。
OpenSpec 是一种规范驱动（spec-driven）的开源开发框架，主要面向 AI 编程助手（如 Claude Code、GitHub Copilot、Cursor 等）而设计。它通过在「共识规范 → AI 执行 → 自动验证」的闭环流程，帮助团队在 AI 参与的代码开发过程中明确需求、降低指令歧义、提升代码可追溯性与可维护性。
它为 AI 编程工具（Claude Code、Cursor、Codex、OpenCode、windsurf 等）提供一种标准化的方式：
🧠 核心理念：
'让 AI 先写清楚规范（spec）再写代码'，而不是盲目凭 prompt 去写。
该框架在功能增强和多人协作开发中价值较高，尤其是大型项目很多都是基于原有项目扩展和改造。之前由于模型上下文的问题导致很多企业级项目以及一些老旧项目升级改造 AI 就变得难以搞定。另外 AI 开发的项目多人协作也是比较难搞定的。这个项目刚好解决这两个问题。
访问 https://www.trae.cn/ 下载并安装到本地。
我们在终端命令行输入下面命令安装 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 主要的流程如下：
使用 AI 编程工具的自定义命令，比如 cursor, windsurf, auggie 等：
/openspec:proposal 创建需求
/openspec:apply 执行需求
/openspec:archive 归档需求
使用关键词，比如 spec, proposal 等触发创建规格文件。
接下来我们需要简单来完成一个需求：
/openspec:proposal 请基于雪花 id 的知识以及雪花.md 的内容，帮我完成功能开发。请不要先代码，先把需求整理好，结合原来的项目梳理项目新增的变革需求。
输出如下:
再次执行：
/openspec:apply
上面的新增加的需求变更已经完成。接下来我们需要执行第三命令 /openspec:archive，对执行新增功能进行归档操作方便后面修改新功能对归档文档进行阅读。
我们同样执行下面命令：
/openspec:archive
AI 执行完成后我们看到下面归档信息。
本次新增需求就开发完成了。上面的文档信息和修改的代码提交代码仓库，其他小伙伴也可以依据已经修改的功能继续开发新的功能点了。
执行完 openspec init 之后会生成几个重要的文件 (命令/工作流)：
Agents.mdopenspec-apply.mdopenspec-proposalopenspec 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（开放问题）
- [...]
它不是解决难题，是建立规范，产生文档，记录变更。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online