97 lines
3.7 KiB
Markdown
97 lines
3.7 KiB
Markdown
# 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 的执行力放在编码阶段，各取所长。
|