Spec Coding 实战指南：用 OpenSpec 框架构建生产级 AI 开发流

TL;DR: OpenSpec 是目前最通用的 Spec Coding 开源框架。通过 /opsx:propose → /opsx:apply → /opsx:archive 三步工作流，你可以让 AI 在结构化规格的约束下产出生产级代码。本文将通过一个完整的实战案例，手把手教你从安装到归档的全流程。

引言

在了解了 Spec Coding 的理论基础后，你可能会好奇：在真实的 IDE 中，这一切是如何运作的？我该用什么工具来管理规格文件？

答案是 OpenSpec——由 Fission-AI 开源的 Spec Coding 框架（MIT 协议）。它支持 20+ 主流 AI 编程助手，提供了一套完整的制品驱动开发工作流。

OpenSpec 是什么？

OpenSpec 是一个轻量级的规格层（spec layer），它在你和 AI 之间建立一个"先对齐再编码"的契约。其核心哲学：

→ fluid not rigid        （流动，而非僵化）
→ iterative not waterfall （迭代，而非瀑布）
→ easy not complex        （简单，而非复杂）
→ built for brownfield    （适用于已有项目）
→ scalable from personal projects to enterprises （从个人到企业可扩展）

每一个变更（change）都会生成一组标准化制品：

5 分钟安装与初始化

前置条件：Node.js 20.19.0 或更高版本。

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

cd your-project
openspec init

openspec init 会在项目根目录创建 openspec/ 目录和 AI 指导文件。初始化完成后，你可以直接在 AI 编程助手中使用斜杠命令。

也支持 pnpm、yarn、bun 和 nix。详见 安装文档。

实战三剑客：OpenSpec + CLAUDE.md + .cursorrules

在 2026 年的 AI 编程生态中，这三者构成了 Spec Coding 的完整工具链：

1. OpenSpec：制品驱动的开发框架，通过斜杠命令管理变更的完整生命周期。
2. CLAUDE.md：源自 Anthropic 的项目记忆规范。它像是一个"项目总纲"，记录了项目的核心架构、技术栈选择和已有的规约。
3. .cursorrules：IDE 级别的指令集，用于强制 AI 遵守代码风格（如：使用 TypeScript 严格模式、禁止内联样式）。

三者分工明确：OpenSpec 管流程，CLAUDE.md 管记忆，.cursorrules 管风格。

完整实战：用 OpenSpec 开发"食谱搜索"功能

我们将演示 OpenSpec 的完整三步工作流。

第一步：/opsx:propose — 提出变更

不要直接对 AI 说"写个搜索"。使用 OpenSpec 的 propose 命令：

/opsx:propose add-recipe-search

AI 会自动创建 openspec/changes/add-recipe-search/ 目录并生成四个制品：

openspec/changes/add-recipe-search/
├── proposal.md    ← 为什么要做这个功能
├── specs/         ← 需求和验收场景
│   └── search-recipe.md
├── design.md      ← 技术方案
└── tasks.md       ← 实施清单

其中 specs/search-recipe.md 会包含结构化的验收标准：

## 需求背景
用户需要通过关键词搜索已有的食谱，并支持按"烹饪时间"过滤。

## 验收场景 (Scenarios)
#### 场景 1: 基础关键词搜索
- **WHEN** 用户输入 "鸡蛋"
- **THEN** 系统应返回所有标题包含 "鸡蛋" 的食谱列表

#### 场景 2: 空状态处理
- **WHEN** 搜索结果为空
- **THEN** 系统应显示"未找到相关食谱"的提示，并推荐 3 个热门食谱

## 约束条件 (Constraints)
- 搜索接口响应时间必须 < 200ms
- 搜索结果需支持分页

tasks.md 会生成实施清单：

## 实施任务
- [ ] 1.1 创建搜索 API Endpoint (`/api/recipes/search`)
- [ ] 1.2 实现全文搜索逻辑（使用已有的 Prisma 查询）
- [ ] 2.1 实现搜索 UI 组件（SearchBar + ResultList）
- [ ] 2.2 添加"烹饪时间"过滤器
- [ ] 3.1 编写 API 层单元测试
- [ ] 3.2 编写组件级 E2E 测试

此时你需要做的是：审查这些制品，确保 AI 理解了你的意图。 你可以随时修改任何制品——OpenSpec 的哲学是"fluid not rigid"，没有僵化的阶段门。

第二步：/opsx:apply — 逐任务执行

确认制品后，执行实现命令：

/opsx:apply

AI 会按 tasks.md 中的清单逐任务执行。输出类似：

Implementing tasks...
✓ 1.1 创建搜索 API Endpoint
✓ 1.2 实现全文搜索逻辑
✓ 2.1 实现搜索 UI 组件
✓ 2.2 添加烹饪时间过滤器
✓ 3.1 编写 API 层单元测试
✓ 3.2 编写 E2E 测试
All tasks complete!

关键优势：AI 每次只读取一个任务和相关的规格上下文，这种"小步快跑"模式极大减少了幻觉概率。相比于一次性抛给 AI 一个模糊需求，任务粒度的执行将有效输出率提升至 95% 以上。

第三步：/opsx:archive — 归档变更

所有任务完成并通过测试后：

/opsx:archive

OpenSpec 会将变更归档到 openspec/changes/archive/ 目录，并附上时间戳：

openspec/changes/archive/2026-04-01-add-recipe-search/

这意味着你拥有了完整的变更历史。 即便三个月后重新回顾这个功能，你也能通过 proposal.md 快速理解"为什么当时这么做"。

扩展工作流

除了核心三步命令，OpenSpec 还提供了扩展工作流（通过 openspec config profile 选择并 openspec update 启用）：

OpenSpec vs. 竞品对比

如何写出高质量的 Spec？(黄金法则)

一份好的规格说明书应该具备以下三要素：

1. 使用 WHEN/THEN 语法：这种行为驱动开发（BDD）的语法对 AI 极其友好，因为它明确了输入和预期输出。
2. 明确边界条件：告诉 AI 如果用户输入非法字符、断网或数据为空时该怎么办。
3. 定义"不准做的事"：在规格中明确禁止的行为（如：禁止修改数据库 Schema，禁止使用第三方库）。

避坑指南：Spec Coding 的常见错误

• 过度规格化 (Over-specifying)：OpenSpec 的哲学是"fluid not rigid"。如果你把每一行代码怎么写都规定死了，那你就失去了 AI 的灵活性。Spec 应该关注"结果"，而非"指令"。
• 忽略单一事实来源 (SSOT)：如果你在对话中改了需求，但没改 specs/ 目录中的文件，AI 很快就会陷入逻辑混乱。记住：需求变了，先改 Spec。
• 缺乏任务验证：每完成一个任务，必须让 AI 运行对应的测试，而不是仅仅相信它的"我写完了"的回复。
• 不归档变更：/opsx:archive 不是可选步骤。归档意味着知识的持久化——三个月后你或你的队友可以通过归档快速理解变更历史。

模型推荐与上下文建议

OpenSpec 在高推理能力模型上效果最佳。官方推荐：

• 规划阶段：Opus 4.5、GPT 5.2
• 实现阶段：Opus 4.5、GPT 5.2

上下文卫生：在开始 /opsx:apply 前，建议清理 AI 的上下文窗口，确保 AI 专注于当前变更的制品而非历史对话。

总结

Spec Coding 是从"玩具项目"迈向"生产级项目"的分水岭。通过 OpenSpec 的三步工作流（propose → apply → archive），你可以让 AI 成为你真正的资深开发搭档，而不是一个偶尔出错的实习生。

准备好更进一步了吗？了解如何通过 Harness Engineering 为你的 AI Agent 搭建一个自动化运行环境。

相关阅读：

• Spec Coding 概念完全指南
• Vibe Coding 实战指南：从 Cursor 到 Claude Code
• Context Engineering: 如何为 AI 提供最完美的上下文