基于OpenSpec的SDD Vibe Coding实践

Read Time:2 Minute, 8 Second

随着大模型能力的发展，越来越多的AI IDE工具开始出现，Vibe Coding也逐渐变得流行起来。通过Vibe Coding，普通人如设计师、产品经理也可以快速进行原型验证。对于开发者而言，各种编程语言、框架与生态的壁垒不再是阻碍，前端开发者借助Vibe Coding也可以快速完成后端部署，后端开发者也可以通过Vibe Coding写出精美的前端页面。

在我的早期实践中，我发现使用大模型进行编程解决项目中的小需求点还是非常优秀的，一旦项目复杂度上升，需求无法再通过简单的文本进行描述时，AI的表现就差强人意了。具体表现在以下几点：

代码冗余，根本原因是AI本身没有模块化设计的思想，且不记得之前的实现，导致重复逻辑散落。
意图偏移，在基于一个基本需求进行拓展衍生时，AI往往会在改动中将之前实现的功能改掉，原因在于AI在多轮的对话中无法将上下文进行高效的关联，导致经常顾此失彼。‘

业界现在提供的解决方案是SDD（Spec-Driven Development),即规格驱动开发。其中OpenSpec是一套开源的SDD规范，专门用于AI Agent编程。

本篇博客将记录如何基于OpenSpec进行编程实践。

基础配置

基础配置部分我们参考OpenSpec官方文档，文档地址可点击here。

1.首先确保系统中已配置Node.js，通过node –version确认其版本信息

已配置Node.js时，通过如下命令安装OpenSpec：

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

安装完成后，通过openspec –version查看当前版本信息：

#查看版本信息
openspec  --version
#如下所示：
C:\Users\Administrator>openspec --version
0.17.2

以上就表明openspec已经安装完成。

2.安装完成后我们进入我们的项目目录，进入终端，执行如下命令：

openspec init

之后我们可以看到如下所示画面：

在这个阶段，openspec会要求你进行配置，选择需要配置的AI工具，如Claude Code、Cursor等，根据你的选择openspec会配置相应的命令行，并在当前的项目目录下创建openspec目录，同时会出现changes、specs子目录以及AGENTS.md和project.md两个文件。

在我的实践中我选择了Cursor作为我的AI IDE，其还会出现.cursor\commands目录，其目录内增加了openspec-apply.md,openspec-archive.md以及openspec-proposal.md。

同时我发现在Cursor Agent对话时我们可以使用/openspec自动补全命令行操作，可以方便快捷地完成相关任务。

需要说明的是，在openspec init完成后，我们需要重启我们的AI IDE才可以让配置生效。

这里有一个实用性的小技巧，在openspec生成的配置文件中，都是英文文档。这对我们中文用户而言不是很友好，但我们可以自行编辑openspec/AGENTS.md，让后续生成的内容为中文文档。

这里添加的内容如下：

## Language and Communication
* Default to Simplified Chinese for all OpenSpec artifacts and interaction, including `proposal.md`, `design.md`, `tasks.md`, and spec/spec-delta `spec.md` files.
* For tool compatibility, keep only OpenSpec structural tokens/headings in English: 
* Requirement/Scenario headings: `### Requirement:`, `#### Scenario:`
* Requirement section headings: `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`
* Scenario step keywords: `**GIVEN**`, `**WHEN**`, `**THEN**`, `**AND THEN**`
* Normative keyword: `SHALL` (recommended; write the rest in Chinese, e.g. `系统 SHALL ...`)
* Keep CLI commands, paths, and parameters as-is, and display them in code format (e.g., `openspec validate <id> --strict`).

工程使用

接下来就是将我们的工程实操环节，其实在我们openspec init完成之后，openspec就有给出相应的提示：

1. Populate your project context:
   "Please read openspec/project.md and help me fill it out
    with details about my project, tech stack, and conventions"

2. Create your first change proposal:
   "I want to add [YOUR FEATURE HERE]. Please create an
    OpenSpec change proposal for this feature"

3. Learn the OpenSpec workflow:
   "Please explain the OpenSpec workflow from openspec/AGENTS.md
    and how I should work with you on this project"

首先我们在Agent对话框内，输入please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions，openspec会提出相应的问题引导你进行初步的描述，我们进行初步的一些细化，如下所示：

这时我们需要在对话框内进行一个初步的需求描述，之后就会更新openspec/project.md，但此时其内部很多信息只是模板内容，需要根据我们实际的开发需求进行修改，这里我们手动修改project.md的内容。

之后我们引入我们的第一个提案，这里我们通过命令行/openspec-proposal命令进行创建。

在我的实践中，我想开发一个用于远程管理服务器的应用，该应用需要先实现服务器的添加和SSH的登录，并支持保存、编辑、删除服务器。这里我的/openspec-proposal 输入为实现添加服务器后进行SSH登录基础功能，并实现数据持久化。

在这个阶段，Openspec会在openspec/changes目录下增加新的子目录，并创建design.md、proposal.md以及tasks.md，针对我们的需求又自行细分了三个子需求,如下所示：

│  design.md
│  proposal.md
│  tasks.md
│
└─specs
    ├─data-persistence
    │      spec.md
    │
    ├─server-management
    │      spec.md
    │
    └─ssh-authentication
            spec.md

我们需要仔细查看这些生成的文件，按照自己的实际需要进行修改。

修改完成后，我们通过/openspec-apply PROPOSAL进行实现。如下所示：

第一次就生成了完整的代码，并完成了gradle相关配置，这里我注意到生成的配置使用的gradle版本为9.0，不出所然当我编译发生了一堆错误，后来我明确告诉Agent使用gradle版本8.7，问题才解决，之后可以实现正常编译。

需要说明的是，这期间并不会一帆风顺，你需要多次介入调试并且调整我们的design.md、proposal.md以及tasks.mk，以确保最终能够满足我们的设计要求。

当满足我们的需求之后，我们就可以通过/openspec-archive PROPOSAL进行归档了。

每一个Feature特性我们都可以按照上述的方式进行提案、实现以及归档。在归档阶段，openspec会进行两个动作：

1.将当前的proposal内容从changes的一级目录移动至changes/archive的二级目录，这里会按照日期进行归档

2.从当前提案中提取spec规范，放入specs目录

以上就完成了归档，我们可以开始新的提案创作了。

Update：在openspec的1.2.0版本中，提供了opsx-xxxx开头的commands以及openspec-xxxx开头的skills，opsx-xxxx是openspec提供的原生命令，而openspec-xxxx是作为skills提供给AI进行调用的。同时在openspec的新版本中，原生支持了多语言，无需进行额外设置就能进行中文对话。