# AI编程新范式：规格驱动编程 OpenSpec 的落地实战

**来源：** [微信公众号 - AI软件产品经理](https://mp.weixin.qq.com/s/5CSEUj1R7q3KhaRBkJE-ZA)
**作者：** melong
**日期：** 2026年4月7日 07:00
**标签：** #OpenSpec #规格驱动编程 #AI编程 #Cursor #落地实战

---

## OpenSpec 简介

> OpenSpec 是一个命令行工具，帮助我们和 AI 助手之间建立规范驱动（spec-driven）的开发流程，强调变更隔离、人类与 AI 的共识和审查闭环，本质上是在构建一种新的"人机协作语言"。

GitHub: [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)

### 核心思想
将开发流程拆解为两个清晰的阶段：
1. **明确"要什么"** — 在 `openspec/specs/` 文件夹中定义当前系统的完整规范
2. **管理"怎么改"** — 在 `openspec/changes/` 文件夹中存放所有变更提案

从"边写边改"到"规范先行"，非常适合 **1→n 的项目迭代**。

### 亮点
- 变更从提案到落地、全流程规范、闭环管理，每一步可溯源、复查与协同
- 规范落地后，后续团队成员查阅 specs 文档即可快速了解业务历史和变更细节

---

## 初始化工作

### 1. 安装 OpenSpec
```bash
npm install -g @fission-ai/openspec@latest
# 需要 Node >= 20.19.0
```

### 2. 项目初始化
```bash
cd your_project
openspec init
```
选择使用的工具（Cursor、Claude Code、Codex 等），会在项目根目录下生成对应的 skill 文件夹。

### 3. 填充项目上下文信息
在 Cursor 对话框中输入：
```
Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions
```

`project.md` 结构包括：Purpose、Tech Stack、Project Conventions（Code Style / Architecture / Testing / Git Workflow）、Domain Context、Important Constraints、External Dependencies。

### 4. 生成变更提案
在 Cursor 中使用 `/openspec-propose` 命令：
```
/openspec-propose 需求文档地址为https://mi.feishu.cn/wiki/xxx
```

每次提案生成一个 Change ID，在 `changes/` 下创建目录，包含：
- **proposal.md** — 提案（Why / What Changes / Impact）
- **design.md** — 技术方案和架构决策
- **tasks.md** — 任务清单（多阶段 checkbox 任务）
- **specs/xxx/spec.md** — 可测试的需求规格

### 5. 审查与验证
- **重新提案**：不满意时可反复迭代，直到符合预期
- **反复迭代**：直接在 tasks.md 上修改，而不是新建提案

---

## 执行落地

### 拆分任务为可用交付（walkthrough）
- 将 tasks.md 的每个阶段按最细粒度拆分
- 让 AI 搞清楚当前阶段全部任务细节
- 确认前后端各自的任务边界

### 增量编码模式
- 每完成一个 phase，`/review` → `/fix` → `/test`
- 用自然语言描述期望，比问"有没有bug"更有效
- tips：频繁 `/clear` 清空上下文，避免 token 老化

---

## 常见报错与解决

| 报错 | 原因 | 解决 |
|------|------|------|
| `openspec: command not found` | Node 版本不够或全局安装路径问题 | 用 `npx @fission-ai/openspec` 替代，或升级 Node |
| 图片/head 标签被截断 | Cursor 的响应长度限制 | 分阶段执行，或要求 AI 仅输出关键修改部分 |
| 上下文过长导致幻觉 | 长时间未 `/clear` | 每个 phase 完成后 `/clear`，重新加载上下文 |

---

## 总结

> **OpenSpec 的核心价值不在于工具本身，而在于它强制执行的"先想清楚再动手"的工程纪律。** 在 AI 编码能力越来越强的今天，真正的瓶颈已经不是"写不出代码"，而是"写不对代码"。OpenSpec 通过规范驱动的方式，把人的判断力放在设计阶段，把 AI 的执行力放在编码阶段，各取所长。