从“凭感觉聊天”到“按规范开发”的转变，是提升AI编程可控性和工程质量的关键一步。OpenSpec作为一个轻量级的规范驱动开发框架，为实现这一转变提供了清晰的路径和实用的工具-1。

下面是一份详细的OpenSpec规范驱动开发指南，帮助你理解和上手这一工作流。

🌊 从Vibe Coding到Spec Coding：为何需要OpenSpec？

Vibe Coding（氛围编程）让开发者通过自然语言和AI对话来生成代码，极大地提升了原型开发的速度-3-5-9。然而，这种非结构化的协作方式也带来了挑战：

• 需求偏移与幻觉：AI容易遗漏细节、添加多余功能，导致代码与预期不符-1。

• 不可预测性：项目状态和变更历史仅存在于零散的聊天记录中，难以追踪和审计-1-2。

• 维护成本高：快速生成的“面条代码”缺乏一致性和架构完整性，长期维护困难-5。

Spec Coding（规范驱动开发，SDD）应运而生。它主张在编写任何代码之前，先由人类和AI共同创建一份清晰、机器可读的规范，作为项目唯一的“真相来源”-1-6。OpenSpec正是实现这一理念的轻量级框架。

🧭 OpenSpec核心概念与工作流

OpenSpec的核心是通过一个结构化的四阶段工作流，将模糊的想法转化为可落地的代码。

下图清晰地展示了从“意图”到“实施”再到“归档”的完整闭环：

这个工作流的顺利执行，依赖于一个精心设计的目录结构-1-2-10：

• openspec/specs/：存放所有已实现功能的规范，是项目的“真相来源”。

• openspec/changes/：存放所有进行中的变更提案。每个变更（如 add-user-login）都是一个独立的子目录，包含：

  • proposal.md：解释变更的“原因”和“内容”-10。

  • tasks.md：供AI执行的详细实施清单-10。

  • design.md：（可选）记录关键的技术设计决策-10。

  • specs/：存放本次变更对 specs/ 目录的增量修改，格式与主规范保持一致-2。

🚀 OpenSpec 上手实战指南

下面我们通过一个完整的实战案例，来演示如何使用OpenSpec完成一个功能开发。

准备工作：安装与初始化

OpenSpec是基于Node.js的命令行工具，安装非常简单-2-4。

1. 安装CLI工具
打开终端，全局安装OpenSpec包：

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

安装后，可以用以下命令验证是否成功：

openspec --version

2. 在你的项目中初始化
进入你的项目根目录，运行初始化命令：

cd your-project
openspec init

初始化时，CLI会引导你选择正在使用的AI工具（如Cursor、Copilot等），并自动在项目中创建openspec/目录和必要的配置文件-2。

实战案例：为应用添加用户登录功能

假设我们要为一个Web应用添加“用户登录”功能。

第一步：起草变更提案 (Draft Proposal)
在AI助手的聊天框中，输入自然语言指令。如果你的AI工具支持斜杠命令（如Cursor），可以直接使用快捷方式-2-8：

/openspec:proposal 添加用户登录功能

AI会自动在openspec/changes/下创建一个新目录（如add-user-login），并生成proposal.md、tasks.md和必要的规范增量文件骨架-4。

第二步：审查与对齐 (Review & Align)
此刻，你需要扮演审核者的角色。打开AI生成的文件进行检查和迭代-2。

• 查看 openspec/changes/add-user-login/proposal.md，确认变更范围和目标是否正确。

• 查看 openspec/changes/add-user-login/tasks.md，细化实施步骤。

• 最关键的是审查规范增量文件，例如 openspec/changes/add-user-login/specs/auth/spec.md，确保需求描述清晰、无歧义。一个规范的格式通常如下-7-10：

## ADDED Requirements
### Requirement: 用户密码登录
系统 MUST 允许已注册用户通过邮箱和密码登录。

#### Scenario: 成功登录
- **GIVEN** 用户已注册且邮箱和密码正确
- **WHEN** 用户提交登录表单
- **THEN** 系统返回一个有效的会话令牌

#### Scenario: 密码错误
- **GIVEN** 用户已注册但提交了错误密码
- **WHEN** 用户提交登录表单
- **THEN** 系统返回密码错误提示

你可以与AI对话要求修改，也可以直接手动编辑这些Markdown文件，直到你对计划完全满意-2。

第三步：AI驱动的实施 (AI-Driven Implementation)
计划锁定后，就可以让AI开始动手写代码了。在AI聊天框中输入-2-4：

/openspec:apply add-user-login

此时，AI的角色完全转变为“执行者”。它会严格遵循 tasks.md 中的清单和规范文件里的要求，一步步编写代码、创建文件、编写测试，并在完成后自动勾选任务项-2。

第四步：归档并更新真相来源 (Archive & Update Specs)
实施完成并验证通过后，进行最后一步归档。在AI聊天框中输入-2-4：

/openspec:archive add-user-login

这个命令会将 changes/add-user-login/specs/ 下的增量规范，合并到主 specs/ 目录中，正式更新了整个项目的“真相来源”。同时，该变更会被标记为“已归档”，代表本次开发周期的结束-1-2。

💡 关键规范格式与最佳实践

为了确保AI能准确理解规范，编写时需要遵循一些简单的规则-10：

规范要素	格式要求	示例
变更类型	使用 ## ADDED/MODIFIED/REMOVED Requirements 作为前缀	## ADDED Requirements
需求标题	使用 ### Requirement: 描述	### Requirement: 用户密码登录
验收场景	使用 #### Scenario: 描述，并用 - **GIVEN/WHEN/THEN** 描述步骤	#### Scenario: 成功登录 - **WHEN** 用户提交登录表单 - **THEN** 系统返回令牌
关键词	使用 MUST、SHALL 等强约束词表达硬性需求	系统 MUST 验证用户密码。

🧰 常用命令速查

在开发过程中，这些命令会经常用到-2-10：

命令	用途
openspec list	查看所有进行中的变更
openspec show <change-id>	查看某个变更的详细信息
openspec validate <change-id>	验证变更文件夹内的规范格式是否正确
openspec archive <change-id> --yes	归档一个已完成的变更

从Vibe Coding到Spec Coding的转变，本质上是将工程的纪律性注入到AI的创造性中。OpenSpec提供了一个轻量、非侵入式的桥梁，让开发者能在享受AI带来的效率飞跃的同时，依然牢牢掌控项目的质量和演进方向-1-6。希望这份指南能帮助你开启新的开发体验。