一、中 3 条以上，这篇值得你花 5 分钟

先说几个我亲身踩过的坑，你看看自己中了几条：

1. 一个需求丢给 AI，代码几分钟"刷刷"出来了，修 AI 写出的 bug 却比手写还累。
2. 同一个项目，AI 这次写的代码和上次风格不一样，完全不顾复用。
3. 一个复杂需求聊到一半，AI 开始"失忆"——前期约定好的架构，它忘得干干净净。
4. 开新会话，项目背景、业务边界、技术栈又得从头讲一遍。
5. 一天到晚整理 txt 文件里的碎片化提示词，自己都看不懂昨天写了啥。
6. 会话越长 Token 越烧，钱花得肉疼，速度还越来越慢。

如果你中了 3 条以上，恭喜——这不是 AI 的问题，是工作流程的问题。

四个痛点，一个根源

根源一句话：AI 每次"理解"都是从零重建，需求和方案只活在聊天框里——既不能评审，也无法沉淀。

而 SDD（Spec-Driven Development，规范驱动开发），治的就是这个病。

二、OpenSpec 是什么？一句话讲清

OpenSpec 是落地 SDD 的标准化规格框架，把"方案先行、评审通过后再编码"的工程规范轻量化融入 AI 开发流程，统一沉淀项目规则，实现人机协同复用。

看个对比，瞬间明白：

没有 OpenSpec：

人："我要做个工单管理"
   → AI 自己猜 → 直接生成代码 → 人看代码评审（已经晚了）

方向偏了，代码全写完才发现，返工地狱。

有了 OpenSpec：

人："我要做个工单管理"
   → AI 先生成 proposal.md（意图+范围）        ← 评审：范围对不对？
   → AI 再生成 specs/spec.md（需求+验收标准）   ← 评审：需求全不全？
   → AI 再生成 design.md（技术方案）            ← 评审：方案合不合理？
   → 方案过了，AI 才生成 tasks.md 并写代码      ← 方向对了再动手

AI 每次都能读到这些文件，不会忘记；新成员来了直接读文件，不用翻聊天记录。

[图：流程对比图 - 上方"裸奔模式"是 AI 乱写一通后才发现问题；下方"OpenSpec 模式"是层层评审卡口，方向对了才放行]

三、OpenSpec 三要素：天然适配敏捷迭代

这三点让 OpenSpec 既能从零搭建新功能，也能在老项目里只改一小块——增量规范、独立 change、小步快跑、持续沉淀。

要素 1：一个变更 = 一个文件夹

每做一个功能，就在 <code>openspec/changes/</code> 下建一个文件夹，4 个文件齐活：

openspec/changes/add-auto-process/   ← 这是"给工单加自动生成工序"的变更
├── proposal.md     # 为什么做？范围是什么？
├── specs/
│   └── spec.md     # 具体需求，用"新增/修改/删除"格式写
├── design.md       # 技术方案（DB 怎么设计？API 怎么写？）
└── tasks.md        # 把方案拆成可执行的小任务

类比：就像你开发一个功能时脑子里转的那四件事——"为啥做 → 做成啥 → 怎么做 → 分几步"。OpenSpec 只是把它写下来。

要素 2：增量规范——只写"变化了啥"

传统方式（每次重写全部规范）：

# 工单管理规范 V3
工单创建页面字段：工单号、项目、产品、数量...
工单创建时自动生成工序...
工序反馈页面...

OpenSpec 方式（只记变化）：

# Delta: 给工单加上自动生成工序

## ADDED（新增）
- 创建工单选产品后，自动带出标准工序列表
- 新增"产品工序配置"页面

## MODIFIED（修改）
- 工单创建页：原"手动逐条添加" → 现"选产品自动生成"

## REMOVED（删除）
（本次没有）

好处一眼看到：这次到底改了啥，不用扒完整份规范。版本演进一目了然。

要素 3：工作流很自由

两条路，按需求清晰度选：

快速路径（需求明确时）:
  /opsx:propose → /opsx:apply → /opsx:archive
  一口气建好 → 写代码 → 归档

探索路径（需求模糊时）:
  /opsx:explore → /opsx:new → /opsx:continue → /opsx:apply → /opsx:archive
  先聊想法 → 建框架 → 逐步完善 → 写代码 → 归档

没有"必须按 1234 步走"的死板限制，随时可回头改。

四、实战篇：硬件生产排产功能优化

场景：选择产品自动生成工序

管理者创建工单时选择"人员定位基站"，系统自动带出 6 道工序：加工 → 单板测试 → 组装 → 电气连接 → 成品测试 → 包装。

跟着 6 步走完，整个 change 从提案到归档。

Step 1：创建提案

# 在新会话里告诉 AI
/opsx:propose 选择产品类型自动生成工序清单

AI 自动生成 <code>proposal.md</code>：

# Proposal: 选择产品类型自动生成工序清单

## 为什么做
产线管理者创建工单时，每次手动逐条加工序（加工→测试→组装→包装...），
一个工单 6 道工序，操作繁琐还容易漏。

## 做什么（范围）

✅ 做这些：
- 产品工序配置页面（维护"产品→工序"映射）
- 工单创建选产品后自动加载工序
- 自动生成的工序可修改、删除、追加

❌ 暂不做：
- 工序差异化表单（不同工序显示不同字段）
- 和金蝶 ERP 对接

✅ 评审点：范围对不对？做和不做边界清不清楚？

Step 2：写增量规范

AI 生成 <code>specs/spec.md</code>，用 ADDED / MODIFIED / REMOVED 描述变化：

# Delta Spec: 产品类型自动生成工序

## ADDED

### 需求：产品工序配置管理
管理者能维护"产品类型 → 工序清单"的映射。

场景：新建产品工序模板
- 假设 管理者进入"产品工序配置"页面
- 当 点击"新增"，选择产品"人员定位基站"，添加工序列表
- 那么 系统保存映射，之后该产品的工单自动加载

### 需求：工单创建时自动加载工序

场景：选择产品自动生成
- 假设 产品"人员定位基站"配置了 6 道工序
- 当 管理者创建工单并选择该产品
- 那么 工序子表自动出现 6 行，按配置顺序排列

## Edge Cases（边界情况）
- 产品没配工序模板 → 子表为空，手动添加（兼容旧流程）
- 切换已选产品 → 弹窗确认，清空并重新加载
- 模板本身为空（0 条工序）→ 视为未配置，不自动生成

✅ 评审点：需求全不全？边界情况想到了吗？验收场景是"假设/当/那么"三段式，测试用例顺手就有了。

Step 3：设计方案

AI 生成 <code>design.md</code>（精简版）：

# 技术方案: 产品工序自动生成

## 数据库
新表 t_oa_product_process_config（产品工序配置主表）
  - id, product_id, product_name, product_type

新表 t_oa_product_process_config_detail（工序明细）
  - id, config_id, process_name, sort_order, description

## 后端 API
GET  /product-process-config/findByProduct/{productId}   ← 工单创建时调
POST /product-process-config/create                       ← 新建配置
PUT  /product-process-config/update                       ← 修改配置
GET  /product-process-config/findPage                     ← 配置列表
DEL  /product-process-config/delete                       ← 删除配置

## PC 前端
修改工单创建表单（src/views/production/productionOrder/）：
  监听 productId 变化 → 调 findByProduct API → 自动填充工序子表

新增产品工序配置页（src/views/production/productProcessConfig/）：
  标准列表页 + 工序明细编辑器

✅ 评审点：表设计合理吗？API 路径规范吗？前端改动影响面可控吗？

Step 4：生成任务清单

AI 把方案拆成可勾选的 <code>tasks.md</code>：

# 实施任务

## 阶段 1: 数据库 + 后端基础
- [ ] 创建 Flyway 迁移脚本
- [ ] 创建实体类 ProductProcessConfig + Detail
- [ ] 创建 Service + Controller

## 阶段 2: PC 前端
- [ ] 产品工序配置列表页
- [ ] 工序明细编辑器组件
- [ ] 修改工单创建表单（产品选择联动）

## 阶段 3: H5 前端
- [ ] H5 端同步支持

✅ 评审点：任务拆得够细吗？阶段划分合理吗？做完一条勾一条，进度一目了然。

Step 5：写代码

/opsx:apply
# AI 按 tasks.md 逐条执行，做完一条勾一条

因为前 4 步已经把方案、需求、技术细节全写清楚了，AI 此时只是机械执行——不会再"自由发挥"，不会跑偏。

Step 6：归档

/opsx:archive
# 增量规范自动合并到主规范（openspec/specs/）
# 整个变更文件夹移到 archive/，永久可查

下次有人问"为什么工单选产品会自动生成工序"，直接翻 archive，连设计意图、决策依据、边界处理一起翻出来。

五、写在最后：AI 时代的工程素养

回到开头那几个坑——

它们不是 AI 的锅，是我们用 AI 的方式还停留在"对话驱动"时代。

对话驱动的问题在于：信息只活在聊天框里——既不能评审，也无法沉淀，更没法协作。

OpenSpec 给出的答案很简单，就三句话：

方案先写下来 → 评审通过再编码 → 决策永久可追溯

这不是又一个重型规范框架。它把"瀑布式"的严谨和"敏捷式"的轻量缝在了一起：新功能从零搭，老功能增量改，每个 change 独立不干扰。

用得越久，规范越厚，AI 越聪明，团队越省力。

这才是 SDD 真正的价值——不是让 AI 替你写代码，而是让 AI 在你画的圈里，把代码写明白。

下一篇预告：OpenSpec 进阶玩法——如何用 Schema 定制团队专属规范，让 AI 不仅按你说的做，还按你团队的标准做。