OpenSpec 实践指南：让 AI 编码助手"靠谱"起来OpenSpec 实践指南：让 AI 编码助手"靠谱"起来前

OpenSpec 实践指南：让 AI 编码助手"靠谱"起来

40K+ Stars！这个开源框架正在重新定义 AI 编码的工作方式。

前言

你有没有遇到过这种情况：

让 AI 写代码，结果跑偏了，实现的功能和你要的不一样
AI 生成的代码风格混乱，每次都不一致
团队协作时，每个人用 AI 的方式不同，代码质量参差不齐
返工成本高，AI 写完才发现方向错了

如果你中了哪怕一条，这篇文章就是为你准备的。

OpenSpec 是一个专门为 AI 编码助手设计的规范驱动开发框架（SDD）。它让 AI 在写代码之前先理解你要什么，确保产出符合预期。

什么是 OpenSpec？

OpenSpec 是由 Fission-AI 开发的开源项目，目前在 GitHub 上拥有 40K+ Stars。它的核心理念是：

fluid not rigid         — 不僵化，灵活应对变化
iterative not waterfall — 迭代式，而非瀑布式
easy not complex        — 简单易用，无繁琐流程
brownfield-first        — 优先支持现有项目，而非仅限新建

简单来说，OpenSpec 让你和 AI 的协作变得有序、可控、可追溯。

官网: openspec.dev/
GitHub: github.com/Fission-AI/…
许可证: MIT

为什么你需要它？

1. AI 编码的痛点

问题	传统方式	OpenSpec 方式
方向跑偏	AI 自由发挥，结果偏离需求	先定义规范，再生成代码
风格混乱	每次输出不一致	规范约束，风格统一
返工成本高	写完才发现问题	前期规划，减少返工
团队协作难	各自用 AI，无统一流程	规范驱动，流程标准化

2. 核心价值

OpenSpec 提供了三个核心价值：

规范优先 - 在 AI 开始写代码之前，先定义清楚"要做什么"

变更追踪 - 每次修改都有完整的变更记录，可追溯、可回滚

团队协作 - 规范文件可以 Git 管理，团队共享、PR 评审

3. 与传统方法对比

传统的"AI 直接写代码"模式：

需求 → AI 写代码 → 发现问题 → 返工 → 再写 → ...

OpenSpec 模式：

需求 → /opsx:propose → 规范文件 → 评审 → /opsx:apply → 实现 → /opsx:archive

核心概念

目录结构

openspec/
├── specs/              # 系统行为的源真理（当前状态）
│   ├── auth/
│   │   └── spec.md     # 认证模块的规范
│   ├── payments/
│   │   └── spec.md     # 支付模块的规范
│   └── ui/
│       └── spec.md     # UI 规范
│
└── changes/            # 提议的修改（待合并）
    ├── add-dark-mode/  # 一个变更 = 一个文件夹
    │   ├── proposal.md # 为什么做这个变更
    │   ├── specs/      # 规范变更（delta）
    │   ├── design.md   # 技术设计方案
    │   └── tasks.md    # 实现任务清单
    │
    └── add-logout-button/
        └── ...

关键概念：

目录	作用
`specs/`	系统当前行为的"源真理"，描述系统应该怎样工作
`changes/`	待实施的变更提案，每个变更一个独立文件夹

规范格式（Spec Format）

一个规范文件包含需求（Requirements）和场景（Scenarios）：

# Auth Specification

## Purpose
认证和会话管理。

## Requirements

### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.

#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard

#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued

### Requirement: Session Expiration
The system MUST expire sessions after 30 minutes of inactivity.

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated

结构说明：

元素	作用
`## Purpose`	模块的高层描述
`### Requirement:`	系统必须具备的特定行为
`#### Scenario:`	需求的具体示例，可测试验证
SHALL/MUST/SHOULD	RFC 2119 关键词，表示需求强度

变更文件夹（Change Folder）

每个变更提案包含：

changes/add-dark-mode/
├── proposal.md    # 为什么做？要改什么？
├── specs/         # 规范的变更（delta 格式）
├── design.md      # 技术实现方案
└── tasks.md       # 实现任务清单

快速开始

安装

npm:

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

pnpm:

pnpm add -g @fission-ai/openspec@latest

Nix (免安装直接运行):

nix run github:Fission-AI/OpenSpec -- init

验证安装:

openspec --version

初始化项目

cd your-project
openspec init

这会创建 openspec/ 目录结构。

核心工作流

OpenSpec 提供了一套基于 OPSX 的命令流程：

快速路径（默认 `core` profile）

/opsx:propose → /opsx:apply → /opsx:archive

示例对话：

你: /opsx:propose add-dark-mode

AI: Created openspec/changes/add-dark-mode/
   ✓ proposal.md — 为什么要做，要改什么
   ✓ specs/      — 需求和场景
   ✓ design.md   — 技术方案
   ✓ tasks.md    — 实现任务清单
   Ready for implementation!

你: /opsx:apply

AI: Implementing tasks...
   ✓ 1.1 Add theme context provider
   ✓ 1.2 Create toggle component
   ✓ 2.1 Add CSS variables
   ✓ 2.2 Wire up localStorage persistence
   Implementation complete!

你: /opsx:archive

AI: Archived add-dark-mode/
   Deltas merged into specs/ui/spec.md
   Change folder moved to openspec/archives/

核心命令说明

命令	作用
`/opsx:propose`	创建变更提案，生成规划文件
`/opsx:apply`	实施变更，按任务清单执行
`/opsx:archive`	归档变更，将 delta 合并入主规范

扩展工作流

如果你想要更细粒度的控制，可以启用扩展 profile：

openspec config profile
openspec update

扩展命令包括：

命令	作用
`/opsx:new`	创建新的变更文件夹
`/opsx:continue`	继续之前的变更
`/opsx:ff`	快进，一次性生成所有规划文件
`/opsx:verify`	验证实现是否符合规范
`/opsx:sync`	同步规范与代码状态

Delta 格式：变更的可视化

OpenSpec 的一个核心创新是 Delta 格式，让变更一目了然：

### Requirement: Session expiration
- The system SHALL expire sessions after a configured duration.
+ The system SHALL support configurable session expiration periods.

#### Scenario: Default session timeout
- GIVEN a user has authenticated
- WHEN 24 hours pass without activity
+ WHEN 24 hours pass without "Remember me"
- THEN invalidate the session token

+ #### Scenario: Extended session with remember me
+ - GIVEN user checks "Remember me" at login
+ - WHEN 30 days have passed
+ - THEN invalidate the session token
+ - AND clear the persistent cookie

符号说明：

符号	含义
`-`	移除的内容
`+`	新增的内容

这让团队成员可以快速理解"改了什么"，无需阅读完整规范。

实践指南

1. 从小开始

不要一次性为整个系统写规范。先从一个模块开始：

# 只为认证模块创建规范
openspec init
# 然后手动创建 openspec/specs/auth/spec.md

2. 规范即代码

把 openspec/ 目录放入 Git：

git add openspec/
git commit -m "Add OpenSpec for auth module"

这样：

规范变更可以通过 PR 评审
团队成员共享同一份规范
可以追溯历史变更

3. 变更提案先评审

在 /opsx:apply 之前，先让团队成员看看 proposal.md 和 design.md：

你: /opsx:propose add-dark-mode

# 不要急着 apply，先：
# 1. 打开 openspec/changes/add-dark-mode/proposal.md
# 2. 团队评审，确认方向
# 3. 确认后再 /opsx:apply

4. 规范写什么、不写什么

应该写：

用户可观察的行为
输入输出、错误条件
安全性、隐私性约束
可测试验证的场景

不应该写：

内部函数名、类名
具体的库/框架选择
详细的实现步骤

5. 场景要具体可测试

好的场景：

#### Scenario: Valid credentials
- GIVEN a user with email "test@example.com" and password "valid123"
- WHEN the user submits login form
- THEN a JWT token is returned with 24h expiration

不好的场景（太抽象）：

#### Scenario: User logs in
- GIVEN user exists
- WHEN login
- THEN success

与现有项目的集成

OpenSpec 特别适合现有项目（brownfield）：

场景：添加新功能

你: /opsx:propose add-export-feature

AI: Created openspec/changes/add-export-feature/
   分析现有代码结构...
   ✓ proposal.md — 添加数据导出功能
   ✓ specs/      — 导出行为规范
   ✓ design.md   — 复用现有 CSV 库
   ✓ tasks.md    — 实现清单

场景：修改现有功能

你: /opsx:propose extend-session-timeout

AI: Created openspec/changes/extend-session-timeout/
   ✓ Delta 格式展示对 specs/auth/spec.md 的修改
   ✓ design.md — 修改 auth middleware

支持的工具

OpenSpec 可以与多种 AI 编码助手集成：

工具	支持状态
Cursor	✅ 支持
Windsurf	✅ 支持
Claude Code	✅ 支持
Copilot	✅ 支持
其他	可通过自定义 schema 扩展

详见：supported-tools.md

最佳实践总结

规范层面

按领域组织 - auth/, payments/, ui/ 而非 api/, frontend/
使用 RFC 2119 关键词 - SHALL/MUST/SHOULD 明确需求强度
场景要可测试 - 具体、可验证，而非抽象描述
规范放入 Git - PR 评审、团队共享

工作流层面

propose → review → apply - 不要跳过评审环节
delta 格式评审 - 一眼看出改了什么
archive 后再 propose - 保持规范整洁

团队协作层面

统一 OpenSpec 流程 - 团队成员用同一套命令
规范变更走 PR - 和代码一样评审
归档变更保留历史 - 追溯"为什么当初这么改"

我的思考

OpenSpec 的出现，标志着 AI 编码助手正在从"玩具"走向"工具"。

早期的 AI 编码，更像是一个智能的代码补全器——你问，它答，至于答得对不对，你用过才知道。这种方式在小项目还行，但放到团队协作、长期维护的项目里，问题就暴露了：

方向不一致 - 每次输出都可能跑偏
风格混乱 - 没有"统一标准"
责任不清 - 出问题是谁的责任？

OpenSpec 的思路是：让 AI 先理解规范，再写代码。这就像是给 AI 一个"设计图纸"，让它按图纸施工，而不是自己发挥。

更重要的是，规范是人类可控的：

规范写在 Markdown 文件里，Git 管理
变更提案可以团队评审
delta 格式让变更一目了然

这种模式把 AI 编码从"黑盒"变成了"白盒"——你知道 AI 要做什么，可以干预，可以追溯。

当然，OpenSpec 也带来了额外的学习成本。但对于团队协作的项目，这份投入是值得的：

减少返工成本
提高代码一致性
让 AI 编码变成可控的开发流程

一句话总结：OpenSpec 让 AI 编码从"自由发挥"变成"按规范施工"。

OpenSpec 实践指南：让 AI 编码助手"靠谱"起来