跳到主要内容

OpenSpec - AI 编程助手的规范驱动开发工具

📋 项目概况​

OpenSpec 是一个开源的规范驱动开发工具，专门为 AI 编程助手设计。它通过在编写任何代码之前建立明确的规范，使人类和 AI 编程助手在工作目标上达成一致，从而提供确定性和可审查的输出结果。

核心价值​

  • 意图锁定：在代码编写前明确约定要构建什么
  • 确定性输出：减少 AI 编程助手的不可预测性
  • 可审查性：所有变更都有明确的规范依据
  • 团队协作：人类和 AI 利益相关者在工作开始前就规范达成一致
  • 轻量级：简单工作流，无需 API 密钥，最小化设置

🔍 核心特性​

1. 轻量级工作流​

  • 简单流程：提案 → 审查 → 实施 → 归档
  • 无需 API 密钥：本地运行，无外部依赖
  • 最小化设置：几分钟即可完成初始化

2. 结构化变更管理​

openspec/
├── specs/              # 当前真相（源规范）
│   └── [domain]/
│       └── spec.md
└── changes/            # 提议更新
    └── [change-name]/
        ├── proposal.md    # 变更提案
        ├── tasks.md       # 实施任务清单
        ├── design.md      # 技术决策（可选）
        └── specs/         # 规范增量
            └── [domain]/
                └── spec.md

3. 跨工具兼容性​

  • 原生支持工具：Claude Code、CodeBuddy、Cursor、OpenCode、Qoder 等
  • 通用支持：通过 AGENTS.md 存根支持所有其他 AI 助手
  • 斜杠命令：支持的工具可使用快捷命令

🚀 快速开始​

安装要求​

  • Node.js >= 20.19.0

安装步骤​

  1. 全局安装 CLI

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

  2. 项目初始化

    cd my-project
    openspec init

  3. 创建第一个变更

    # 向 AI 助手请求创建变更提案
    "Create an OpenSpec change proposal for adding profile search filters"

    # 或使用斜杠命令（支持的工具）
    "/openspec:proposal Add profile search filters"

核心工作流​

  1. 起草变更提案 - 捕获你想要的规范更新
  2. 审查与对齐 - 与 AI 助手一起审查提案直到达成一致
  3. 实施任务 - 参考约定规范实施任务
  4. 归档与更新 - 将批准的更新合并回源真相规范

🔧 命令参考​

基本命令​

openspec list                    # 查看活动变更文件夹
openspec view                    # 规范和变更的交互式仪表板
openspec show <change>           # 显示变更详情（提案、任务、规范更新）
openspec validate <change>       # 检查规范格式和结构
openspec archive <change> [-y]   # 将完成的变更移入 archive/

项目管理​

openspec update                  # 更新 AI 指导和斜杠命令绑定
openspec init                    # 在项目中初始化 OpenSpec

📊 与同类工具对比​

vs. spec-kit​

OpenSpec 优势：

  • 双文件夹模型（specs/ 当前真相，changes/ 提议更新）保持状态和差异分离
  • 在修改现有功能或多规范更新时表现更好
  • 跨规范更新和演进功能的结构更清晰

spec-kit 优势：

  • 绿地/0→1 项目表现更强
  • 新功能开发体验更佳

vs. Kiro.dev​

OpenSpec 优势：

  • 将每个功能的所有变更组织在一个文件夹中
  • 更容易跟踪相关规范、任务和设计
  • 功能跟踪更加集中化

Kiro.dev 特点：

  • 更新分布在多个规范文件夹
  • 更灵活的文件组织方式

vs. 无规范开发​

无规范的问题：

  • AI 编程助手从模糊提示生成代码
  • 经常遗漏需求或添加不需要的功能
  • 输出结果不可预测

OpenSpec 价值：

  • 在编写代码前就约定期望行为
  • 提供可预测性和可审查性
  • 减少沟通成本和返工

🏗️ 文件格式规范​

增量格式（Delta Format）​

增量文件显示规范如何变化：

# ADDED Requirements - 新功能
### Requirement: 双因素认证
系统必须在登录期间要求第二因素。

# MODIFIED Requirements - 改变行为（包含完整更新文本）
### Requirement: 用户认证
系统在成功登录时应颁发 JWT。

# REMOVED Requirements - 弃用功能
### Requirement: 旧认证方式
已弃用的认证方法描述。

格式要求​

  • 使用 ### Requirement: <名称> 作为标题
  • 每个需求至少需要一个 #### Scenario: 块
  • 需求文本中使用 SHALL/MUST

示例文件结构​

AI 生成的规范（openspec/specs/auth/spec.md）：

# 认证规范

## 目的
认证和会话管理。

## 需求

### Requirement: 用户认证
系统在成功登录时应颁发 JWT。

#### Scenario: 有效凭据
- 当用户提交有效凭据时
- 那么返回 JWT

AI 生成的变更增量（openspec/changes/add-2fa/specs/auth/spec.md）：

# 认证增量

## ADDED 需求

### Requirement: 双因素认证
系统在登录期间必须要求第二因素。

#### Scenario: 需要 OTP
- 当用户提交有效凭据时
- 那么需要 OTP 挑战

AI 生成的任务（openspec/changes/add-2fa/tasks.md）：

## 1. 数据库设置
- [ ] 1.1 向用户表添加 OTP 密钥列
- [ ] 1.2 创建 OTP 验证日志表

## 2. 后端实现
- [ ] 2.1 添加 OTP 生成端点
- [ ] 2.2 修改登录流程以要求 OTP
- [ ] 2.3 添加 OTP 验证端点

## 3. 前端更新
- [ ] 3.1 创建 OTP 输入组件
- [ ] 3.2 更新登录流程 UI

👥 团队采用策略​

采用步骤​

  1. 初始化 OpenSpec - 在仓库中运行 openspec init
  2. 从新功能开始 - 要求 AI 将即将进行的工作捕获为变更提案
  3. 增量增长 - 每个变更归档到记录系统的活规范中
  4. 保持灵活性 - 不同团队成员可以使用 Claude Code、CodeBuddy、Cursor 或任何 AGENTS.md 兼容工具，同时共享相同的规范

最佳实践​

  1. 规范先行：总是在编写代码前明确规范
  2. 小步快跑：将大功能分解为小的、可管理的变更
  3. 及时归档：完成实施后立即归档变更
  4. 团队同步：当有人切换工具时运行 openspec update

🔗 与现有生态系统集成​

与 Claude Code 集成​

OpenSpec 为 Claude Code 提供：

  • 原生斜杠命令支持（/openspec:proposal、/openspec:apply、/openspec:archive）
  • 自动上下文注入
  • 无缝的工作流集成

与其他 AI 工具集成​

通过标准的 AGENTS.md 机制，OpenSpec 可以与任何支持该标准的 AI 编程助手协作。

🎯 使用场景​

适用场景​

  • 现有功能修改：特别是当更新跨越多个规范时
  • 团队协作项目：需要明确规范和可审查性的项目
  • 复杂功能开发：需要详细规划和分解的功能
  • 质量要求高的项目：需要确定性和可追溯性的项目

不太适合的场景​

  • 简单原型开发：过度工程化
  • 单人快速项目：可能增加不必要的开销
  • 探索性编程：需要灵活性和快速迭代的项目

🔮 发展前景​

OpenSpec 代表了 AI 辅助软件开发的重要趋势：

  1. 从对话到规范：将模糊的需求转化为明确的规范
  2. 从不可预测到可确定：通过规范驱动提高 AI 输出的可预测性
  3. 从个人到团队：支持多人协作的 AI 开发工作流
  4. 从临时到结构化：建立可持续的知识积累和管理机制

📚 相关资源​

🔗 相关文档​

最后更新时间：2025-12-19