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

OpenSpec实战指南：如何用规范驱动AI编码

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

OpenSpec实战指南：如何用规范驱动AI编码

让AI编码助手从"随机应变"变为"言听计从"

前言

你是否遇到过这种情况：让AI写个功能，它却生成了一堆你不需要的东西？或者遗漏了关键需求？这篇文章将告诉你如何使用OpenSpec——一个规范驱动的AI编码开发工具，让AI真正理解你想要什么。

一句话说明白OpenSpec

OpenSpec = 在写代码之前，先用Markdown写一份"需求规范"，让AI严格按照规范来编码。

它解决的核心问题是：AI太"聪明"了，聪明到会自己猜测你的需求，结果猜错了。

环境准备

1. 检查Node.js版本

node --version

要求：Node.js >= 20.19.0

如果版本不够，去 Node.js官网 下载最新版本。

2. 安装OpenSpec CLI

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

验证安装：

openspec --version

快速开始：5分钟入门

步骤1：初始化项目

cd 你的项目目录
openspec init

初始化时会问你选择哪个AI工具（Claude Code、Cursor等），然后自动配置并创建 openspec/ 目录结构。

这里提示是enter选中，如果不好使按空格选中试试

步骤2：验证设置

openspec list

步骤3：如何使用

进入你常用的工具后 比如opencode 进入后 按反斜杠 /
你会看到 /openspec-explore 说明安装成功

如果没有看到斜杠命令，重启你的AI助手，然后运行 openspec update。

核心使用流程

OpenSpec的工作流程就四步：提案 → 审查 → 实施 → 归档

1️⃣ 起草变更提案

# 告诉AI助手
/openspec:proposal 添加用户搜索功能

AI会自动创建：

openspec/changes/用户搜索功能/
├── proposal.md      # 变更说明
├── tasks.md        # 实施任务清单
└── specs/          # 规范差异

2️⃣ 审查与对齐

# 查看变更详情
openspec show 用户搜索功能

# 验证规范格式
openspec validate 用户搜索功能

关键动作：和AI一起审查规范，确保需求完整、表达清晰。

💡 提示：规范的格式很重要，每个Requirement至少要有一个Scenario。

### Requirement: 用户搜索
系统必须支持按用户名搜索用户。

#### Scenario: 按用户名精确搜索
- WHEN 用户输入用户名
- THEN 返回匹配的用户

3️⃣ 实施任务

# 告诉AI助手
/openspec:apply 用户搜索功能

AI会按照 tasks.md 中的清单逐步实施，每完成一个任务会标记为 ✓。

4️⃣ 归档与更新规范

# 归档完成的变更
openspec archive 用户搜索功能 --yes

归档后会：

  • 将变更合并到 openspec/specs/
  • 移动到 archive/ 目录

常用命令速查

| 命令 | 用途 |
|------|------|
| openspec list | 查看所有活动变更 |
| openspec show <名称> | 显示变更详情 |
| openspec validate <名称> | 验证规范格式 |
| openspec archive <名称> --yes | 归档变更 |
| openspec update | 刷新AI指导 |

支持的AI工具

OpenSpec支持主流AI编码助手，包括：

| 工具 | 命令格式 |
|------|----------|
| Claude Code | /openspec:proposal |
| Cursor | /openspec-proposal |
| OpenCode | /openspec-proposal |
| Cline | 在 .clinerules/ 中配置 |
| GitHub Copilot | /openspec-proposal |

团队协作

初始化团队项目

openspec init

工作流

  1. 每个新功能 → 创建变更提案
  2. 团队Review → 确保规范完整
  3. 实施 → AI按规范编码
  4. 归档 → 规范沉淀到文档

工具灵活性

不同团队成员可以使用不同的AI工具（Claude Code、Cursor等），因为OpenSpec通过 AGENTS.md 文件让所有工具理解相同的规范。

常见问题

Q1: AI助手没有显示斜杠命令？

A: 重启AI助手，运行 openspec update

Q2: 可以同时处理多个变更吗？

A: 可以，但一次只能应用一个

Q3: 怎么修改已归档的规范？

A: 创建新的变更提案，通过相同流程更新

总结

OpenSpec的核心价值：在AI编码前，先用Markdown写下"明确的需求"

它让AI从"自由发挥"变成"按图索骥"，大幅减少返工，提升代码质量。

参考资料

  • 官网：https://openspec.dev/
  • GitHub：https://github.com/Fission-AI/OpenSpec
  • NPM：https://www.npmjs.com/package/@fission-ai/openspec
OpenCodeOpenSpec