自从 2023 年左右，AI 编程助手Yi经Neng够生成几乎完整的业务代码，许多开发者dou沉浸在“只要说一句话，就Neng得到实现”的快感里。然而这股狂热背后隐藏着一个让人夜不Neng寐的难题：代码的来龙去脉往往在对话窗口里消失得无影无踪。一段时间后再回头查需求，发现自己只Neng靠记忆拼凑逻辑；同样的需求在不同会话里得到截然不同的实现；团队协作时谁也不知道 AI 改了哪些文件。

Ru果把这种状态比作一台随机数生成器，也不为过——它输出的每一次结果，dou像掷骰子。要想把这颗“骰子”变成可靠的工程工具，就必须给它加上结构化、可审计的约束层。

目前的大多数模型只关注当前上下文，一旦对话结束，所有指令和思考dou会被抛弃。于是同一个需求在两次提问中可Neng得到基于 Passport.js 的实现，也可Neng得到 JWT 方案，两者差别足以导致接口不兼容。

开发者往往把需求写在即时聊天里：“帮我加个登录功Neng，要支持邮箱和 GitHub”。这句话kan似完整，却隐藏了会话超时、错误处理、双因子认证等关键细节。缺少正式文档，这些细节只Neng靠事后补救。

多人使用同一个 AI 助手时每个人dou在自己的聊天记录中生成代码，彼此之间没有共享的“共识”。结果是合并冲突频发、审查成本飙升。

Ru果继续这样下去，你会发现项目像一艘没有航海图的船，只Neng靠风向随波逐流。

核心理念：在动手写代码之前，让 AI 和开发者一起完成一次“规格对齐”。这份规格不是几行聊天记录，而是存放在项目目录下的机器可读文档，人Ke以随时打开、编辑或审查。

通过这种方式，AI 的输出Ke以直接对照文档进行校验；人类也Ke以快速定位某段代码背后的业务意图。换句话说AI 从“随意猜测”转向了“按规范执行”。

my-project/
├─ src/
├─ spec/
│   ├─ specs/        # 单一事实来源
│   ├─ changes/      # 增量提案
│   └─ config.yaml   # 工作流配置
└─ package.json

specs/ 保存系统当前完整行为描述；每个子目录对应一个子系统。

changes/ 用来记录“我要改什么”“为什么改”的增量提案，每个提案dou是一个独立文件夹。

config.yaml 用来定义默认模型、工作流模式等参数。

proposal.md   → 解释动机 & 范围
specs/*.md    → 明确系统应当怎样表现
design.md     → 技术实现思路
tasks.md      → 可执行检查清单

只有当所有四个环节dou准备好，AI 才会进入「生成代码」阶段，从而确保每一步dou有依据可循。

# 初始化项目

# 创建目录并进入
mkdir my-react-app && cd my-react-app
git init
# 安装 OpenSpec
npm i -g @openspec/cli
openspec init   # 自动创建 spec/ 结构

 OpenSpec 初始化完成
📁 spec/specs/
📁 spec/changes/
📄 spec/config.yaml

# 发起第一次增量提案

/opsx:propose initial-setup
# 系统自动创建：
spec/changes/initial-setup/
├─ proposal.md
├─ specs/
│   └─ project/spec.md
├─ design.md
└─ tasks.md

# 编辑 proposal.md

# 初始搭建目标
- 使用 Vite + TypeScript 构建 React 应用  
- 支持 ESLint + Prettier  
- CI 使用 GitHub Actions 自动跑测试  
- 兼容 Chrome / Edge / Safari  
范围：仅限前端脚手架，不涉及后端 API。

# 一键生成其余文档

/opsx:ff initial-setup
# 输出：
 design.md Yi生成  
 tasks.md Yi生成  
全部待办事项Yi列出。

# 执行任务

/opsx:apply initial-setup
# 系统逐条运行 tasks 中指令，例如：
npm create vite@latest . --template react-ts  
npm i -D eslint prettier eslint-config-prettier  
git add . && git commit -m "chore: scaffold project"
# 完成后 tasks 中对应项自动打勾。

# 验证并归档

/opsx:verify initial-setup   # 输出完整性报告…
/opsx:archive initial-setup   # 合并到主 specs 并归档。

hen多团队面对的是「老系统+新需求」的组合拳。OpenSpec 的 Delta Spec 正好解决了「只描述变化」的问题，无需重写整个规格文件。

# 确认项目Yi初始化，如未初始化执行 `openspec init`.

/opsx:explore "产品列表是怎么实现的？使用了哪种数据库？"

/opsx:propose add-shopping-cart
spec/changes/add-shopping-cart/
├─ proposal.md          # 为什么要Zuo购物车？
├─ specs/cart/spec.md   # 具体行为描述
├─ design.md            # 技术选型：使用 Zustand + localStorage…
└─ tasks.md             # 实现步骤清单。

# 购物车核心需求
功Neng点

添加商品至购物车  
删除商品 / 清空购物车
场景示例



  
场景
  
前置条件
  
步骤
  
预期



  
添加商品
  
商品Yi展示
  
点击 “加入购物车”
  
商品出现在侧边栏


  
跨页面保持
  
刷新页面
  
页面重新加载
  
购物车状态保持




如需额外字段请自行补充。

/opsx:ff add-shopping-cart   # 一键产出 design 与 tasks 

/opsx:apply add-shopping-cart 
/opsx:verify add-shopping-cart 
/opsx:archive add-shopping-cart