/ 目录 / 演练场 / Spec Workflow
● 社区 Pimzino ⚡ 即开即用

Spec Workflow

作者 Pimzino · Pimzino/spec-workflow-mcp

结构化的需求→设计→任务工作流,配有实时看板和人工审批节点——让 Claude 不再拿到一句话就冲去写代码。

Spec Workflow 将功能开发变成三阶段流水线:需求文档、设计文档、任务列表。每个阶段都需要审批(通过 Web 看板或 VSCode 侧边栏)才能继续。Claude 无法跳过阶段,会写实现日志,并追踪每个任务的进度状态。体验类似「Claude 专属的 Jira」。

为什么要用

核心特性

实时演示

实际使用效果

spec-workflow-mcp.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "spec-workflow-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pimzino/spec-workflow-mcp@latest",
        "/path/to/project"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "spec-workflow-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pimzino/spec-workflow-mcp@latest",
        "/path/to/project"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "spec-workflow-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pimzino/spec-workflow-mcp@latest",
        "/path/to/project"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "spec-workflow-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pimzino/spec-workflow-mcp@latest",
        "/path/to/project"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "spec-workflow-mcp",
      "command": "npx",
      "args": [
        "-y",
        "@pimzino/spec-workflow-mcp@latest",
        "/path/to/project"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "spec-workflow-mcp": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@pimzino/spec-workflow-mcp@latest",
          "/path/to/project"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

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

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: Spec Workflow

用规格文档而非直觉 prompt 来开发功能

👤 开发中等复杂度功能的工程师 ⏱ ~90 min intermediate

何时使用: 你打算让 Claude「加个 OAuth」,但已经开始害怕那个一口气扔过来的 500 行 diff。

前置条件
  • 已知项目路径 — 启动 MCP 时以 /path/to/project 为参数
步骤
  1. 需求阶段
    使用 spec-workflow。创建一个名为 oauth-login 的 spec。先写需求——我们要加什么、面向谁、非目标是什么?✓ 已复制
    → 需求文档草稿已生成,附看板审批链接
  2. 审批 + 设计
    我在看板中已审批。现在写设计文档:组件、数据模型、时序图、错误处理。✓ 已复制
    → 包含具体架构的设计文档
  3. 任务 + 执行
    我已审批。拆分成任务。然后执行任务 1.1——只做这一个,做完停下来。✓ 已复制
    → 任务列表已创建;只有任务 1.1 被实现,并有日志记录

结果: 功能交付时附有可审查的中间产物,而非一个来路不明的大 diff。

注意事项
  • Claude 试图直接跳到写代码 — MCP 会阻止这一行为——但 prompt 里也要明确写「还不要实现」
搭配使用: github · filesystem

让非技术干系人在写代码前审批规格文档

👤 需要 PM/设计审批流程的团队 ⏱ ~60 min intermediate

何时使用: 你需要 PM 在开始实现前批准方案,但 PM 不看 GitHub PR。

前置条件
  • 看板 URL 可共享 — 通过端口转发或 ngrok 将 localhost:5000 暴露给远程 PM
步骤
  1. 起草规格
    checkout-v2 起草需求文档,并分享看板 URL。✓ 已复制
    → 文档已生成,附可共享链接
  2. 根据反馈迭代
    PM 在看板中留了 3 条修改意见。拉取这些意见并修改文档。✓ 已复制
    → 文档已更新,修改记录可见
  3. 审批后执行
    刚刚通过审批——进入设计阶段。✓ 已复制
    → 下一阶段开始,审批时间戳已记录

结果: 来自非技术干系人的可追溯审批链。

注意事项
  • 看板对远程用户不可访问 — 使用带认证的 Tailscale 或 ngrok
搭配使用: github

组合

与其他 MCP 搭配,撬动十倍杠杆

spec-workflow-mcp + github

每个审批任务对应开一个 PR

执行任务 2.1 后,开一个标题为 "feat(oauth): task 2.1" 的 GitHub PR,附上 diff。✓ 已复制
spec-workflow-mcp + filesystem

将规格文档与代码一起存入仓库

将审批通过的规格文档保存到 /docs/specs/oauth-login.md 并提交。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
create_spec name: str 启动新功能开发 free
write_requirements spec_id, content: markdown 任何 spec 的第一阶段 free
write_design spec_id, content: markdown 需求审批通过后 free
create_tasks spec_id, tasks: [] 设计审批通过后 free
execute_task spec_id, task_id 每次执行一个任务 free
get_approval_status spec_id, stage 进入下一阶段前的门控检查 free

成本与限制

运行它的成本

API 配额
本地
每次调用 Token 数
与文档/任务大小成正比
费用
免费
提示
保持需求简洁——审批的成本是人力时间,不是 token

安全

权限、密钥、影响范围

最小权限: filesystem-write (for spec docs)
凭据存储:
数据出站: 无——看板只在 localhost

故障排查

常见错误与修复

Dashboard won't load

显式启动:npx -y @pimzino/spec-workflow-mcp@latest --dashboard

验证: Visit localhost:5000
Port 5000 already in use (macOS AirPlay)

传入 --port 5050,或在系统设置中关闭 AirPlay 接收器

验证: Check with `lsof -i :5000`
Tasks stay in pending after approval

MCP 客户端可能缓存了旧的工具结果——重启客户端

替代方案

Spec Workflow 对比其他方案

替代方案何时用它替代权衡
Plain Markdown in /docs独立开发者,不需要审批流程没有结构约束,没有看板
Linear MCP你已经在用 Linear 管理任务,希望 Claude 直接操作 Issue没有规格文档层

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills