引言：AI 编程的“甜蜜陷阱”与破局之道
在 Cursor、Claude Code、GitHub Copilot 等 AI 编程助手普及的今天，开发者普遍陷入一种“甜蜜陷阱”：
- 你让 AI “加个购物车功能”，它却擅自重构了整个用户模块；
- 你要求“修复基金估值精度问题”，它却引入了新的时区 Bug；
- 几轮对话后，AI 完全“忘记”最初的需求，代码越改越偏……
这种“凭感觉编码”（Vibe Coding）模式虽能快速产出，却难以支撑复杂项目的可靠演进。正如一线研发同学反复吐槽：“代码库越大，AI 越乱”。
为解决这一核心痛点，规范驱动开发（Spec-Driven Development, SDD）应运而生。而 OpenSpec + OpenCode 正是该理念的一套轻量、开源、可落地的实践组合，旨在将 AI 编程从“不可预测的艺术”转变为“可重复、可审计的工程科学”。
一、OpenSpec 是什么？—— 用 Markdown 锁定共识
OpenSpec 的核心思想极其简单却深刻：在 AI 写任何一行代码前，先用 Markdown 文件将需求、设计和变更意图清晰、结构化地固化下来。
这套规范成为人与 AI 之间的“共识文档”，确保 AI 始终在正确的轨道上工作，而非依赖模糊的聊天记录或易逝的上下文。
1.1 核心目录结构
OpenSpec 在项目根目录下创建 .openspec/ 目录，其结构如下：
.openspec/
├── specs/ # 当前系统行为的权威描述（主规范库）
├── changes/ # 每个新功能或修复的独立工作区
├── archive/ # 已完成变更的历史归档
├── AGENTS.md # 给 AI 助手的全局指令说明
└── config.yaml # （可选）工具配置
- specs/：代表系统当前的“真相来源”（Source of Truth），描述了所有已实现的功能。
- changes/：每个新需求或 Bug 修复都在此创建一个独立子目录（如 add-fund-valuation），隔离开发过程，避免相互干扰。
- archive/：功能完成后，变更目录被移至此处，形成完整、可追溯的项目历史。
这种分离设计，使得迭代式开发变得可管理、可审计、低冲突。
二、OpenCode 是什么？—— AI 的“执行引擎”
如果说 OpenSpec 是“大脑”制定的作战计划，那么 OpenCode 就是忠实执行命令的“机械臂”。
OpenCode 是一个强大的 AI 编码引擎，它能够：
- 深度理解 OpenSpec 规范文件；
- 依据 spec.md 和 tasks.md 精准生成或修改代码；
- 与主流 IDE（如 VS Code、Cursor）无缝集成；
- 支持多种大模型（如 Claude、GPT、DeepSeek），可自定义接入。
它不依赖于某个特定平台（如 Kiro），因此迁移成本极低，适合个人开发者和团队灵活选用。
三、完整工作流：三阶段九步骤
以开发一个“基金实时估值程序”为例，OpenSpec + OpenCode 的完整工作流可分为三个阶段：
阶段一：创建变更（Create Change）
目标：明确“为什么改”、“改什么”、“怎么改”。
初始化变更
执行命令：
openspec new add-fund-valuation
系统在 changes/ 下创建 add-fund-valuation/ 目录。
撰写提案（proposal.md）
- Why：阐述业务背景。例如：“作为个人投资者，我需要一个本地程序，能实时查看我持有的基金净值，避免频繁打开 App。”
- Scope：明确范围边界。例如：“仅支持公募基金，不包含股票、债券等其他资产。”
定义规范（spec.md）
- UI 设计：使用 Pencil、Figma 或纯文字描述界面布局。例如：“主窗口包含基金代码输入框、查询按钮、结果表格（列：基金名称、最新净值、估算涨跌幅）。”
- 数据源：指定技术方案。例如：“使用 akshare Python 库获取数据，避免网络爬虫法律风险。”
- API 接口：如有后端，需定义接口格式。
- 非功能需求：如性能、安全性等。
拆解任务（tasks.md）
将规范转化为 AI 可执行的任务列表：
– [ ] 安装 akshare 依赖
– [ ] 创建主窗口 UI（PyQt5）
– [ ] 实现基金查询逻辑
– [ ] 添加错误处理（如基金代码无效）
– [ ] 编写单元测试
关键点：此时，你尚未写一行代码，但 AI 已完全理解你的意图。
阶段二：实施（Apply）
目标：让 AI 严格按规范生成代码。
启动 OpenCode
在 IDE 中打开 changes/add-fund-valuation/ 目录，并激活 OpenCode 插件。
AI 执行任务
OpenCode 会：
- 读取 spec.md 理解整体设计；
- 按 tasks.md 逐项生成或修改代码；
- 自动处理依赖安装、文件创建等操作。
人工审核与引导
开发者角色从“编码者”转变为“审核者”：
- 检查 AI 输出是否符合规范；
- 若有偏差，在 spec.md 中修正，而非直接修改代码；
- 通过追加注释或细化 tasks.md 引导 AI 调整。
优势：即使中断数日，回归项目时只需重读 spec.md，即可快速恢复上下文，AI 也不会“失忆”。
阶段三：归档（Archive）
目标：固化成果，更新系统状态。
验证功能
手动或通过自动化测试确保功能正确。
执行归档命令
openspec archive add-fund-valuation
该命令会：
- 将 spec.md 中的变更合并到 specs/ 主库，更新系统当前状态的权威描述；
- 将整个 add-fund-valuation/ 目录移至 archive/ 存档；
- 清理临时文件，保持项目整洁。
提交 Git
将 .openspec/ 目录纳入版本控制。由于每个功能独立隔离，多人协作时冲突概率极低。
四、为何选择 OpenSpec + OpenCode？
4.1 解决 AI 编程的核心痛点
| 上下文遗忘 | 规范文件持久化，AI 始终有据可依 |
| 需求漂移 | spec.md 作为唯一真相来源，锁定需求 |
| 代码混乱 | tasks.md 提供清晰执行路径，避免自由发挥 |
| 协作困难 | 每个变更独立目录，Git 合并冲突少 |
4.2 低门槛、高灵活性
- 开源免费：CLI 工具，无厂商绑定。
- IDE 无关：支持 Cursor、VS Code、JetBrains 等。
- 模型开放：可接入任意 LLM，不依赖特定 API。
- 渐进式采用：可从单个功能开始试用，无需全盘改造。
4.3 面向未来的工程化基础
OpenSpec 不仅是当下提升效率的工具，更是通向 AI Agent 自动化工程 的基石：
- 未来，Agent 可自动读取 changes/ 中的新规范，自主完成开发、测试、部署全流程；
- specs/ 主库可作为系统知识图谱，用于智能问答、影响分析等高级场景。
五、实战技巧与最佳实践
5.1 多人协作
- 将 .openspec/ 目录加入 Git。
- 约定分支策略：每个功能对应一个 changes/xxx 目录，PR 合并前完成归档。
- 利用 AGENTS.md 统一团队对 AI 的指令风格。
5.2 处理遗留项目
- 对现有功能，可反向生成 spec.md 存入 specs/，建立初始状态。
- 新增功能严格遵循 OpenSpec 流程。
5.3 规范编写建议
- 具体：避免“用户体验好”等模糊描述，改为“点击查询按钮后，3 秒内显示结果”。
- 可验证：每条规范都应能通过测试或人工检查确认。
- 原子性：一个 changes/ 目录只解决一个问题。
六、总结：从“黑盒”到“白盒”的智能开发
OpenSpec + OpenCode 并非要取代开发者，而是通过建立一套人机协同的契约，将开发者从繁琐的、易错的上下文同步中解放出来，聚焦于更高价值的架构设计与业务决策。
它让 AI 编程不再是“开盲盒”，而是“按图索骥”；不再是“一次性快感”，而是“可持续交付”。
正如实践者所言：“规范不是束缚，而是通往自由的桥梁。”
现在，这套万字实践指南已为你铺就道路。无论你是个人开发者，还是希望提升团队效能的技术负责人，都可以立即尝试 OpenSpec + OpenCode，开启你的 AI 工程化之旅。
附录：快速开始
让 AI 真正成为你可靠的工程伙伴，从此告别“Vibe Coding”，拥抱“Spec-Driven Engineering”。
