初识OpenSpec

在AI编程助手日益普及的今天，开发效率的提升有目共睹。然而，一个普遍存在的痛点也逐渐浮出水面：当需求描述不够精确时，AI生成的代码往往与预期相去甚远，导致反复沟通和修改，反而拖慢了进度。有没有一种方法，能让AI像理解图纸一样，精准地执行我们的开发意图？

答案或许就藏在“规范驱动开发”（Specification-Driven Development, SDD）的理念中。其核心逻辑非常直接：先像绘制精密图纸一样定义好技术规范，再让AI这位“施工员”严格按图作业。今天，我们要深入剖析的，正是这一理念的优秀实践——开源工具OpenSpec。

OpenSpec是什么？

简单来说，OpenSpec是一个专为AI编程助手设计的规范驱动开发工具。它通过一套结构化的变更文件夹（涵盖提案、任务和规范更新）来确保项目范围的明确性和可审计性。其根本目的，是在任何实际编码工作开始之前，就让人类开发者与AI助手在技术细节上达成共识。

当前，OpenSpec已更新至0.16.0版本，其主要优势可以概括为三点：完全开源免费、既适用于从零开始的新项目也适合迭代中的现有项目，以及提供了多平台支持。当然，要顺畅使用它，你需要对其工作流程有一个基本的了解。

为什么需要OpenSpec？

要理解OpenSpec的价值，得先看看传统AI编码助手面临的几个典型困境：

• 需求描述模糊
  ：依靠一句自然语言描述需求，存在大量歧义空间，AI只能“猜”你的意图。

• 上下文缺失
  ：AI不了解项目的整体架构和技术约束，容易遗漏关键功能或画蛇添足。

• 标准缺失
  ：没有明确的输入输出规范，AI自由发挥的代码质量难以预测，风格不一。

• 文档滞后
  ：代码与文档分离，一旦代码修改，文档往往立刻过时，形成信息孤岛。

OpenSpec的规范驱动开发模式，正是为了系统性地解决这些问题：

• 明确共识
  ：编码前锁定所有要求，确保技术规范一致。

• 结构化变更
  ：所有相关文档集中管理，变更过程清晰可追溯。

• 可审查输出
  ：AI基于明确规范生成代码，所有提案、进行中或已存档的内容都具备高度可见性。

• 版本控制
  ：完整追踪从提案到归档的整个变更历史。

核心工作流程解析

OpenSpec的工作流程是一个清晰的闭环，大致可以分为四个阶段：

1. 起草变更提案
   ：用自然语言描述功能需求，AI会分析需求、询问关键细节，并自动生成完整的提案文档、设计稿、任务清单和规范增量。

2. 审查对齐
   ：与AI助手一同审查提案，补充遗漏点，反复打磨直至规范得到所有参与者（包括你和AI）的认可。

3. 实施任务
   ：严格按照已确认的规范逐一执行开发任务，并实时标记任务进度。

4. 存档更新
   ：变更完成后进行归档，并将批准的规范合并到项目的主规范文档中，形成知识沉淀。

快速上手指南

安装与配置

使用OpenSpec的前提是安装Node.js（版本20.19.0及以上）。之后，通过npm全局安装CLI工具：

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

安装后，在命令行输入 openspec --version 验证，出现版本号即表示成功。

基本使用与目录结构

OpenSpec支持在主流AI编码助手平台中使用，其强大功能离不开一套严谨的目录结构。一个完整的OpenSpec项目结构如下：

openspec/
├── project.md             # 项目规范约定
├── AgentS.md              # 为AI助手提供的使用说明（通常无需改动）
├── specs/                 # 源规范目录，每次变更归档后会合并到这里
│       ├── spec.md        # 源需求和场景规范
│       └── design.md      # 源技术设计
├── changes/               # 提案变更目录
│   ├── [change-name]/     # 单个提案变更文件夹
│   │   ├── proposal.md    # 变更原因、内容与影响
│   │   ├── tasks.md       # 实施检查清单
│   │   ├── design.md      # 技术决策（可选）
│   │   └── specs/         # 增量变更规范
│   │       └── [capability]/
│   │           └── spec.md # 记录新增/修改/删除的规范
│   └── archive/           # 已完成的提案变更存档目录

这个结构是OpenSpec管理提案、验证、执行和归档的生命周期基础。

初始化项目

在项目根目录下执行 openspec init 即可初始化。过程分为三步：简介（直接回车）、选择你使用的AI开发工具（以便生成对应配置）、信息确认。完成后，OpenSpec会给出清晰的操作引导。

引导建议通常包括：1. 让AI帮你填充项目上下文信息到 project.md；2. 创建你的第一个变更提案；3. 让AI从 AGENTS.md 学习OpenSpec工作流。

实战演练：一个完整的变更周期

让我们以一个“添加注册登录页面”的需求为例，走完整个OpenSpec流程。

：初始化后，首先让AI熟悉项目。你可以直接使用引导词，或手动提示：“熟悉项目功能、技术栈等信息并填充 @project.md”。AI会协助你完善项目基础文档。

：你可以用自然语言描述：“创建一个OpenSpec变更提案，用于添加一个注册登录页面”，或使用OpenSpec生成的自定义命令如 /openspec:proposal 添加一个注册登录页面。对于模糊需求，AI会主动提问（例如认证方式、功能范围等），你需要明确回答。AI随后会生成结构化的提案目录。

：提案创建后，可使用命令 openspec validate [变更名称] --strict 进行手动验证，确保规范完整合规。

：提案验证通过后，即可实施。使用提示“实施 add-auth-pages 变更提案”或命令 /openspec-apply add-auth-pages。AI将根据规范生成代码，并更新任务状态。此阶段可随时提出调整，AI会同步更新提案。

：开发完成后，进行归档。使用提示“归档变更 add-auth-pages”、命令 /openspec-archive add-auth-pages 或CLI命令 openspec archive add-auth-pages。归档操作会将提案规范合并到主规范库，并将原提案移至存档目录。

至此，一个需求从提出、明确、开发到知识沉淀的全流程，就在清晰、可控的规范驱动下完成了。这不仅仅是使用了一个工具，更是引入了一种让人类与AI协同更高效、更可靠的工作范式。