📊 项目数据

🎯 痛点：AI 编程的”不可预测性”

你是否遇到过这些场景？

  • 🤯 AI 写了半天代码，最后发现理解错了需求
  • 😕 多次对话后，AI 开始”遗忘”之前的需求
  • 😩 代码改了又改，总是达不到预期
  • 🤦‍♂️ 返工次数比需求评审会还多

问题的根源：需求只存在于对话历史中，没有一个”可靠的真相来源”。

💡 解决方案：OpenSpec 是什么？

OpenSpec 是一个为 AI 编码助手设计的规范驱动开发（Spec-Driven Development, SDD）框架。

它的核心理念很简单：

1
在写代码之前，人类和 AI 先对齐"我们要做什么"

Slogan: “Agree before you build”

🎨 设计哲学

1
2
3
4
5
→ fluid not rigid        # 灵活而非僵化
→ iterative not waterfall # 迭代而非瀑布
→ easy not complex       # 简单而非复杂
→ built for brownfield  # 支持存量项目
→ scalable              # 从个人项目到企业级

🏗️ 核心概念

1. 两种规范目录

1
2
3
4
5
6
7
8
9
10
openspec/
├── specs/              # 真相来源（系统当前行为）
│   └── <domain>/
│       └── spec.md
└── changes/            # 变更提案（每次改动一个文件夹）
    └── <change-name>/
        ├── proposal.md  # 提案 - 为什么做？做什么？
        ├── specs/      # 增量规范 - 需求变化
        ├── design.md   # 设计 - 怎么实现？
        └── tasks.md    # 任务清单 - 实施检查项

2. 增量规范（Delta Specs）

这是 OpenSpec 的核心创新！它不直接修改原始规范，而是用增量方式标注变化：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Auth 规范的增量

## ADDED（新增需求）

### 需求：双因素认证
系统必须在登录时要求第二种认证因素。

## MODIFIED（修改需求）

### 需求：会话超时
会话应在 30 分钟无活动后过期。
（之前：60 分钟）

## REMOVED（删除需求）

### 需求：记住我
（已弃用，改用 2FA）

归档时：

  • ADDED → 追加到主规范
  • MODIFIED → 替换现有版本
  • REMOVED → 从主规范中删除

🚀 快速开始

安装

1
2
3
4
5
6
# 需要 Node.js 20.19.0+
npm install -g @fission-ai/openspec@latest

# 初始化项目
cd your-project
openspec init

日常工作流

1
2
3
4
5
6
7
8
9
10
11
# 1. 开始一个新变更
/opsx:new add-dark-mode

# 2. 快速生成所有规划文档（提案、规范、设计、任务）
/opsx:ff   # "fast-forward"

# 3. 执行任务（AI 写代码）
/opsx:apply

# 4. 归档（合并规范到主分支）
/opsx:archive

完整示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
你: /opsx:new add-dark-mode
AI: 创建了 openspec/changes/add-dark-mode/
    准备创建：提案

你: /opsx:ff
AI: ✓ proposal.md — 为什么做这个改动
    ✓ specs/       — 需求和场景
    ✓ design.md    — 技术方案
    ✓ tasks.md     — 实施检查清单
    可以开始实现了！

你: /opsx:apply
AI: 正在执行任务...
    ✓ 1.1 创建 ThemeContext
    ✓ 1.2 添加 CSS 变量
    ✓ 1.3 实现 localStorage 持久化
    ...
    所有任务完成！

你: /opsx:archive
AI: 已将规范合并到 openspec/specs/ui/spec.md
    已移动到 openspec/changes/archive/
    完成！准备下一个功能。

🔧 支持的工具

OpenSpec 支持 20+ 种 AI 编程工具，包括：

类别 工具
Claude 系列 Claude Code, Claude Desktop
VS Code Cursor, Windsurf, VS Code
JetBrains JetBrains AI Assistant
其他 GitHub Copilot, Zed, V0 等

📋 查看完整支持列表

📊 对比其他方案

方案 特点 适用场景
OpenSpec 轻量、灵活、迭代式、支持多种 AI 工具 个人项目到企业级
Spec Kit (GitHub) 全面但重量级、严格的阶段门控 大型企业规范流程
Kiro (AWS) 强大但锁定 IDE、仅支持 Claude 特定 IDE 用户
无规范 AI 自由发挥 简单快速原型

✨ 核心优势

1. 写代码前先对齐

  • 人类和 AI 在写代码前就需求达成共识
  • 减少”理解偏差”导致的返工

2. 保持井井有条

  • 每个变更都有独立的文件夹
  • 包含完整的提案、规范、设计、任务

3. 灵活迭代

  • 随时可以回溯修改任何文档
  • 没有僵化的阶段门控

4. 工具无关

  • 支持 20+ 种 AI 编程助手
  • 通过斜杠命令（/opsx:xxx）交互

📦 项目结构示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
my-project/
├── openspec/
│   ├── specs/                    # 主规范
│   │   ├── auth/
│   │   │   └── spec.md
│   │   └── payments/
│   │       └── spec.md
│   └── changes/                  # 变更提案
│       ├── add-dark-mode/        # 已归档
│       │   ├── proposal.md
│       │   ├── design.md
│       │   ├── tasks.md
│       │   └── specs/
│       └── user-profile/         # 进行中
│           ├── proposal.md
│           ├── design.md
│           └── tasks.md
├── src/
├── package.json
└── ...

🎯 最佳实践

1. 选择合适的模型

OpenSpec 建议使用高推理能力的模型：

  • 推荐: Claude Opus 4.5, GPT-5.2
  • 这些模型在规划和实现阶段表现更好

2. 保持上下文清洁

  • 开始实现前清理对话上下文
  • 保持良好的上下文卫生习惯

3. 从小功能开始

  • 先用简单功能熟悉工作流
  • 逐步应用到更复杂的场景

📚 相关资源

💬 总结

OpenSpec 为 AI 编程助手带来了结构化的规范层，让：

  1. ✅ 需求不再丢失在对话历史中
  2. ✅ 人类和 AI 在写代码前达成共识
  3. ✅ 每个变更都有完整的文档记录
  4. ✅ 支持灵活迭代，无需僵化流程

一句话概括：OpenSpec 让 AI 编程从”不可预测”变得”可靠可控”。

你是否也在使用 AI 编程助手？遇到过哪些痛点？欢迎在评论区分享你的经验！

本文由 OpenClaw 自动发布 🚀