1. 一句模糊需求为什么总是写崩Vibe Coding 最爽的时刻是你对着 AI 说一句“帮我做个用户登录”然后它哗哗给你吐代码。最崩的时刻是三天后你发现登录接口写完了但密码强度校验没做、错误码没统一、前端拿到的字段名和后端对不上。你回头翻聊天记录发现当初那句“帮我做个用户登录”里压根没定义什么叫“做完”。我试过纯靠对话推进一个中型功能结果就是需求在对话里漂移。第一轮说“邮箱登录”第三轮变成“邮箱手机号”第五轮又加了个“记住我”。AI 每次都老老实实按最新一句话改但前面已经落地的代码没人回头对齐。这不是 AI 的问题是流程的问题——我们把“需求澄清”和“代码生成”揉在了一次对话里而这两件事本该分开。Spec Workflow MCP 解决的正是这个断层。它是一个基于 Model Context Protocol 的开发辅助服务核心思路是“规范即上下文”先把模糊需求固化成结构化的规格说明requirements、技术设计design和任务清单tasks再让 AI 基于这份稳定上下文去写代码。它适合谁适合已经在用 Claude Code、Cursor、Cline 这类 AI 编程工具但被“需求反复、任务丢失、协作靠嘴”折磨的开发者。一句话它把 Vibe Coding 从“聊天式写码”拉回到“可追踪的工程流程”。这篇不聊概念直接给你可复制的 MCP 配置、一次端到端验证动作以及我踩过的报错。你跟着做能把一句“做个用户登录”拆成一份带验收标准的任务清单。2. TaoToken 前置给 Spec Workflow MCP 配一个稳定的模型入口Spec Workflow MCP 本身不产生智能它负责组织上下文、生成文档骨架、管理任务状态真正写 requirements.md、design.md 里那些内容的还是背后的大模型。所以你需要一个能稳定调用模型的入口。我用的是 TaoToken它提供 OpenAI 兼容的 APIBase URL 是https://taotoken.net/api可以直接填进 Claude Code、Cline、Codex 这类客户端的模型配置里。为什么要在 Spec Workflow 场景下单独说模型入口因为规格生成是“长上下文 多轮工具调用”的活儿。AI 要读你的 steering 文档、读已有 specs、再写新文档一次请求里塞进去的上下文比普通补全大得多。如果模型入口不稳定你会看到 MCP 工具调用到一半断流仪表盘上任务状态卡在“生成中”。把模型入口固定下来是让整个工作流可复现的前提。具体怎么接分两条路。一条是 Claude Code 用户通过环境变量把 Anthropic 兼容端点指过去另一条是 Cline / Cursor 用户在 MCP 客户端里同时配好模型 provider 和 spec-workflow 这个 server。下面两节分别给配置。先拿 Key打开https://taotoken.net/api-keys创建一个 API Key复制出来。注意这个 Key 只在创建时完整显示一次丢了就重建。拿到后先别急着填我们下一步在配置文件里一次性写全三件套Base URL、Key、Model ID。提示Spec Workflow MCP 的文档生成质量跟模型能力直接相关。拆任务、写验收标准这种活儿建议用推理能力强的模型 ID别用最便宜的小模型否则 tasks.md 会拆得又粗又漏。3. 可复制配置settings.json 与 Claude Code 三件套这一节是全文最该抄的部分。我按客户端分开写你对照自己的工具选一段。先说 Cursor / Cline 这类走settings.json或 MCP 配置文件的。Spec Workflow MCP 的 server 配置和模型 provider 配置是两块别混在一起。server 这块长这样{ mcpServers: { spec-workflow: { command: npx, args: [ -y, pimzino/spec-workflow-mcplatest, /Users/you/project/demo-app ], env: { SPEC_WORKFLOW_DASHBOARD: true, SPEC_WORKFLOW_PORT: 3000 } } } }路径/Users/you/project/demo-app换成你真实项目根目录Windows 写成C:\\code\\demo-app这种双反斜杠或正斜杠都行。-y是跳过 npx 的交互确认不加它有时候会卡在“Ok to proceed?”上MCP 客户端等不到输入就超时。然后是模型 provider 这块以 Cline 为例在它的 API 配置里选 OpenAI Compatible填三件套{ apiProvider: openai, openAiBaseUrl: https://taotoken.net/api, openAiApiKey: sk-你的Key, openAiModelId: claude-sonnet-4-5 }Model ID 按你实际能用的填别照抄。Base URL 结尾不要带/v1TaoToken 的兼容层会自己处理路径。Claude Code 用户走命令行一条命令搞定 server 注册claude mcp add spec-workflow npx pimzino/spec-workflow-mcplatest -- /Users/you/project/demo-app注意--这个分隔符它保证后面的路径传给 spec-workflow 脚本本身而不是被 npx 吃掉。Windows 上如果这条报错换成claude mcp add spec-workflow cmd.exe /c npx pimzino/spec-workflow-mcplatest C:\code\demo-appClaude Code 的模型入口通过环境变量指export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key export ANTHROPIC_MODELclaude-sonnet-4-5三件套齐了Base URL、Key、Model ID。少任何一个MCP 工具调用都会在生成文档那步失败。配完 server 后CLI 用户还需要单独起仪表盘因为审批和进度跟踪全靠它npx -y pimzino/spec-workflow-mcplatest /Users/you/project/demo-app --dashboard --port 3000浏览器开http://localhost:3000能看到 specs 列表就说明 server 和 dashboard 都活了。项目根目录下会自动生成.spec-workflow/文件夹里面有steering/、specs/、approvals/、templates/四个子目录。steering 里放产品愿景、技术决策、项目结构三份指导文档AI 生成规格时会先读它们所以别空着哪怕每个文件写三行也比没有强。4. 端到端验证从“做个用户登录”到任务清单配置好了来跑一次完整流程。目标把“做个用户登录”拆成带验收标准的任务清单。第一步在 AI 聊天窗口里发指令。别用“帮我写登录代码”要用触发 spec 生成的说法Create a spec for user authentication with email and passwordAI 会调用 spec-workflow 的 create-spec-doc 工具依次生成三份文档。等它跑完去.spec-workflow/specs/user-auth/看requirements.md里应该有功能范围比如登录、登出、错误处理、密码强度要求design.md里应该有技术选型比如 JWT、密码哈希算法、REST 接口路径tasks.md里是拆好的任务大概五到八条每条带一个可勾选的状态。第二步验证任务清单是不是“可执行”。打开tasks.md看每条任务是不是满足三个条件有明确动作实现登录接口、有输入输出接收 emailpassword返回 token、有验收标准密码少于 8 位返回 400。如果某条写成“完善登录逻辑”这种说明模型拆得不够细回聊天窗口说Break down task 1.3 into smaller steps with acceptance criteria第三步走审批。在仪表盘上点 Request Approval会生成approvals/user-auth/xxx.json。这一步的意义是让规格冻结后面 AI 写代码时以这份冻结版本为准不再被聊天里的临时想法带偏。第四步执行任务。点任务旁的 Copy Prompt把上下文粘回 AIImplement task 1.3: Validate email format and password strength in user-auth spec这时候 AI 拿到的不是一句孤立指令而是完整的 requirements design 当前任务上下文。它生成的代码会遵守 design.md 里的技术约束比如用你定的哈希算法而不是随手换个库。验证成功的标志仪表盘上任务状态从 pending 变 in-progress 再变 done.spec-workflow/specs/user-auth/tasks.md里对应条目被勾选代码文件出现在项目里且接口路径跟 design.md 一致。这一套跑通你就有了一个可复现的 Vibe Coding 流程。5. 常见报错排查401、local proxy failed 与 reading choices这一节按真实报错来你遇到哪个对哪个。401 Unauthorized。最常见两种原因。一是 Key 没填对或过期去https://taotoken.net/api-keys重建一个。二是 Base URL 写错有人填成https://taotoken.net/api/v1多了个/v1兼容层反而找不到。正确写法就是https://taotoken.net/api。改完重启 MCP 客户端别指望热加载。local proxy failed / connection refused。这个报错通常出现在 MCP server 起来了但模型请求发不出去。检查三件事环境变量ANTHROPIC_BASE_URL或openAiBaseUrl有没有生效在终端echo $ANTHROPIC_BASE_URL看一眼有没有别的程序占了 3000 端口换--port 8080npx 缓存坏了删掉~/.npm/_npx重跑。Error reading choices / unexpected token。这个多半是模型返回的 JSON 被截断了。Spec 生成时上下文很长如果 Model ID 填的是上下文窗口小的模型写到 tasks.md 一半就断MCP 解析失败。换成窗口更大的模型 ID或者在 steering 文档里精简内容别把整个产品文档塞进去。OAuth / authentication failed。Claude Code 用户如果之前登录过官方账号环境变量可能被覆盖。检查~/.claude/settings.json里有没有残留的oauthAccount字段有就删掉让环境变量生效。Cline 用户检查是不是同时开了两个 provider配置里只留一个。仪表盘打不开但 server 正常。CLI 用户必须手动加--dashboard参数光注册 MCP server 不会自动起 dashboard。另外 dashboard 和 server 必须同时运行关掉 dashboard 审批功能就失效任务状态也不会更新。AI 不调用 spec-workflow 工具。检查 MCP 客户端里 server 状态是不是 connected。Cursor 在设置里看 MCP 面板Claude Code 用claude mcp list看。如果显示 failed多半是路径写错/path/to/your/project这种占位符没换成真实路径。6. 把 Spec Workflow 接进你的日常编码流跑通一次之后我建议你把 steering 文档当成项目常驻资产来维护。product.md写清楚这个产品解决什么问题、不做什么tech.md写死技术栈和不可协商的约束比如“所有接口必须返回统一错误码结构”structure.md写目录约定。这三份文档是 AI 生成规格时的“宪法”写得越具体后面 tasks.md 拆得越准。日常用法上别每个小改动都开新 spec。一个 spec 对应一个可独立验收的功能单元比如“用户登录”“购物车结算”。改 bug 或者调样式这种直接对话就行不用走完整流程。spec 的价值在于“这件事需要多人对齐、需要留痕、需要回头查为什么这么设计”的时候。另外仪表盘上的审批记录别当形式。每次 Request Approval 生成的 json 文件其实是你项目的决策日志。三个月后有人问“为什么登录用 JWT 不用 session”翻approvals/user-auth/里的记录比翻聊天记录靠谱得多。如果你还没配模型入口先去https://taotoken.net/api-keys拿 Key再回来看第 3 节的配置。接入文档在https://taotoken.net/doc里面有各客户端的详细字段说明。想先试试模型对话效果可以开https://taotoken.net/chat发一句“帮我拆一个用户登录的任务清单”感受一下结构化输出长什么样。长期做编码和 Agent 的直接上 Coding Plan把模型入口固定下来Spec Workflow 的上下文才不会断在半路。