规格先行，交付不慌：用 OpenSpec 做前端 SDD 的通用实践手册

leafyyuki
6 阅读7分钟

一句话：用 规范驱动开发（SDD） 把「想清楚再写代码」落在仓库里——提案 → 规格 → 设计 → 任务 → 实现 → 验证 → 同步 → 归档。OpenSpec 通过 斜杠命令（与 AI 协作） 与 CLI（目录与自动化） 串联全流程，适合中大型前端模块与增量迭代。

本文归纳通用模式；命令名、配置项以当前 OpenSpec 版本及官方文档为准。

1. SDD 与 OpenSpec

概念作用
SDD（Specification-Driven Development）先有可验收的规格与任务拆分，再写代码，减少返工与「口头需求」。
OpenSpec提供 变更（change）容器、目录约定、斜杠命令集与 CLI，让人与 AI 在同一套工件上协作。

前端侧典型收益：接口与页面结构先对齐、组件与路由变更有据可查、联调与验收标准可追溯。

2. 安装与项目初始化

2.1 安装 CLI

以官方说明为准，常见方式为全局安装后校验：

npm install -g @fission-ai/openspec@latest
openspec --version

也可使用 pnpm / yarn / npx。Node 版本以官方要求为准。

2.2 在仓库中落地

在仓库根目录执行初始化（具体子命令以官方为准，如 openspec init）：

  • 生成 openspec/ 及约定子目录
  • 常见包含 openspec/config.yaml：项目上下文、规则（spec / tasks / implementation / proposal）、guides 索引等
  • 可与 Cursor / Claude 等通过 AGENTS.md 或官方模板对接

说明：即使主要用 IDE 里的斜杠命令 驱动 AI，仓库内仍建议保留完整 openspec/，便于评审、Diff 与版本演进。

3. 仓库目录约定（通用形态）

openspec/
├── config.yaml           # 全局上下文、规则、guides 引用
├── project.md            # 可选：技术栈、架构惯例（供 AI 长期对齐）
├── guides/               # 深度指南：API、目录结构、代码风格等
├── specs/                # 主规范库（能力级长期规格，可选）
├── changes/              # 进行中的变更
│   ├── README.md         # 索引当前 change
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       ├── specs/        # 本变更的增量规格（delta）
│       └── .openspec.yaml  # 若存在：变更级元数据
└── changes/archive/      # 已归档变更

关系简述：单功能变更在 changes/<name>/ 内迭代；落地后可通过 sync 将规范合并进 openspec/specs/，形成团队级「主规范库」。

4. AI 协作：斜杠命令与阶段

OpenSpec 为前端 SDD 提供一套 斜杠命令，用于在支持 OpenSpec 的 AI 环境中，从需求探索到归档的全流程管理（是否全部启用取决于 Profile，见下一节）。

命令阶段功能说明
/opsx:explore探索与 AI 纯讨论需求、技术方案，不生成仓库文件
/opsx:new规划创建新变更目录及基础框架（如 proposal.md、tasks.md 等占位）
/opsx:continue规划按当前进度顺序补全下一缺失工件（常见顺序：proposal → specs → design → tasks）
/opsx:ff规划（快进）一次性生成规划侧全套工件，适合需求已明确的场景
/opsx:apply执行读取 tasks.md，逐项生成代码并落到约定目录
/opsx:verify验证对照 specs/、design.md 等检查实现，输出验证报告
/opsx:sync同步将本变更中新增/修改的规范合并到主规范库 openspec/specs/
/opsx:archive归档归档单个已完成变更（移动目录、更新索引与状态等，以工具行为为准）
/opsx:bulk-archive归档批量归档多个已完成变更

与 CLI 的关系：斜杠命令驱动 AI 在仓库内生成/修改文件；CLI 多用于列出变更、状态、初始化等（见第 7 节）。二者互补，按场景选用。

5. 命令模式：核心集与扩展集

OpenSpec 可能默认仅启用 核心模式（少量命令）。若需使用上表中的完整斜杠命令集，需在配置中切换为 Expanded Profile（具体项名以官方为准，如通过 openspec config profile 或项目内配置切换）。

建议在团队内统一 Profile，避免有人能用 /opsx:sync、有人不能用的割裂。

6. 推荐工作流（三种典型节奏）

6.1 复杂功能：逐步推进

适合需求复杂、需多轮评审的场景：

  1. /opsx:explore — 澄清需求与技术选型（不落文件）
  2. /opsx:new — 创建变更目录
  3. /opsx:continue — 生成并审阅 proposal.md
  4. /opsx:continue — 生成并审阅 specs/
  5. /opsx:continue — 生成并审阅 design.md
  6. /opsx:continue — 生成并审阅 tasks.md，定稿
  7. /opsx:apply — 按任务清单实现代码
  8. /opsx:verify — 验证并修复偏差
  9. /opsx:sync — 合并规范到主库（若团队维护 openspec/specs/）
  10. /opsx:archive — 归档变更

6.2 小型快速迭代

适合范围小、需求已对齐的场景：

  1. /opsx:ff — 快进生成 proposal / specs / design / tasks
  2. /opsx:apply — 编码
  3. /opsx:verify — 验证
  4. /opsx:archive — 归档（按需再执行 sync）

6.3 规范先行：团队协作

在项目或模块启动时先沉淀全局可复用规范（代码风格、API 设计原则、目录约定等），写入 openspec/specs/ 或通过 /opsx:explore + /opsx:new 建立初始主规范；后续每个功能变更从主规范派生 delta，开发完成后用 /opsx:sync 回写主库，保证团队知识库与代码同步演进。

7. 命令行 CLI（补充参考）

以下常见于自动化与脚本；参数以 openspec --help 与官方文档为准。

场景典型命令（示意）
查看版本openspec --version
列出变更openspec list / openspec list --json
新建变更容器openspec new change "<short-name>"
变更状态openspec status --change "<name>"
生成某类工件指引openspec instructions proposal --change "<name>" 等
实施指引openspec instructions apply --change "<name>"

常见节奏：list → status → instructions * → 人工/AI 补全文件；或与斜杠命令混用。

8. 端到端要点（前端实现向）

  • 命名：变更目录使用团队约定（如 kebab-case）。
  • proposal.md：范围、非目标、验收标准、风险；接口与页面边界写清。
  • design.md：路由、状态、组件边界、与现有模块关系。
  • tasks.md：按可交付块拆分（如 API 封装 → 页面骨架 → 联调），标注依赖。
  • specs/：可用 Scenario / Given-When-Then 描述行为与边界。
  • 实现：对照 tasks.md；技术约束以 config.yaml / project.md / guides/ 为准。
  • 验收：以 proposal 验收条款为自测清单；有 verify 则在合入前执行。

9. 上下文与协作习惯

做法说明
规范先行先稳定 proposal 与 specs，再大规模 /opsx:apply，减少「写完才发现理解错了」。
迭代修正实现中发现偏差时，直接改规格或设计；再次 /opsx:apply 时按任务从中断处继续（以工具实际行为为准）。
版本控制将 openspec/ 整体纳入 Git，保留规范演化历史，便于多人协作与 Code Review。
上下文文件除 config.yaml 外，可用 openspec/project.md（或官方推荐文件名）维护技术栈、架构模式、禁止项，减少 AI 偏离项目惯例。
长文放 guides具体 API、目录规范放在 guides/*.md，规格中只写摘要与链接。

10. 归档

方式一（工具）：使用 /opsx:archive 或 /opsx:bulk-archive，由 OpenSpec 完成目录移动、索引与状态标记（以官方行为为准）。

方式二（手工）：将 openspec/changes/<name>/ 移至 openspec/changes/archive/<name>/（或团队约定的归档路径）；在 proposal.md 等文首标注 「状态：已归档」；更新 openspec/changes/README.md 中的索引；全局替换文内旧路径，避免链接失效。

归档是决策快照，便于审计与复盘，不等于删除历史。

11. 常见问题

问题建议
小需求也要走全套吗？可只用轻量 proposal + tasks，或 /opsx:ff 快进；以团队约定为准。
斜杠命令与 CLI 冲突吗？不冲突：前者驱动 AI 写仓库文件，后者偏列表、状态与自动化。
与产品文档的关系？OpenSpec 承载工程可交付规格；PRD/原型可链接，避免大段复制（防泄密与过时）。
命令与文档不一致？以官方 CLI --help 与当前 OpenSpec 版本说明为准；必要时在团队内维护「已验证命令表」。

12. 延伸阅读

  • OpenSpec 公开仓库与文档：搜索 Fission-AI OpenSpec（GitHub / 官方文档站）。
avatar
文章
阅读
粉丝