OpenSpec + Superpowers 实战：在 Claude Code 中打通 Apifox 接口文档与原型驱动的规范开发

一、从“AI 写代码”到“AI 写对代码”

2024 年到 2026 年，AI 编程工具经历了爆发式增长。Claude Code 这类 AI Agent 已经能够自主完成完整的功能开发。但随着 AI 承担的任务范围越来越大，两个问题开始浮现：

第一，设计共识随对话消失。 当你和 AI 在长对话中反复推敲需求时，早期达成的共识很容易被遗忘。/clear 释放上下文后，之前决定好的设计方向荡然无存。

第二，AI 有能力写代码，但没有纪律维护工程质量。 没有外部结构约束时，AI 不会主动先写测试，不会系统定位 bug 根因，也不会在写代码前检查需求是否完整。产出质量完全依赖于人类工程师在每次对话中是否足够谨慎。

有开发者这样形容：“如果没有一套规范驱动的工作流来约束 AI 的行为，‘AI 写代码’很容易变成‘AI 制造技术债’。”

规范驱动开发（Spec-Driven Development，SDD）正是破解这两个问题的关键路径。本文将基于我最近使用 OpenSpec 和 Superpowers 的实操经验，完整展示如何从零到一构建一个项目——包括在 Claude Code 中集成 Apifox 接口文档、依据原型图构建页面，以及通过规范驱动的工作流确保代码质量。

文末附完整操作思维导图，可直接保存存档。

二、OpenSpec：什么是“规范驱动开发”，SDD 如何让 AI 真正照你说的做

2.1 SDD 的核心思想

传统的 AI 辅助编码流程是这样的：用户描述需求 → AI 直接写代码 → 用户检查代码 → 发现不对 → 重来。

SDD 的思路完全不同：用户描述需求 → 生成规范文档（提案/设计/规格/任务）→ AI 按规范实现 → 按规范验证。

核心理念只有一句话：先想清楚再动手，用文档约束行为，用验证确保正确。

2.2 OpenSpec 的 Artifact 链

OpenSpec 是一个嵌入在 AI 编码助手中的结构化开发工作流框架，其核心是一条 Artifact 依赖链：

proposal.md → design.md → specs/*.md → tasks.md → 代码实现 → 归档

Artifact	职责	核心内容
proposal.md	变更提案	为什么做、目标/非目标、影响范围
design.md	设计决策	技术方案选择、替代方案对比、风险评估
specs/*.md	需求规格	Requirements + Scenarios（WHEN/THEN 格式）
tasks.md	任务清单	可执行的 checkbox 任务列表

每个 artifact 都是前一个的细化，而且所有中间状态持久化为文件——这意味着你可以在任意步骤之间安全地 /clear，状态在文件系统中，不在对话历史里。

举个例子，我曾经需要实现一个“启动时检查并拉起后台服务”的功能，用 /opsx:ff（快速通道）一次性说清需求，AI 自动生成了 proposal.md、design.md、4 个场景的 spec、3 个可执行任务，然后逐个 task 实现。

2.3 OpenSpec 的核心命令

OpenSpec 提供了一组命令来驱动整个流程：

命令	作用	说明
/opsx:explore	探索模式	自由思考，不写代码，只讨论
/opsx:propose	提案	生成 proposal + 后续 artifacts
/opsx:ff	快速通道	一次性生成所有 artifacts
/opsx:apply	实现	逐 task 实现代码
/opsx:verify	验证	对照 artifacts 检查实现
/opsx:archive	归档	归档完成的变更

2.4 OpenSpec 安装与初始化

# 全局安装 OpenSpec
npm install -g @fission-ai/openspec@latest

# 在你的项目目录中初始化
cd your-project
openspec init

初始化后，项目根目录会生成 openspec/ 目录结构，包含 specs/（主规格知识库）和 changes/（变更目录）。

三、Superpowers：给 AI 装上“执行纪律”

如果说 OpenSpec 解决的是“写什么”的问题，那 Superpowers 解决的就是“怎么做”的问题——用严格的执行纪律约束 AI 的行为。

3.1 Superpowers 的核心机制

Superpowers 的核心是一套方法论封装机制。它通过 Skill（技能） 将特定能力进行模块化封装，从而实现工作流编排、专家领域知识沉淀以及工具集成。

在实际使用中，Superpowers 会强制遵循 TDD 最佳实践，通过需求澄清、计划编写和两阶段代码审查（代码审查阶段会详细检查 TDD 遵守情况和代码质量），确保 AI 助手一次性通过测试并零报错。

以我熟悉的工作流为例，Superpowers 提供以下核心能力：

• brainstorming：需求探索和设计发散
• TDD：测试驱动的代码实现
• debugging：系统化的 bug 定位
• code review：双阶段代码审查

3.2 如何整合 OpenSpec + Superpowers

OpenSpec 和 Superpowers 各有所长，但单独使用都不够：OpenSpec 有 spec 流程但缺 TDD 纪律，Superpowers 有执行方法论但设计共识无处持久化。因此，真正成熟的方案是把它们整合成一套连贯的 SDD 工作流。

整合的核心理念是 薄编排架构：用户只通过 sdd-* 技能（如 sdd-plan、sdd-code）与 AI 交互，底层分别调用 OpenSpec 和 Superpowers 的能力。

用户 ──→ sdd-* skills（唯一入口）
         │
         ├── invoke → Superpowers skills（brainstorming / TDD / debugging...）
         ├── invoke → OpenSpec skills（continue-change / ff-change / verify...）
         └── SDD 自有逻辑（前置检查 / review 循环 / 产物校验）

它的核心特性和优势在于：

• Action not Phases：每个操作是独立的 action，不是必须按顺序完成的阶段，可以根据需要灵活组合使用。
• 产物接力：每个 action 的输出直接成为下一个 action 的输入，所有中间状态持久化为文件，任意步骤之间可以安全 /clear，不会丢失状态。
• 不修改底层工具：SDD 只是编排层，不修改 OpenSpec 或 Superpowers 的任何原有文件，两个工具保持独立升级能力。

这种设计最大的好处在于：设计共识不再依赖于对话记忆，而是沉淀在文档中；AI 的行为受到 TDD 纪律的约束，不再随心所欲。

四、Claude Code × Apifox MCP：让 AI 自动读取接口文档

在规范驱动的开发流程中，另一个关键的痛点是如何让 AI 准确理解项目的接口定义。如果每次都手动把 Apifox 里的接口文档复制粘贴给 AI，效率低下且容易出错。

4.1 MCP 协议简介

MCP（Model Context Protocol）是由 Anthropic 公司于 2024 年 11 月推出并开源的协议，旨在解决 AI 大模型与外部数据源、工具的集成难题。它允许 Claude Desktop、Claude Code、Cursor 等 MCP 客户端通过标准化接口调用外部工具——数据库、API、web 搜索、文件系统等不限。

简单说，MCP 就是让 AI 能够“主动读取”外部数据源的协议。

4.2 Apifox MCP Server 与安装

Apifox MCP Server 是一个 MCP 服务器，允许 Claude Code 等客户端通过 Apifox Open API 自动导入 OpenAPI/Swagger 规范到你的 Apifox 项目。最关键的能力是：可以将 Apifox 项目内的接口文档作为数据源提供给 AI 工具，让 AI 能够直接访问接口文档数据。

核心功能：

• ✅ API 导入：批量导入 OpenAPI/Swagger 规范到 Apifox
• ✅ API 导出：支持 Summary（目录结构）和 Full（完整规范）两种模式
• ✅ 智能废弃标记：自动检测并标记已删除的接口为废弃状态
• ✅ 多格式支持：OpenAPI 3.0/3.1 和 Swagger 2.0

MCP Server 安装配置全流程：

第一步：获取 Apifox Access Token 和 Project ID

• Token：登录 Apifox → 头像 → 账号设置 → API 访问令牌 → 新建令牌
• 项目 ID：打开项目 → 项目设置 → 基本设置 → 复制项目 ID

第二步：在 Claude Code 中配置 Apifox MCP Server（推荐使用 CLI 命令）：

# 添加 MCP 服务器
claude mcp add apifox

# 按提示输入：
# Command: npx
# Args: -y apifox-openapi-mcp@latest --token "你的-TOKEN" --project-id "你的-项目-ID"

第三步：验证配置是否成功：

claude mcp list
# 应该能看到 apifox 出现在列表中

以上配置流程参考自 [Apifox MCP 服务器文档]，具体路径：glama.ai/mcp/servers…

配置后的大模型对话流程：完成上述配置后，你就可以直接在 Claude Code 中与 AI 对话来使用接口文档了。例如，你可以输入“根据 APIFOX MCP 服务器中的接口文档，生成登录相关的所有 MVC 代码”，AI 会自动调用 MCP 工具读取 Apifox 项目内的接口定义，然后生成对应的代码。

4.3 注意点

接口文档数据默认会缓存在本地。如果 Apifox 内的数据有更新，需要告诉 AI 刷新数据，否则 AI 读到的可能不是最新的。

五、从原型到页面：如何在 Claude Code 中实现设计稿

有了 OpenSpec 的规格文档管理，有了 Superpowers 的纪律约束，有了 Apifox MCP 的接口注入，接下来就是实际开发了。前端环节的核心问题：如何在 Claude Code 中处理设计稿，并让 AI 准确生成符合设计需求的页面代码？

Claude Code 本身无法“看图”，这里分享几种实用思路：

5.1 思路一：在设计工具中完成样式提取

目前主流的设计工具如摹客，支持上传图片后 AI 自动解析页面布局、配色与组件结构，一键生成高保真设计稿。你可以利用这类工具快速得到设计稿，然后从设计稿中抽取出以下要素，整理成文字描述提供给 Claude Code：

• 页面布局结构（Header/Main/Sidebar/Footer 如何布局）
• 组件层级关系
• 色值、字体、间距、圆角等样式变量
• 交互方式和状态变化

把整理后的设计规范文档放入项目目录（或在 Claude Code 对话中直接贴出），AI 就可以按照设计约束来生成代码。

5.2 思路二：使用规范驱动的代码生成

把设计稿抽象成可执行的规格文档：

## 页面规格：用户管理列表

### 布局
- 顶部：搜索栏 + 新增按钮
- 主体：表格，列名依次为 用户名/角色/状态/操作
- 底部：分页组件

### 样式约束
- 主色调：#1890ff
- 表格行高：48px
- 状态标签：进行中=蓝色，已完成=绿色，已取消=灰色

### 接口集成
参考 Apifox MCP 中的 /api/user/list 接口定义

在 Claude Code 中，你可以这样说：

“根据以上页面规格，结合 Apifox MCP 中的用户列表接口，生成完整的用户管理页面代码，使用 React + TypeScript + Tailwind CSS。数据加载显示骨架屏。”

5.3 思路三：交互式原型迭代

在开发过程中，可以分段提供反馈：

• 首先生成页面框架
• 在浏览器中预览，标记需要调整的位置
• 将调整需求（“列表操作栏的按钮间距稍微拉开一些”“状态标签加上圆角”）返回 Claude Code
• 让 AI 进行精准修改

通过这种“生成→反馈→修正”的循环，最终页面可以和设计稿高度对齐。

六、动手实战：从零到一完整项目搭建

下面以一个实际的项目为例，完整展示整个工作流。

项目背景：一个电商后台的“用户管理模块”，包含用户列表、用户详情、新增/编辑用户、删除用户等 CRUD 功能。

6.1 第 1 步：初始化 OpenSpec 项目

# 创建项目目录
mkdir user-management-module
cd user-management-module

# 初始化 OpenSpec
openspec init

# 安装 Superpowers 相关 skills（根据具体 AI 工具配置）
# 在 Claude Code 中直接使用 sdd-* 技能

6.2 第 2 步：通过 SDD 流程生成规格文档

在 Claude Code 中使用 sdd-propose 技能：

“创建一个用户管理功能的变更提案，包含以下核心需求：

1. 用户列表页：分页查询、按用户名/状态筛选
2. 用户详情页：展示用户完整信息
3. 新增/编辑用户：表单验证 + 提交
4. 删除用户：二次确认 + 软删除”

AI 会自动：

• 生成 proposal.md：为什么做、目标和影响范围
• 生成 design.md：技术方案（前端用什么框架、状态管理方案、API 调用方式等）
• 生成 specs/*.md：用 GIVEN/WHEN/THEN 格式描述需求场景
• 生成 tasks.md：可执行的任务清单

6.3 第 3 步：配置 Apifox MCP 注入接口文档

在 Claude Code 中完成 MCP 配置：

claude mcp add apifox

然后在对话中验证接口文档是否可用：

“根据 Apifox MCP 中的 /api/user/list 接口定义，帮我生成对应的 TypeScript 接口类型定义，以及数据获取的 React Hook。”

6.4 第 4 步：依据原型实现页面

我无法在 Claude Code 中直接“看”到设计稿图片，所以需要额外准备一个包含页面设计说明的 design-spec.md 文件，放在项目目录中：

## 用户管理页面设计规范

### 颜色
- 主色：#1677ff
- 成功色：#52c41a
- 警告色：#faad14
- 错误色：#ff4d4f

### 组件库
- 使用 Ant Design 5.x
- Table, Modal, Form, Button, Input, Select 等组件

### 布局
- 列表页：Card 包裹，内部 Filter 表单 + Table
- 弹窗：Modal 形式，内部 Form
- 响应式：桌面优先，最小宽度 1200px

然后在 Claude Code 中指示：

“根据 design-spec.md 的设计规范，以及 Apifox MCP 提供的接口定义，实现用户列表页。包含：筛选表单（用户名输入框、状态下拉框、查询重置按钮）、分页表格（显示用户数据、操作列含编辑/删除按钮）。”

6.5 第 5 步：TDD 驱动的代码实现

使用 sdd-code 技能，AI 会按照 TDD 流程逐 task 实现：

1. 先写单元测试（组件渲染测试、API mock 测试）
2. 然后写实现代码
3. 运行测试验证
4. 进入代码审查环节
5. 修复审查发现的问题后进行最终验证与归档封存

6.6 第 6 步：最终归档和封存

全部任务完成后，使用 sdd-ship 技能：归档所有变更到 openspec/changes/archive/ 目录中，记录完整的变更历史，便于后期维护与追溯。

七、最佳实践与踩坑经验

在使用这套工作流的过程中，我总结了一些实用和个人心得：

问题场景	解决方案	核心价值
AI 遗忘早期需求	关键 decision 沉淀到文档，不要只依赖对话记忆	文档即事实，对话可丢弃
AI 输出质量不稳定	始终先用 workflow（如 sdd-code）约束行为	纪律先于技能
接口文档变更后 AI 不更新	在对话中说明“请刷新 MCP 数据”	状态管理明确
设计稿无法直接上传	将视觉规范抽象为 Markdown 文档放入项目目录	设计即代码的前置步骤
跨 session 上下文丢失	每次新对话先让 AI 读取 openspec/ 目录	复用已有成果而非重启

关键洞察：工具链的核心价值在于——把 AI 的行为从“自由发挥”变成“受控执行”。它解决了 AI 忘记约定、偏离设计、跳过测试等常见问题。写好提示词就能让 AI 输出高质量代码是一种错觉，结构化的工作流才是长期工程质量的保障。

八、总结与展望

OpenSpec 和 Superpowers 这套 SDD 工作流，本质上是把传统软件工程的最佳实践（需求文档、设计文档、规格验证、TDD）适配到了 AI 编码助手的语境中。

未来值得探索的方向包括：

• AI 辅助 spec 自动生成：从需求描述自动生成 Gherkin 场景
• 基于 MCP 的更深度集成：让 AI 不仅能“读”Apifox，还能“写”到 Apifox
• 团队协作：多人在同一个规范驱动工作流中协作
• 性能回归验证：在代码变更后自动检测性能消耗，量化对比前后差异

不管 AI 如何进化，有一条原则不会变：好的代码始于好的规范。 希望这篇文章能为你的 AI 辅助开发实践提供一些实用的参考。

附录：完整实操思维导图

为了让你在开发中快速查阅整套工作流时机与顺序，我绘制和整理了这份端到端规范驱动开发（SDD）的全流程实操决策图：

flowchart TD
    subgraph A[前置准备]
        A1["cd your-project<br>openspec init"] --> A2["配置 Apifox MCP<br>claude mcp add apifox"]
    end

    subgraph B[SDD 工作流]
        B1["sdd-propose<br>生成变更提案"] --> B2["sdd-ff<br>快速生成所有 artifacts"]
        B2 --> B3["将设计规范.md<br>放入项目目录"]
        B3 --> B4["sdd-code<br>逐 task TDD 实现"]
        B4 --> B5["sdd-verify<br>验证实现"]
        B5 --> B6["sdd-ship<br>归档变更"]
    end

    subgraph C[MCP 集成层]
        C1["Claude 读取 Apifox<br>接口文档"] --> C2["自动生成类型定义<br>API 调用代码"]
    end

    A1 --> B1
    A2 --> C1
    B3 --> C2
    C2 --> B4
    B6 --> D[归档到<br>openspec/changes/archive/]

使用要点：从右上角 openspec init 开始入手，随后先配好 MCP，让 AI 能在开发前自动读懂 Apifox 中的 API 定义；再进入中心的 SDD 流程，根据原型设计补充 design-spec.md 文档，执行 sdd-code 时 AI 会强制 TDD 纪律并落地成代码，最终归档形成可追溯变更历史。

---

帮助文档与参考链接：

• OpenSpec GitHub：github.com/Fission-AI/…
• Apifox MCP 服务器：glama.ai/mcp/servers…
• Superpowers 相关文档：github.com/seanf-ai/op…
• Apifox MCP 服务器配置详情：mcprepository.com/Warren-W/ap…