3.7 KiB
3.7 KiB
AI编程新范式：规格驱动编程 OpenSpec 的落地实战
来源： 微信公众号 - AI软件产品经理 作者： melong 日期： 2026年4月7日 07:00 标签： #OpenSpec #规格驱动编程 #AI编程 #Cursor #落地实战
OpenSpec 简介
OpenSpec 是一个命令行工具，帮助我们和 AI 助手之间建立规范驱动（spec-driven）的开发流程，强调变更隔离、人类与 AI 的共识和审查闭环，本质上是在构建一种新的"人机协作语言"。
GitHub: Fission-AI/OpenSpec
核心思想
将开发流程拆解为两个清晰的阶段：
- 明确"要什么" — 在
openspec/specs/文件夹中定义当前系统的完整规范 - 管理"怎么改" — 在
openspec/changes/文件夹中存放所有变更提案
从"边写边改"到"规范先行"，非常适合 1→n 的项目迭代。
亮点
- 变更从提案到落地、全流程规范、闭环管理，每一步可溯源、复查与协同
- 规范落地后，后续团队成员查阅 specs 文档即可快速了解业务历史和变更细节
初始化工作
1. 安装 OpenSpec
npm install -g @fission-ai/openspec@latest
# 需要 Node >= 20.19.0
2. 项目初始化
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 的执行力放在编码阶段，各取所长。