Pre

Vibe Coding - GitHub官方开源项目spec-kit_spec规范驱动开发

概述

一句话概括：Spec Workflow MCP 是一个基于 Model Context Protocol（MCP）的开发辅助工具，通过结构化规范（Spec）驱动开发流程，结合实时仪表盘与 AI 工具，实现从需求 → 设计 → 任务 → 实现的全流程自动化管理。

---

引言：为什么我们需要“结构化规范驱动开发”？

在现代软件开发中，我们常常面临以下挑战：

• 需求模糊不清，导致反复返工
• 设计与实现脱节，代码偏离初衷
• 任务拆解不清晰，协作效率低下
• 缺乏统一文档，新人上手困难

而 Spec Workflow MCP 正是为解决这些问题而生。它将传统的“文档先行”理念与 AI 辅助编程深度融合，通过一套结构化工作流（Structured Workflow），让 AI 不仅能写代码，还能理解上下文、遵循规范、协同推进项目。

---

核心架构与工作流程

Spec Workflow MCP 的核心思想是 “规范即上下文”（Spec as Context）。它通过以下组件协同工作：

1. MCP Server（AI 上下文提供者）

作为 Model Context Protocol 服务端，Spec Workflow MCP 向 AI 工具（如 Claude、Cursor、Continue 等）提供结构化项目上下文，包括：

• 当前需求文档（Requirements）
• 技术设计方案（Design）
• 任务分解清单（Tasks）
• 项目指导方针（Steering Docs）

2. 实时仪表盘（Dashboard）

提供 Web 或 VSCode 内置界面，用于：

• 查看所有规范状态
• 跟踪任务进度（带可视化进度条）
• 发起文档审批流程
• 导航各类文档

3. 结构化项目目录

项目根目录下自动生成 .spec-workflow/ 文件夹，组织如下：

.spec-workflow/
├── steering/           # 项目指导文档
│   ├── product.md      # 产品愿景
│   ├── tech.md         # 技术决策
│   └── structure.md    # 项目结构
├── specs/              # 功能规范
│   └── user-auth/      # 示例规范
│       ├── requirements.md
│       ├── design.md
│       └── tasks.md
├── approvals/          # 审批记录
└── templates/          # 文档模板

---

工作流程详解

整个开发流程遵循 需求 → 设计 → 任务 → 实现 → 审批 的闭环。

---

快速上手：三步集成到你的开发环境

第一步：配置 MCP 客户端

以 Cursor IDE 为例，在 settings.json 中添加：

{
  "mcp.servers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/your/project/path"]
    }
  }
}

💡 提示：使用 --AutoStartDashboard 参数可自动启动仪表盘（部分客户端支持）。

Claude Code
请将以下命令添加到你的 MCP 配置中：

claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/project

重要说明：

• -y 参数用于跳过 npm 的交互式提示，使安装过程更顺畅（建议加上）。
• -- 分隔符的作用是确保后面的路径参数传递给 spec-workflow 脚本本身，而不是传递给 npx。
• 请将 /path/to/your/project 替换为你实际的项目目录路径。

Windows 用户备选方案（如果上述命令无效）：

claude mcp add spec-workflow cmd.exe /c "npx @pimzino/spec-workflow-mcp@latest /path/to/your/project"

第二步：启动仪表盘（CLI 用户必需）

npx -y @pimzino/spec-workflow-mcp@latest /your/project/path --dashboard --port 3000

访问 http://localhost:3000 即可查看实时项目状态。

第三步：与 AI 对话驱动开发

在 AI 聊天窗口中输入自然语言指令：

• “为购物车功能创建规范，包含添加商品、修改数量、结算”
• “列出所有规范及其状态”
• “执行 spec shopping-cart 中的任务 2.1”

AI 会自动调用 MCP 工具，生成文档、拆解任务，并提供可执行的代码提示。

---

实战案例：创建“用户登录”功能

假设我们要实现一个基础的用户登录功能。

1. 创建规范

向 AI 发出指令：

“Create a spec for user authentication with email and password”

MCP 会自动生成：

• requirements.md：描述功能范围（登录、登出、错误处理）
• design.md：建议使用 JWT、密码哈希、REST API
• tasks.md：拆解为 5 个具体任务（如“实现登录接口”、“添加密码验证”等）

2. 审批与反馈

在仪表盘中点击“Request Approval”，团队成员可在线评论。若需修改，AI 会根据反馈自动更新文档并标记修订版本。

3. 执行任务

点击任务旁的“Copy Prompt”按钮，将上下文粘贴给 AI：

“Implement task 1.3: Validate email format and password strength in user-auth spec”

AI 将基于完整的规范上下文生成符合设计约束的代码，而非孤立片段。

---

多语言支持与国际化

Spec Workflow MCP 支持 11 种语言，包括中文、日文、阿拉伯语等。这意味着：

• 文档模板可本地化
• 仪表盘界面自动适配系统语言
• 非英语团队也能高效使用

这对于跨国团队或本土化项目尤为重要。

---

常见问题与解决方案

问题	原因	解决方案
仪表盘无法启动	未加 --dashboard 参数	确保命令包含 --dashboard
审批功能失效	仪表盘未运行	MCP Server 与 Dashboard 必须同时运行
端口冲突	指定端口被占用	改用 --port 8080 或省略端口自动分配
AI 无法识别 spec	项目路径错误	检查配置中的 /path/to/your/project 是否正确

📌 关键提醒：Dashboard 是工作流的“控制中心”，没有它，审批、进度跟踪等功能将完全失效。

---

总结：Spec Workflow MCP 带来了什么？

• 结构化开发：强制规范先行，减少模糊需求
• AI 上下文增强：让 AI 理解“为什么这样设计”，而非仅“如何写代码”
• 全流程可视化：从需求到实现，状态一目了然
• 协作友好：审批、反馈、修订闭环支持团队协作
• 开箱即用：支持主流 AI 工具与 IDE，5 分钟即可集成

对于希望提升开发质量、减少沟通成本、拥抱 AI 编程的团队来说，Spec Workflow MCP 提供了一条规范、高效、可追溯的现代化开发路径。

---

官方Github

https://github.com/Pimzino/spec-workflow-mcp/

🌟 小建议：如果你正在使用 Claude、Cursor 或 Continue，不妨今天就尝试集成 Spec Workflow MCP——让 AI 成为你的“规范协作者”，而不仅仅是“代码生成器”。