开发者们似乎陷入了一种既兴奋又焦虑的怪圈。我们拥有了像Claude Code、Cursor这样强大的智Neng伙伴，它们Neng瞬间生成大段代码，但随之而来的往往是“需求漂移”和“不可预测性”。你让AI修个bug，它可Neng顺手重构了半个模块；你想要加个功Neng，它可Neng把原本清晰的逻辑搞得一团糟。

这时候，OpenSpec 应运而生。这不仅仅是一个工具，geng是一套让AI与人类协作回归理性的“契约”。今天我们就来深入剖析如何使用OpenSpec，让你的AI开发流程从“狂野西部”变成井井有条的现代化工地。

初识OpenSpec：不仅仅是文档，而是“真相来源”

在深入操作之前，我们必须先理解OpenSpec的核心哲学。hen多团队习惯把文档写在Wiki里或者散落在Notion的各个角落，但AI代码助手往往kan不到这些，或者kan到了也理解不深。OpenSpec的核心理念是：规范即真相。

它通过一个轻量级的CLI工具和一套严格的文件结构，将你的项目规范、技术栈约束、架构设计全部“代码化”。它把“系统当前的行为”和“提议的变geng”彻底分离开来。打个比方，它不会建议你把房子拆了重盖，而是教你如何在不破坏老房子的前提下精准地把新设施嵌进去。这种开放性质至关重要，因为它确保规范是一个工具无关的产物，允许使用不同AI助手的不同团队在单一、共享的真相来源上协作。

第一步：环境准备与安装

工欲善其事，必先利其器。OpenSpec是基于Node.js构建的，所以 请确保你的开发环境Yi经准备就绪。你需要Node.js版本在18以上。

安装过程非常简单，就像安装任何全局npm包一样。打开你的终端，执行以下命令：

# 使用 npm 进行全局安装
npm install -g @fission-ai/openspec@latest
# Ru果你偏爱 pnpm
pnpm install -g @fission-ai/openspec@latest
# 或者是 yarn 的用户
yarn global add @fission-ai/openspec@latest

安装完成后别急着动手，先验证一下是否成功：

openspec --version

Ru果终端乖乖输出了版本号，恭喜你，引擎Yi经启动了。

第二步：初始化你的项目

进入你的项目根目录，我们需要在这里建立一个“OpenSpec基地”。运行初始化命令：

cd your-project
openspec init

这一步操作会在你的项目中生成两个至关重要的目录：specs/ 和 changes/。

specs/这是你的“主规范库”。它描述了系统当前的行为，比如 specs/auth/ 定义了认证逻辑，specs/payments/ 定义了支付流程。这是项目唯一可信源。

changes/这是“战场”。所有的待实现变geng提案dou会在这里孵化，每个变gengdou有自己的文件夹。

此外你还会kan到一个 project-context.md 文件。这个文件是AI的大脑皮层，你需要在这里填入项目的技术栈、架构约束、代码规范等关键信息。Ru果你的团队没有强制要求OpenSpec，或者混用了其他工具，维护好这个文件就显得尤为重要，甚至比维护 CLAUDE.md geng合适。

第三步：掌握核心工作流

OpenSpec的魅力在于它定义了一套清晰的生命周期：提案 -> 审查 -> 实施 -> 归档。我们通过一个具体的例子——比如“添加用户认证功Neng”——来走一遍这个流程。

1. 发起提案

一切始于一个想法。在OpenSpec中，我们不直接写代码，而是先写提案。执行以下命令：

openspec new change user-auth

这行命令会在 openspec/changes/user-auth/ 下生成一套完整的骨架文件，包括 proposal.mddesign.mdtasks.md以及 specs/ 目录下的增量规范。

这时候，你需要与AI协作，通过斜杠命令来填充这些文档。告诉AI你的需求：“我们需要一个支持GitHub和Google登录的认证系统。”AI会根据 project-context.md 生成详细的提案文档。

2. 审查与锁定意图

这是人类介入的关键时刻。不要盲目信任AI生成的第一版内容。你需要打开 proposal.md 和 design.md，仔细检查逻辑是否通顺，技术方案是否合理。

Ru果发现偏差，直接修改文档，然后让AI重新生成。这个过程是一个反馈循环，直到你确信这份文档准确反映了你的意图。一旦通过审查，你就“锁定”了意图，防止后续开发过程中AI跑偏。

3. 验证与应用

提案定稿后进入实施阶段。使用命令：

openspec validate user-auth

这一步会检查格式和规范是否完备。Ru果验证通过就Ke以让AI开工了：

/opsx:apply user-auth

此时AI助手会严格根据 tasks.md 和 specs/ 中的规范来编写代码。因为有了明确的约束，AI生成的代码将具有高度的可预测性，不再是“盲盒”。

4. 测试与调试

代码生成后运行测试。Ru果测试未通过进入调试修复阶段，然后 测试，直到通过。

5. 归档

这是Zui后一步，也是Zui具仪式感的一步。当功Neng完美运行后执行：

openspec archive user-auth

这个操作会触发一系列自动化动作：将 changes/user-auth/ 下的增量规范合并进主 specs/ 目录，geng新“真相来源”，并将整个变geng文件夹移动到 archive/ 中作为历史记录保留。至此，新功Neng正式成为系统的一部分。

目录结构详解：OpenSpec的骨架

为了让你geng直观地理解，我们来kan一下一个成熟项目的OpenSpec目录长什么样：

your-project/
├── .openspec/                      # 内部配置
│   └── config.json
│
├── openspec/                       # 核心工作区
│   ├── AGENTS.md                   # AI代理指导文件
│   ├── project.md                  # 项目上下文
│   │
│   ├── changes/                    # 活跃的变geng提案
│   │   ├── feature-auth/           # 变geng：用户认证
│   │   │   ├── .openspec.yaml      # 元数据
│   │   │   ├── proposal.md         # 提案文档
│   │   │   ├── design.md           # 技术设计
│   │   │   ├── tasks.md            # 任务清单
│   │   │   └── specs/              # Delta Specs
│   │   │       └── auth/
│   │   │           └── spec.md
│   │   │
│   │   └── feature-payment/        # 变geng：支付功Neng
│   │       └── ...
│   │
│   ├── specs/                      # Main Specs
│   │   ├── auth/                   # Yi归档：认证Neng力
│   │   │   └── spec.md
│   │   ├── user-management/        # Yi归档：用户管理
│   │   │   └── spec.md
│   │   └── payment/                # Yi归档：支付Neng力
│   │       └── spec.md
│   │
│   └── archive/                    # 历史归档
│       ├── ---feature-auth/
│       │   ├── proposal.md
│       │   ├── design.md
│       │   ├── tasks.md
│       │   └── specs/
│       └── ---feature-payment/
│           └── ...
│
├── .claude/                        # Claude Code 配置
│   ├── commands/
│   │   └── openspec/
│   │       ├── proposal.md
│   │       ├── apply.md
│   │       └── archive.md
│   └── skills/
│       └── openspec/
│           └── SKILL.md

关于 archive/ 目录的特殊意义

不要小kan这个归档目录。它不仅仅是一个垃圾桶，而是一个存放Yi归档历史变geng的宝库。它保留了完整的决策历史和演进记录。当你在半年后突然想不起“为什么当时认证模块要这么设计”时这里的 proposal.md 和 design.md 会给你答案。

Commands 与 Skills：AI的左右手

OpenSpec与AI编辑器的深度集成，主要通过 Commands 和 Skills 两种方式实现。理解它们的区别，Neng让你事半功倍。

Commands：明确的指令

Commands 就像是给AI下的死命令。当你输入 /opsx:proposal 时AI会立即加载对应的指令集并执行。

触发方式通过斜杠命令，如 /opsx:proposal。

加载方式即时加载，随叫随到。

适用场景当你明确知道要Zuo什么操作时使用。

它们通常存放在 .claude/commands/openspec/ 目录下。

Skills：智Neng的上下文感知

Skills 则geng加高级和智Neng。它是一种懒加载机制。只有当AI判断你的请求与某个技Neng相关时才会加载完整的技Neng定义。

触发方式自动识别或手动调用。

加载方式先加载元数据，确认匹配后再加载完整内容。

适用场景需要上下文感知的复杂智Neng行为。

这种设计非常巧妙，因为它避免了向AI的上下文窗口塞入过多无关信息，保持了对话的轻量级。

Zui佳实践：如何写出高质量的提案

工具再好，还得kan人怎么用。在OpenSpec的工作流中，proposal.md 的质量直接决定了代码的质量。

✅ 推荐Zuo法：详尽且结构化

不要只写一句话。一个好的提案应该包含背景、问题陈述、备选方案等。

### Background
当前系统缺乏用户认证机制，导致数据裸奔，无法追踪责任人。
### Problem Statement
我们需要构建一个安全可靠的认证系统，支持：
- 用户名密码登录
- 第三方 OAuth 
- 会话管理
### Alternatives Considered
1. **自建系统**：成本高，维护难。
2. **Auth0**：功Neng全但贵。
3. **Keycloak**：开源免费，协议支持丰富。✓ Yi选

❌ 避免Zuo法：模糊且简略

添加用户登录功Neng。

这种模糊的指令只会让AI瞎猜，Zui终生成的代码大概率不符合你的预期。

高阶功Neng：双重规格系统

OpenSpec Zui精妙的设计之一就是 Delta Specs vs Main Specs。

在开发过程中，我们修改的是 changes/ 目录下的 Delta Specs。只有当功Neng完成并归档后这些增量才会合并进 specs/ 主目录。这种机制确保了主规范库始终处于“可发布”的状态，而开发中的混乱被隔离在 changes/ 中。

此外你还Ke以通过 openspec config profile 来管理不同的配置文件，或者通过 openspec update 来geng新工具本身，确保你始终使用Zui新的功Neng。

让AI成为你的副驾驶，而不是随机数生成器

OpenSpec 不仅仅是一个CLI工具，它代表了一种新的开发范式。在这个范式里人类负责定义“Zuo什么”和“为什么Zuo”，而AI负责“怎么Zuo”。

通过规范驱动，我们将AI编程从“黑盒魔法”变成了“白盒工程”。Ru果你厌倦了不断修复AI制造的意外渴望一种可控、可预测、可追溯的开发体验，那么现在就打开终端，运行 npm install -g @fission-ai/openspec@latest，开始你的OpenSpec之旅吧。

---