OpenSpec入门指南：从零开始掌握规范编写

随着AI编程助手成为开发者日常工作的标配，开发效率的提升显而易见。但一个普遍困扰也随之凸显：当需求描述不够具体时，AI生成的代码常常与开发者的真实意图存在偏差，导致反复沟通和修改，反而降低了工作效率。那么，是否存在一种方法，能让AI像熟练的工程师一样，精准理解并执行复杂的开发指令？

“规范驱动开发”（Specification-Driven Development, SDD）为此提供了解决方案。其核心理念直击要害：首先像绘制严谨的工程蓝图一样，定义清晰、完整的技术规范，然后让AI作为“执行者”严格按图施工。本文将深入探讨这一理念的杰出实践——开源工具OpenSpec，并解析其如何重塑人机协作的编码流程。

OpenSpec是什么？

OpenSpec是一款专为AI编程助手设计的规范驱动开发（SDD）工具。它通过一套结构化的变更管理文件夹系统（涵盖提案、任务和规范更新），确保项目范围的明确性和所有修改的可追溯性。其根本目标，是在实际编写任何代码之前，就让人工开发者与AI助手在技术实现的每一个细节上达成牢固共识。

目前，OpenSpec已迭代至0.16.0版本，其主要优势体现在三个方面：完全开源且免费、既支持从零搭建新项目也适配现有项目的迭代优化，以及提供了跨平台的良好支持。当然，要充分发挥其效能，理解其核心工作流程是第一步。

为什么需要OpenSpec？

要洞悉OpenSpec的价值，首先需要审视传统AI编码协作中常见的几个痛点：

• 需求描述模糊不清：仅凭一句自然语言描述需求，存在大量歧义空间，AI只能进行“猜测性”理解。
• 项目上下文缺失：AI缺乏对项目整体架构、技术选型和业务约束的全局认知，容易遗漏关键功能或添加冗余代码。
• 编码标准不统一：缺乏明确的输入输出规范、代码风格和架构要求，导致AI生成的代码质量参差不齐，难以维护。
• 文档与代码脱节：文档通常滞后于代码变更，一旦代码修改，文档迅速过时，形成信息断层。

OpenSpec所倡导的规范驱动开发模式，正是为了系统化地解决上述问题：

• 建立明确共识：在编码开始前锁定所有功能与非功能要求，确保技术规范的一致性。
• 管理结构化变更：将所有相关的需求、设计和任务文档集中管理，使变更过程清晰、可追溯。
• 生成可审查的输出：AI基于明确的规范生成代码，使得从提案、开发到归档的每个环节都具备高度可见性和可审查性。
• 实现完整版本控制：完整记录从需求提案到规范归档的整个变更历史，便于审计与回溯。

核心工作流程解析

OpenSpec的工作流程构成了一个高效的闭环，通常可分为四个关键阶段：

1. 起草变更提案：使用自然语言描述功能需求或问题。AI会分析需求、主动询问关键细节，并自动生成结构化的提案文档、技术设计稿、详细任务清单以及待更新的规范增量。
2. 审查与对齐：与AI助手共同审查生成的提案，补充遗漏信息，反复打磨直至技术规范得到所有参与者（包括开发者和AI）的最终确认。
3. 实施开发任务：严格依据已确认的规范，逐一执行开发任务。AI将生成对应代码，并实时更新任务进度状态。
4. 归档与知识更新：变更实施完成后进行归档，并将已批准的规范增量合并到项目的主规范文档中，实现项目知识的持续沉淀与积累。

快速上手指南

安装与配置

使用OpenSpec需要预先安装Node.js（建议版本20.19.0或更高）。之后，通过npm全局安装其命令行工具：

$ 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工作流说明。

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

让我们以“为Web应用添加用户注册登录页面”这一常见需求为例，完整走一遍OpenSpec的流程。

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

2. 创建变更提案：你可以用自然语言描述需求：“请创建一个OpenSpec变更提案，用于添加一个用户注册和登录页面”。也可以使用OpenSpec生成的自定义命令，例如 /openspec:proposal 添加一个注册登录页面。对于模糊的需求点，AI会主动提问（例如采用何种认证方式、需要包含哪些具体功能等），你需要给出明确回答。随后，AI将生成结构化的提案目录及相关文档。

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

4. 实施开发任务：提案验证通过后，进入实施阶段。使用提示“请实施 add-auth-pages 变更提案”或命令 /openspec-apply add-auth-pages。AI将依据确认的规范生成前端与后端代码，并同步更新任务状态。在此阶段，你可以随时提出调整，AI会相应更新提案内容。

5. 归档变更：开发与测试完成后，进行变更归档。使用提示“归档变更 add-auth-pages”、命令 /openspec-archive add-auth-pages 或CLI命令 openspec archive add-auth-pages。归档操作会将本次提案的规范内容合并到主规范库（specs/目录），并将原始提案文件夹移至存档目录（changes/archive/）。

至此，一个需求从提出、细化、开发到知识沉淀的完整生命周期，就在清晰、可控的规范驱动下高效完成了。这不仅仅是引入了一个工具，更是采纳了一种能显著提升人机协作效率与可靠性的新一代开发范式。