OpenSpec Coding 从零上手使用

OpenSpec Coding

AI编程助手虽功能强大，但当需求仅存在于聊天记录中时，其行为往往难以预测。OpenSpec引入了一种轻量级的规范工作流，在实现之前锁定意图，为您提供确定性和可审查的输出结果。

OpenSpec 作为一个为AI编码助手设计的规范驱动开发工具，核心优势：

  • 🚀 轻量级：无需API密钥，最小化设置
  • 🔄 现有项目优先：特别适合修改现有功能 (1→n)
  • 📋 变更跟踪：提案、任务和规范差异的完整生命周期管理
  • 🤖 AI工具集成：支持多种主流AI编码助手

为什么需要 OpenSpec Coding

传统AI编码助手的问题：
当您使用AI编码助手时，是否遇到过以下情况：

  • ❌ AI根据模糊提示生成不符合需求的代码
  • ❌ 遗漏重要功能要求
  • ❌ 添加了不必要的功能
  • ❌ 代码行为不可预测

OpenSpec的解决方案
OpenSpec通过规范驱动开发解决这些问题：

  • ✅ 明确共识：在编码前确定所有要求
  • ✅ 结构化变更：所有相关文档集中管理
  • ✅ 可审查输出：AI根据明确规范生成代码
  • ✅ 版本控制：完整追踪所有变更历史

安装配置 OpenSpec

  1. 准备工作
1
2
3
4
5
6
7
8
9
10

# 检查Node.js版本（需要 >= 20.19.0）
node --version

# 全局安装OpenSpec
npm install -g @fission-ai/openspec@latest

# 验证安装情况
openspec --version

  1. 初始化项目
1
2
3
4
5
6
7
8

# 创建一个新目录
mkdir my-project
cd my-project

# 初始化OpenSpec项目
openspec init

紧接着完善下project.md文件，示意指令例如：

1
2
Please read openspec/project.md and help me fill it out
with details about my project, tech stack, and conventions

这一步很重要，会自动分析你的代码，填写：

  • 项目用途
  • 技术栈
  • 代码规范
  • 领域知识
  • 约束条件
    它让AI充分理解你的项目背景。

OpenSpec 核心概念

  1. 双文件夹模型
    OpenSpec使用两个主要目录：
1
2
3
4
5
6
7
8
9
10
11
12

openspec/
├── specs/          # 当前真理源规范
│   └── auth/
│       └── spec.md
├── changes/        # 变更提案
│   └── feature-name/
│       ├── proposal.md
│       ├── tasks.md
│       └── specs/
└── project.md      # 项目级别约定

  • 📄 proposal.md
    为什么做这个功能？
    要改哪些地方？
    影响哪些模块？
    向后兼容吗？
  • 📄 design.md
    技术决策：为什么用UserDefaults而不是SwiftData？
    数据存储：为什么用”分钟”而不是”秒”？
    算法说明：树木阶段如何计算？
  • 📄 tasks.md
    44个具体任务
    分成9个阶段
    包含8个测试任务
  • 📁 specs/
    4个能力的规范增量
    timer-session（计时会话）
    tree-visualization（树木可视化）
    statistics-tracking（统计追踪）
    data-persistence（数据持久化）
  1. 规范格式
    规范使用Markdown格式，包含：
1
2
3
4
5
6
7
8
9
10
11

# Auth Specification
## Purpose
Authentication and session management.
## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT on successful login.
#### Scenario: Valid credentials
- WHEN a user submits valid credentials
- THEN a JWT is returned

  1. 变更差异
    变更通过”差异”格式显示：
1
2
3
4
5
6
7
8
9
10

# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.
#### Scenario: OTP required
- WHEN a user submits valid credentials
- THEN an OTP challenge is required


完整工作流程

OpenSpec遵循四步工作流程：

1️. 起草变更提案
AI会自动创建：
openspec/changes/feature-name/proposal.md - 变更说明
openspec/changes/feature-name/tasks.md - 实施任务
openspec/changes/feature-name/specs/ - 规范差异

1
2
3
4
5

# 使用AI助手或直接创建
/openspec:proposal Add profile search filters


2️. 审核与对齐
与AI助手讨论，直到所有人同意：
您：能否为角色和团队过滤器添加验收标准？
AI：我来更新规范差异，添加角色和团队过滤器的场景。

1
2
3
4
5
6
7
8

# 查看变更详情
openspec show feature-name

# 验证规范格式
openspec validate feature-name


3️. 实施任务

1
2
3
4

# 开始实施
/openspec:apply feature-name

4️. 归档与更新规范

1
2
3
4

# 归档完成的变更
openspec archive feature-name --yes

OpenSpec适合什么场景？

  1. 改进现有项目（1→n）
    OpenSpec专门为此设计。它的双文件夹模型（specs/存放当前状态，changes/存放提议更新）让复杂的功能演进变得清晰可管理。
  2. 需要高质量的场景
    当你需要：
  • 准确的实现
  • 清晰的文档
  • 可追溯的决策
  • 团队协作
    OpenSpec能提供规范化的支持。
  1. 使用AI编码助手
    OpenSpec的核心就是帮助AI更好地理解和实现你的需求。如果你已经在用Claude Code、Cursor等工具，OpenSpec会让你的效率翻倍。