首页 > 专题 > AI编程 > 文章详情
返回 AI编程

OpenSpec最佳实践：规范驱动AI编码完整指南

2026年03月12日 5 阅读 AI编程

OpenSpec最佳实践：规范驱动AI编码完整指南

从"vibe coding"到"spec-driven development"的实战手册

为什么你需要OpenSpec？

想象一下：你告诉AI"帮我加个登录功能"，结果它不仅加了登录，还顺便重构了半个项目——这，就是"vibe coding"的日常。

OpenSpec解决的问题：

  • AI上下文超过40%后性能急剧下降，导致"失忆"
  • 需求散落在聊天记录里，无法追溯
  • 代码审查时没有明确的规范对照

核心概念：先结构，后代码

双文件夹模型

openspec/
├── specs/           # 真理源：当前系统的规范
│   └── auth/
│       └── spec.md
├── changes/        # 变更提案：正在开发的功能
│   └── add-login/
│       ├── proposal.md
│       ├── tasks.md
│       └── specs/
└── project.md      # 项目全局上下文

为什么这样设计？

  • specs/ 是"真理源"，AI修改任何功能前必须先读它
  • changes/ 是"隔离工作区"，每个功能独立一个文件夹
  • 归档时再合并到specs/，类似Git的分支模型

四步工作流详解

1️⃣ 提案（Proposal）

/openspec:proposal 添加用户登录功能

AI会：

  1. 读取project.md和specs/了解现有系统
  2. 创建 openspec/changes/添加用户登录/ 目录
  3. 生成proposal.md、tasks.md

proposal.md包含：

  • 变更动机和范围
  • 预期影响
  • 简化的PRD

2️⃣ 定义规范（Spec Definition）

在 changes/xxx/specs/ 下创建规范差异：

## ADDED Requirements

### Requirement: 用户登录
系统必须支持用户名密码登录。

#### Scenario: 有效凭证
- GIVEN 用户存在
- WHEN 输入正确的用户名和密码
- THEN 返回JWT令牌

#### Scenario: 无效凭证
- GIVEN 用户不存在
- WHEN 输入错误密码
- THEN 返回401错误

验证规范：

openspec validate 添加用户登录

3️⃣ 实施（Apply）

/openspec:apply 添加用户登录

AI按tasks.md逐项执行，每完成一项打勾✓。

4️⃣ 归档（Archive）

openspec archive 添加用户登录 --yes

系统自动：

  • 将specs差异合并到主规范
  • 清理changes目录
  • 更新"真理源"

最佳实践

1. project.md是AI的"世界观"

必须在project.md中明确写明：

# Project Context

## Tech Stack
- Node.js 20.x
- TypeScript 5.x
- React 18

## Code Conventions
- 组件名用PascalCase
- 函数名用camelCase
- 禁止直接查询数据库，必须通过Repository层

## Business Rules
- 订单超时30分钟自动取消
- 用户密码必须bcrypt加密

效果：大幅减少AI"幻觉"，生成的代码符合项目规范。

2. 规范格式要规范

必须包含：

  • ### Requirement: 标题
  • 至少一个 #### Scenario: 块
  • 使用 SHALL/MUST 等规范用语

格式：

### Requirement: 描述
系统必须...[行为描述]

#### Scenario: 场景名
- GIVEN [前置条件]
- WHEN [触发动作]
- THEN [预期结果]

3. "Retrofitting"模式：逆向文档化

面对没有文档的遗留代码，可以：

  1. 创建提案：
/openspec:proposal 逆向文档化旧模块
  1. 指示AI：
请阅读src/legacy-module下的代码，生成OpenSpec规范文件，描述当前行为。
  1. 产出：现有系统的规范文档

价值：为后续重构提供基准线，确保新实现与旧行为一致。

4. Token效率优化

不要：一次性把所有代码喂给AI

要：让AI只读：

  • project.md（全局概览）
  • tasks.md（当前任务）
  • 相关的spec.md（具体需求）

效果：减少Token消耗，提高响应速度

5. 团队协作

Git工作流：

  1. 每个变更提案是一个独立分支式文件夹
  2. PR不仅包含代码diff，还包含proposal.md和specs/
  3. 审查者先看"意图是否正确"，再看"实现是否正确"

CI集成：

# .github/workflows/openspec.yml
- name: Validate OpenSpec
  run: openspec validate ${{ github.event.inputs.change }}

常用命令速查

| 命令 | 用途 |
|------|------|
| openspec init | 初始化项目 |
| openspec list | 查看所有变更 |
| openspec show <name> | 显示变更详情 |
| openspec validate <name> | 验证规范格式 |
| openspec archive <name> --yes | 归档变更 |
| openspec update | 刷新AI指导 |

AI工具集成

| 工具 | 命令格式 |
|------|----------|
| Claude Code | /openspec:proposal |
| Cursor | /openspec-proposal |
| OpenCode | /openspec-proposal |
| GitHub Copilot | /openspec-proposal |
| Windsurf | 自动识别 |

常见问题解决

| 问题 | 解决方案 |
|------|----------|
| AI忽略规范直接写代码 | 运行 openspec update 刷新指令 |
| 归档失败（Plan Mode） | 手动在终端运行 openspec archive |
| 规范验证失败 | 检查是否缺少Scenario，格式是否正确 |
| AI幻觉库 | 在project.md中明确指定依赖版本 |

总结

OpenSpec的核心价值 = 把AI从"黑盒"变成"合作者"

通过：

  • ✅ 隔离的变更工作区
  • ✅ 结构化的规范文档
  • ✅ 四步强制流程

让AI只能"按图索骥"，大幅提升代码质量和可追溯性。

参考资料

  • 官网：https://openspec.dev/
  • GitHub：https://github.com/Fission-AI/OpenSpec
  • 官方文档：https://openspec.pro/getting-started/
OpenCodeOpenSpec