读懂 OpenSpec：AI 编码时代的规范驱动开发新范式

当下 AI Coding 已经成为程序员日常开发的标配，Cursor、Copilot 等工具大幅提升了编码效率，但行业痛点依然普遍：需求模糊导致 AI 乱写代码、多人协作上下文不一致、迭代变更无追溯、代码实现和业务预期严重偏差。

传统开发模式已经跟不上 AI 迭代的速度，而 OpenSpec 的出现，完美解决了 AI 编程的核心乱象。它是一套面向 AI 场景的轻量化规范驱动开发（SDD）框架，通过标准化流程，让人类开发者与 AI 达成统一共识，让 AI 编码从"盲写代码"变成"按规落地"。本文将从核心概念、核心能力、目录结构、实操流程、开发者进化路径五个维度，全方位拆解 OpenSpec。

一、核心概念厘清：SDD、OpenSpec、Harness 与核心文件体系

想要吃透 OpenSpec，首先要理清几组核心概念的关联与区别，理解其底层设计逻辑。

1.1 什么是 SDD（规范驱动开发）

SDD 全称 Specification-Driven Development ，即规范驱动开发 ，是区别于传统敏捷、瀑布流的新型开发思想。传统开发是「先编码、后补文档、边写边改」，开发者 80% 精力耗费在手写编码、调试修 bug、对齐需求等重复工作上。而 SDD 模式彻底颠覆了开发者的工作重心，核心逻辑是 先定规范、后做实现、迭代落地、全程可追溯。

在传统开发模式中，程序员的核心价值是「写代码」，编码速度、语法熟练度、排错能力是核心考核指标。但在 AI 编码普及的当下，基础编码工作已完全可以由 AI 高效承接，传统开发模式彻底跟不上 AI 迭代节奏，而 SDD 开发模式的落地，让程序员的核心工作彻底转移：从编码执行者，转变为规范定义者、AI 调度者、质量把控者。OpenSpec 正是 SDD 思想的轻量化落地工具，摒弃了重型规范文档，用极简结构化文件，适配 AI 快速迭代的开发节奏，完成开发者工作模式的升级。

1.2 OpenSpec 与 Harness 的关系

很多开发者会混淆两者，这里做精准界定：OpenSpec 与 Harness Engineering 是理念相通但相互独立的两个概念，无底座与上层的依赖关系。

Harness Engineering 是 OpenAI 提出的 AI 工程化范式，核心思想是通过标准化外部工程体系、规范流程，驾驭大模型能力，解决 AI 开发无序问题；而 OpenSpec（@fission-ai/openspec）是一款独立的轻量化 CLI 工具，也是 Harness Engineering 范式在规范管理领域的具体落地实现。二者可搭配使用，OpenSpec 无需依赖 Harness 即可独立运行。

开发者无需依赖复杂底层范式，直接使用 OpenSpec 标准化命令和结构化文件，即可落地 AI 规范化开发流程，适配各类项目场景。

1.3 OpenSpec 文件与 agents.md 的核心作用

OpenSpec 的核心价值，是通过固定格式的结构化文件，搭建「人类-AI」的高效沟通桥梁，其中 AGENTS.md 是核心辅助文件，定位极易混淆，这里精准区分两个核心文件的作用。

AGENTS.md 是 OpenSpec 自动生成的AI 工作流指南 ，核心作用是告诉 AI 如何识别、理解 OpenSpec 的目录结构、文件规则、CLI 指令使用规范，约束 AI 遵循标准工作流执行开发任务。而 project.md 才是整个项目的业务与技术上下文说明书，负责定义项目技术栈、编码规范、全局约束、架构信息。

AI 会优先读取 AGENTS.md 适配 OpenSpec 工作流，再结合 project.md 掌握项目全局规则，彻底解决传统 AI 编码上下文丢失、规则反复对齐的低效问题，形成「工作流约束+项目规范+代码落地」的完整闭环，让 AI 开发全程可控、可追溯、可复用。

二、OpenSpec 核心定位：到底解决了什么问题？

OpenSpec 不是代码生成工具，也不是替代 IDE 的编辑器，而是AI 时代的开发流程标准化工具，核心作用可以总结为 4 点，精准击中 AI 编码痛点：

2.1 统一人机共识，杜绝需求偏差

所有开发工作启动前，先产出标准化规范文档，明确「为什么做、做什么、怎么做、验收标准是什么」，让开发者和 AI 完全对齐，从根源避免 AI 理解偏差、代码不符合业务需求的问题。

2.2 全生命周期变更追溯

从需求提案、方案设计、代码落地到归档复盘，每一次迭代变更都会生成结构化记录，告别传统开发「改了哪里、为什么改、谁改的」无迹可寻的乱象，大幅降低项目维护成本。

2.3 轻量化无侵入、兼容性极强

OpenSpec 不绑定编程语言、不强制重构老项目、不替换现有 IDE 和 AI 工具，支持 Cursor、Copilot 等主流 AI 编码助手，可无缝接入新旧项目，零学习门槛即可落地。

2.4 沉淀项目资产，实现能力复用

所有落地的功能规范、设计方案都会归档沉淀为项目资产，新成员接手项目、后续迭代优化时，无需通读全量代码，通过规范文件即可快速掌握项目全貌，实现团队能力沉淀。

三、OpenSpec 标准文件目录结构

执行 openspec init 初始化项目后，会自动生成标准化目录结构，整体结构极简、逻辑清晰，所有 AI 协作、变更管理、规范沉淀均围绕该目录展开，完整结构及释义如下：

Plain 复制代码

openspec/
├── specs/                # 核心规范主库（项目最终唯一可信数据源）
│   └── [业务模块]/
│       └── spec.md       # 已落地稳定功能的标准规范、业务逻辑、代码约束
├── changes/              # 迭代变更目录（所有待开发/开发中功能）
│   └── [变更功能名称]/   # 每个功能迭代独立文件夹
│       ├── proposal.md   # 变更提案（必选）：开发背景、需求价值、变更范围
│       ├── tasks.md      # 任务清单（必选）：AI 编码任务拆解、验收明细
│       ├── design.md     # 技术设计（可选）：复杂功能专属架构、实现方案
│       └── specs/        # 规范增量目录（核心）：存放本次迭代规范变更
│           └── [业务模块]/
│               └── spec.md # 增量规范，标记 ADDED/MODIFIED/REMOVED 变更类型
├── changes/archive/      # 历史迭代归档目录（首次执行归档命令时自动创建）
├── AGENTS.md             # AI 工作流指南（核心规则文件）
└── project.md            # 项目全局上下文（技术栈、整体架构、全局规范）

目录核心逻辑拆解

specs 目录 ：存放已稳定落地的功能规范，是项目的唯一可信标准，迭代完成后最终归档至此，长期复用。
changes 目录 ：存放正在迭代、未上线的功能变更，每个功能独立隔离，互不干扰，开发完成并执行归档命令后，对应迭代文件夹会迁移至 archive 目录统一留存。
project.md：项目全局说明书，记录项目基础信息、技术栈、架构、全局编码规范，是 AI 认知项目的基础。
changes 子级 specs 增量目录：OpenSpec 核心设计之一，存放单次迭代的规范增量变更，通过 ADDED/MODIFIED/REMOVED 标记规范变动内容，是实现规范迭代、增量更新的核心载体，复杂功能可搭配可选的 design.md 完成方案设计。

四、OpenCode 实操：从零上手 OpenSpec 完整流程

OpenSpec 提供简洁的 CLI 命令和 AI 斜杠指令，全程轻量化操作，无需复杂配置。下面是完整的安装、初始化、核心指令实操流程，可直接复刻使用。

4.1 全局安装 OpenSpec

通过 npm 全局安装最新稳定版，适配所有前端、后端、全栈项目：

Plain 复制代码

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

安装完成后，全局生效 openspec 命令，可在任意项目目录执行操作。

4.2 项目初始化：openspec init

进入目标项目根目录，执行初始化命令：

Plain 复制代码

openspec init

执行后自动完成三件事：

生成上述标准化 openspec 目录结构；
自动创建 project.md、AGENTS.md 核心配置文件；
交互询问当前使用的 AI 工具（Cursor/Copilot 等），自动适配对应配置。

初始化完成，项目即接入规范驱动开发流程，无需额外配置。

4.3 五大核心 Slash Commands 实操

OpenSpec 核心通过 5 个官方标准 Slash Commands，完整覆盖「需求调研-方案提案-代码落地-规范校验-迭代归档」全开发闭环，所有指令统一使用冒号分隔格式，适配主流 OpenCode 场景。

为方便大家精准选用指令，先附上核心场景适配对照表：

业务场景	推荐指令	核心优势
需求模糊、需前期调研梳理可行性	/opsx:explore	自由对话模式，不生成任何变更文件，仅做调研分析
需求明确、快速启动迭代开发	/opsx:propose	一键生成标准化提案、任务清单，快速落地开发规划
复杂功能、需要分步审核迭代	/opsx:new + /opsx:continue	拆分文档分步生成，支持逐份审查、精准管控
功能上线、迭代收尾沉淀资产	/opsx:archive	增量合并规范、归档迭代记录，完成闭环沉淀

1. /opsx:explore 需求探索与调研

适用于需求模糊、需要前期调研梳理的场景。指令执行后，AI 会自动分析项目现有代码、架构、业务逻辑，梳理需求可行性、技术难点、依赖关系，输出完整的需求调研文档，帮开发者理清开发思路，避免盲目开发。

2. /opsx:propose 生成需求提案

需求明确后执行该指令，AI 会自动在 changes 目录下创建当前功能的独立文件夹，并一次性生成 4 份标准迭代文件，完整承载一次 AI 开发全流程规范，四份文件各司其职、相互联动，彻底杜绝需求与落地脱节问题，下面逐一说明每份文件的核心内容与作用：

1. proposal.md（变更提案文件）

本次迭代的需求总纲、立项依据。主要记录开发背景、业务痛点、需求价值、变更范围、上下游依赖、兼容风险、预期落地效果。作为团队与 AI 的共识基准，所有开发工作都必须围绕该提案展开，不允许脱离提案范围自由开发。

2. tasks.md（任务拆解清单）

可落地的精细化执行清单。AI 会根据提案内容，自动拆解为粒度清晰的开发任务、调试任务、自测任务，明确每一项任务的执行主体、验收标准、完成边界，将抽象需求转化为可执行、可校验的落地步骤，避免漏功能、少逻辑。

3. design.md（技术设计方案）

可选的技术架构文档，复杂迭代自动生成、简单迭代可省略。用于记录整体技术方案、模块拆分、接口设计、数据结构变更、兼容策略、异常处理方案，解决复杂功能"怎么技术落地"的问题，保障架构统一、代码优雅。

4. specs/[模块]/spec.md（增量规范文件）

OpenSpec 最核心的增量资产文件。用于记录本次迭代的规范变更明细，通过 ADDED（新增）、MODIFIED（修改）、REMOVED（删除）三种标记，精准定义业务规则、代码约束、交互逻辑、校验规则等，是最终合并到项目核心 specs 库、成为项目永久标准的唯一依据。

3. /opsx:apply 规范落地与代码实现

提案确认通过后，执行该指令启动正式开发。AI 会基于已有提案、项目规范、AGENTS.md 约束，自动拆解任务、输出技术设计方案、生成合规代码，同时同步更新 tasks.md 任务清单，全程按照规范落地，杜绝无效编码。

4. /opsx:archive 迭代归档沉淀

功能开发、测试无误后，执行归档指令完成迭代收尾。该指令不会简单同步文件，而是执行精准增量合并 ：将 changes 目录下本次迭代的 specs 增量规范（新增/修改/删除内容）合并至项目核心 specs 主库，更新项目可信标准；同时将完整迭代文件夹自动移动至 changes/archive/ 目录归档留存，而非直接清理文件，完整保留迭代历史、决策过程与开发记录，完成标准化开发闭环。

五、AI Coding 时代，程序员的进化路径

AI 不会替代程序员，但会淘汰只会单纯写代码的程序员 。随着 AI Coding 普及与 OpenSpec 规范驱动模式落地，程序员的核心工作与核心竞争力已经彻底迭代：从过去比拼编码速度、语法熟练度，转变为比拼需求拆解能力、规范定义能力、工程架构能力与 AI 管控能力。依托 SDD 开发思想，手写编码不再是核心工作，规范、设计、调度、沉淀才是核心价值。AI 时代程序员的成长路径，可以清晰分为三个递进阶段，全程适配 AI 开发范式：

第一阶段：AI 辅助编码执行者（旧式思维残留）

这是大部分开发者当下所处的过渡阶段，虽已使用 AI 工具，但思维仍停留在传统开发模式。日常工作依旧以「产出代码」为核心，依赖 AI 辅助完成 CRUD、模板代码、简单 Bug 修复，本质只是把「手动敲代码」换成了「AI 生成代码、人工改代码」。

这类开发者没有规范意识、没有前置设计习惯，依然是「先编码、后补逻辑、出错再改」。AI 只是提升了编码速度，但解决不了需求模糊、代码随意、迭代混乱、无法沉淀的问题。效率有提升，但工程质量、协作能力、技术沉淀几乎没有成长，也是 AI 时代最容易被边缘化的群体。

第二阶段：AI 规范调度者（标准 AI 开发思维）

熟练落地 OpenSpec + SDD 规范驱动开发后，开发者正式进入 AI 时代的标准形态，彻底告别以编码为核心的工作模式。

此时程序员的核心工作完全转移：不再逐行手写业务代码、不再反复调试基础逻辑、不再被动对接模糊需求。工作重心转变为：需求梳理与边界定义、规范文档撰写、技术方案设计、AI 行为约束、代码结果校验、迭代流程管控。

开发者通过 OpenSpec 的 proposal、spec 规范前置定义所有业务约束，让 AI 严格按照标准落地代码，AI 全权承接机械、重复、模板化的编码工作，人类只做「决策、定义、审核、把控」。从「代码搬运者」升级为「AI 开发调度者」，彻底解决 AI 编码混乱、实现不一致、返工率高的问题。

第三阶段：工程资产架构者（AI 时代高阶形态）

这是 AI 时代程序员的终极核心竞争力形态。在熟练规范调度的基础上，开始依托 OpenSpec 体系沉淀团队工程资产、搭建标准化开发体系。

开发者不再局限于单一功能迭代，而是通过 specs/ 核心规范库 沉淀团队统一的业务标准、编码范式、架构规则、验收标准；通过 changes/archive/ 完整沉淀每一次技术决策、方案取舍、问题复盘，形成团队可复用的设计模式与工程经验库。

核心能力从「单点开发管控」升级为「体系搭建与能力复用」：负责业务抽象、技术架构迭代、团队开发规范统一、AI 工程体系优化。这类开发者不依赖编码速度，依靠长期沉淀的工程资产与架构思维形成不可替代性，是企业 AI 工程化落地的核心人才。