Vibe Coding一人即团队系列41: 基于OpenSpec的规格驱动开发(SDD)实战指南

纲要

• 核心概念
  • SDD (Specification-Driven Development) 规格驱动开发
  • OpenSpec 轻量级SDD框架
  • Vibe Coding 与 Spec Coding 的对比
• 核心工作流与命令
  • explore - 需求勘探与方案探索
  • propose - 方案确定与规格生成
  • apply - 规格驱动代码实现
  • archive - 项目归档与历史记录
• 环境与配置
  • 安装与初始化 OpenSpec
  • 项目配置文件 openspec/config.yaml
  • 与 Claude Code 的集成使用
• 完整实战流程
  • 项目初始化和环境配置
  • 需求勘探与交互决策
  • 生成技术规格与任务清单
  • 自动代码生成与项目运行
  • 项目归档与版本管理
• 技术栈与最佳实践
  • 前端框架选型: React + Next.js
  • 本地数据优先策略
  • 跨端适配与响应式设计

探索OpenSpec: 规格驱动的全新开发范式

在现代软件开发中，尤其是面对一人团队或小型团队的场景，如何保证项目的长期可维护性和需求的可追溯性，是一个核心挑战。OpenSpec 作为 SDD (Specification-Driven Development) 的轻量级实现框架，提供了一套完整的规范化开发流程。它结合了 AI 辅助能力，使开发者从需求勘探到代码落地的全过程都能遵循严格的规格驱动，极大提升了代码质量和项目可持续性。

与纯粹的 Vibe Coding 体验式开发不同，SDD 强调通过结构化的规格文档来驱动开发。这种模式的优势在于，即使项目成员发生变动，后续开发者也能通过详尽的规格文档快速理解系统设计和技术决策，实现平滑过渡。

OpenSpec安装与环境配置

要开始使用 OpenSpec，首先需要在你的开发环境中进行安装。OpenSpec 是一个 Node.js 工具，可以通过 npm 全局安装。

# 安装 OpenSpec
npm install -g @openspec/cli

# 验证安装是否成功
openspec --version

安装完成后，在目标项目目录中执行初始化命令，以生成必要的配置文件和目录结构。

# 在项目根目录执行
openspec init

执行命令后，终端会展示一个交互式欢迎界面，提示你选择要集成的 AI 工具（如 Claude Code）。使用空格键选中 Claude Code 并按回车确认。初始化成功后，项目根目录会生成以下结构：

├── .claude/
│   └── commands/          # Claude Code 相关命令集成
├── openspec/
│   ├── config.yaml        # 项目全局配置文件
│   ├── specs/             # 规格文档存储目录
│   ├── tasks.md           # 任务清单文件
│   └── changes/           # 变更记录归档
├── AGENTS.md              # AI 代理指令文件
└── CLAUDE.md              # Claude 特定指令

其中 openspec/config.yaml 是项目的核心配置文件，用于定义项目的基础规格、技术约束和 AI 交互的上下文信息。示例如下：

# openspec/config.yaml
specification:
  driver: openspec
  description: "项目全局规格配置"
  knowledge:
    - "项目采用 React + Next.js 技术栈"
    - "数据存储以本地优先为原则"
  style:
    - "代码风格遵循 Airbnb JavaScript Style Guide"

初始化后，务必重新加载 Claude Code（如关闭并重新打开项目窗口），确保新生成的命令能够正确加载。

核心工作流与命令解析

OpenSpec 提供了一套完整的命令集，贯穿需求勘探、方案设计、代码实现和项目归档的全流程。其中核心命令主要包括以下四个：

1. explore - 需求勘探与方案探索

explore 命令用于启动需求勘探阶段。该命令会引导 AI 与开发者进行多轮交互，深入挖掘项目需求、功能边界、技术选型等关键决策点。这一过程类似于企业内部的需求评审会议，通过多角色视角的讨论，最终形成一份详尽的需求草案。

使用方式：在 Claude Code 中输入 /openspec:explore，并描述你的项目愿景。

/openspec:explore
# 提示词示例：开发一款理财记账应用，主要功能是记录日常消费和收入，支持分类统计。

执行后，AI 会基于提示词提出多个维度的待决策问题，例如：

• 场景定位: 应用的目标用户是谁？使用场景是什么？
• 技术形态: 选择 Web 应用、移动端原生应用还是跨端方案？
• 数据策略: 数据存储在云端还是本地？

开发者需要根据提示，将决策结果写回聊天窗口，供 AI 作为下一步分析的依据。

2. propose - 方案确定与规格生成

当 explore 阶段完成后，OpenSpec 会提议进入 propose 阶段。该命令负责将讨论成果固化为结构化的规格文档。它会生成包括但不限于以下内容的 Markdown 文件：

• design.md: 系统架构、技术栈、模块划分等技术设计方案。
• requirements.md: 功能需求列表、用户故事、验收标准。
• tasks.md: 基于规格拆解的具体开发任务清单。

使用方式：在 Claude Code 中执行 /openspec:propose。

/openspec:propose

执行后，OpenSpec 会自动根据 explore 阶段的上下文生成相应的文档，并存放在 openspec/specs/ 目录下。这些文档构成了后续开发活动的“契约”，确保每一行代码都有据可依。

3. apply - 规格驱动代码实现

apply 命令是 OpenSpec 的核心执行引擎。它读取 tasks.md 中定义的任务列表，逐项驱动 AI 生成符合规格的代码。该过程为全自动化，AI 会根据任务描述创建、修改或删除代码文件，并确保实现与规格一致。

使用方式：在 Claude Code 中执行 /openspec:apply。

/openspec:apply

执行过程中，AI 会按顺序处理任务，并实时更新 tasks.md 中的任务状态（如标记已完成的任务）。对于复杂项目，apply 阶段可能需要较长时间（10-30分钟不等），具体取决于任务的数量和复杂度。此阶段也是 Token 消耗的主要环节。

4. archive - 项目归档与历史记录

当一个迭代或项目里程碑完成后，archive 命令用于将当前的规格文档和变更记录进行归档。归档操作不仅清理了工作空间，还将当前状态保存为历史版本，便于未来查阅和追溯。

使用方式：在 Claude Code 中执行 /openspec:archive。

/openspec:archive

执行后，OpenSpec 会提示选择归档范围（如特定任务或全部任务），并将当前 specs 内容同步到 changes/ 目录下，形成按日期组织的变更历史。这一机制为项目的长期迭代提供了完善的审计和版本管理能力。

规格驱动开发实战演练

本节将以开发一款“理财记账应用”为例，全景展示 OpenSpec 从初始化到归档的完整工作流。其整体流程如下图所示：

步骤一: 需求勘探 (explore)

假设我们启动一个名为“理财记账”的项目。在 Claude Code 中执行 explore 命令，并提供初始提示词：

/openspec:explore
提示词：开发一款理财记账应用，主要功能是记录消费和收入。

AI 会根据提示，返回一系列需要确认的决策点。例如，它会询问应用的目标用户、平台形态和数据存储策略。开发者需要针对这些问题提供具体反馈：

• 场景: 个人使用，作为日常记账工具。
• 平台: 以 Web 应用为主，优先适配移动端视图。
• 数据存储: 本地优先，数据保存在浏览器 IndexedDB 中，确保数据隐私。

经过多轮交互，OpenSpec 会收集到足够的信息，并建议进入下一步。

步骤二: 方案确定与规格生成 (propose)

收到 explore 的完成信号后，执行 propose 命令：

/openspec:propose

AI 会立即开始整理讨论结果，并生成以下关键文档（位于 openspec/specs/ 目录）：

• 技术方案 (design.md): 确定了采用 React + Next.js 框架，并建议使用 Tailwind CSS 进行样式管理，以 IndexedDB 作为本地持久化方案。
• 功能需求 (requirements.md): 详细描述了记账、分类管理、月度报表等核心功能模块。
• 任务清单 (tasks.md): 拆解出包括“创建记账页面”、“实现收入/支出分类”、“搭建本地数据模型”等在内的十项具体开发任务。

步骤三: 代码生成与实施 (apply)

确认规格文档无误后，执行 apply 命令进入自动编码阶段：

/openspec:apply

OpenSpec 会依次读取 tasks.md 中的任务，并生成对应的代码文件。例如，它可能会创建 components/TransactionForm.tsx、lib/db.ts 等文件，并实现数据存取逻辑。执行完毕后，tasks.md 中的任务项会被标记为已完成。

步骤四: 项目启动与验证

代码生成完毕后，即可启动项目进行功能验证。在 Claude Code 中，可以通过指令让 AI 启动开发服务器：

帮我启动项目

AI 会执行 npm run dev 等相应命令。项目启动后，通过浏览器访问 http://localhost:3000，即可看到记账应用的界面。应用已具备基本的记账、分类浏览和流水查询功能。

步骤五: 项目归档 (archive)

项目验证通过后，可以执行 archive 命令进行归档：

/openspec:archive

AI 会提示选择归档范围。确认后，OpenSpec 会将当前 specs 目录下的文档同步到 changes/ 下的一个新日期目录中（例如 changes/2026-08-15/），作为该版本的历史快照。这标志着当前迭代周期的结束。

API 速览

以下是 OpenSpec CLI 的核心命令及用法：

Demo示例

以下是一个 OpenSpec 生成的简单记账应用的核心交互界面，它是一个基于 React 和 Tailwind CSS 构建的响应式 H5 应用。该应用演示了记账流水的展示、收入/支出录入以及分类管理功能。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
  <title>理财记账</title>
  <!-- 使用 Tailwind CSS 通过 CDN 引入 -->
  <script src="https://cdn.tailwindcss.com"></script>
  <!-- 使用 Font Awesome 图标库 -->
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0-beta3/css/all.min.css">
</head>
<body>
  <div id="root" class="max-w-md mx-auto bg-gray-50 min-h-screen shadow-lg">
    <!-- 应用头部 -->
    <header class="bg-white p-4 border-b border-gray-200 flex justify-between items-center">
      <h1 class="text-xl font-bold text-gray-800"><i class="fas fa-wallet text-indigo-500 mr-2"></i>理财账本</h1>
      <div class="flex space-x-3 text-gray-600">
        <i class="fas fa-search"></i>
        <i class="fas fa-user-circle text-2xl"></i>
      </div>
    </header>

    <!-- 资产概况卡片 -->
    <section class="m-4 p-4 bg-gradient-to-r from-indigo-500 to-purple-500 rounded-2xl shadow-lg text-white">
      <div class="flex justify-between items-center">
        <div>
          <p class="opacity-80 text-sm">当前总资产</p>
          <p class="text-3xl font-bold">¥ 12,860.50</p>
        </div>
        <div class="bg-white/20 p-3 rounded-full">
          <i class="fas fa-eye text-xl"></i>
        </div>
      </div>
      <div class="flex justify-between mt-4 text-sm">
        <div>
          <p class="opacity-80">收入</p>
          <p class="font-semibold text-green-200">+ ¥ 8,400.00</p>
        </div>
        <div>
          <p class="opacity-80">支出</p>
          <p class="font-semibold text-red-200">- ¥ 2,539.50</p>
        </div>
      </div>
    </section>

    <!-- 快速记账入口 -->
    <div class="flex justify-around mx-4 mb-4">
      <button class="bg-green-500 hover:bg-green-600 text-white p-4 rounded-full shadow-lg flex items-center justify-center w-16 h-16 transition">
        <i class="fas fa-plus text-2xl"></i>
      </button>
      <button class="bg-red-500 hover:bg-red-600 text-white p-4 rounded-full shadow-lg flex items-center justify-center w-16 h-16 transition">
        <i class="fas fa-minus text-2xl"></i>
      </button>
      <button class="bg-gray-200 hover:bg-gray-300 text-gray-700 p-4 rounded-full shadow flex items-center justify-center w-16 h-16 transition">
        <i class="fas fa-chart-pie text-xl"></i>
      </button>
    </div>

    <!-- 最近流水列表 -->
    <div class="mx-4 bg-white rounded-xl shadow-sm p-3">
      <div class="flex justify-between text-gray-500 px-2 py-1 border-b border-gray-100">
        <span class="font-medium">最新流水</span>
        <span class="text-indigo-500 text-sm">查看全部</span>
      </div>
      <ul class="divide-y divide-gray-100">
        <li class="flex justify-between items-center py-3 px-2">
          <div class="flex items-center space-x-3">
            <span class="bg-blue-100 text-blue-600 p-2 rounded-full"><i class="fas fa-utensils"></i></span>
            <div>
              <p class="font-medium text-gray-800">午餐</p>
              <p class="text-xs text-gray-400">今日 12:30</p>
            </div>
          </div>
          <span class="text-red-500 font-semibold">-¥35.00</span>
        </li>
        <li class="flex justify-between items-center py-3 px-2">
          <div class="flex items-center space-x-3">
            <span class="bg-green-100 text-green-600 p-2 rounded-full"><i class="fas fa-wallet"></i></span>
            <div>
              <p class="font-medium text-gray-800">工资到账</p>
              <p class="text-xs text-gray-400">昨日 10:00</p>
            </div>
          </div>
          <span class="text-green-500 font-semibold">+¥3,200.00</span>
        </li>
      </ul>
    </div>

    <!-- 底部导航栏 -->
    <nav class="fixed bottom-0 left-0 right-0 bg-white border-t border-gray-200 flex justify-around py-2 max-w-md mx-auto">
      <a href="#" class="text-indigo-500 flex flex-col items-center text-xs"><i class="fas fa-home text-xl"></i><span>首页</span></a>
      <a href="#" class="text-gray-400 flex flex-col items-center text-xs"><i class="fas fa-chart-line text-xl"></i><span>报表</span></a>
      <a href="#" class="text-gray-400 flex flex-col items-center text-xs"><i class="fas fa-cog text-xl"></i><span>设置</span></a>
    </nav>
  </div>
</body>
</html>

运行说明

1. 将上述 HTML 代码保存为 index.html 文件。
2. 使用现代浏览器（如 Chrome、Edge）直接双击打开该文件，或使用 VS Code 的 Live Server 插件启动。
3. 页面模拟了移动端适配视图，展示了记账应用的核心布局。

技术点总结

• 响应式设计: 通过 Tailwind CSS 的 max-w-md 和 mx-auto 类模拟移动设备卡片视图。
• UI 组件化: 使用语义化的 HTML 结构和 Font Awesome 图标构建清晰界面。
• 数据展示: 演示了资产统计、流水列表等核心数据的静态展示方式。
• 交互反馈: 按钮悬停和点击状态使用了 transition 和颜色变化。

参考文档

官方文档

• OpenSpec 官方文档: https://openspec.dev/
• OpenSpec GitHub 仓库: https://github.com/openspec/openspec

参考链接

• SDD (Specification-Driven Development) 概念介绍: https://en.wikipedia.org/wiki/Specification-driven_development
• Claude Code 使用指南: https://docs.anthropic.com/en/docs/claude-code

总结

OpenSpec 为一人团队或小规模开发团队提供了一套严谨、可落地的规格驱动开发方案。它将模糊的需求通过 explore 阶段清晰化，借助 propose 固化为文档契约，最终利用 apply 实现自动化代码生成，并通过 archive 保证了项目的可追溯性。

其核心价值在于将临时性的 AI 对话转化为结构化的项目资产，显著提升了开发效率和长期维护的可行性。对于追求工程质量与可持续迭代的开发者而言，OpenSpec 提供了一条从“想法”到“产品”的规范化高速公路。