1. 一句模糊需求為什么總是寫崩Vibe Coding 最爽的時刻是你對著 AI 說一句“幫我做個用戶登錄”然后它嘩嘩給你吐代碼。最崩的時刻是三天后你發(fā)現(xiàn)登錄接口寫完了但密碼強度校驗沒做、錯誤碼沒統(tǒng)一、前端拿到的字段名和后端對不上。你回頭翻聊天記錄發(fā)現(xiàn)當初那句“幫我做個用戶登錄”里壓根沒定義什么叫“做完”。我試過純靠對話推進一個中型功能結果就是需求在對話里漂移。第一輪說“郵箱登錄”第三輪變成“郵箱手機號”第五輪又加了個“記住我”。AI 每次都老老實實按最新一句話改但前面已經落地的代碼沒人回頭對齊。這不是 AI 的問題是流程的問題——我們把“需求澄清”和“代碼生成”揉在了一次對話里而這兩件事本該分開。Spec Workflow MCP 解決的正是這個斷層。它是一個基于 Model Context Protocol 的開發(fā)輔助服務核心思路是“規(guī)范即上下文”先把模糊需求固化成結構化的規(guī)格說明requirements、技術設計design和任務清單tasks再讓 AI 基于這份穩(wěn)定上下文去寫代碼。它適合誰適合已經在用 Claude Code、Cursor、Cline 這類 AI 編程工具但被“需求反復、任務丟失、協(xié)作靠嘴”折磨的開發(fā)者。一句話它把 Vibe Coding 從“聊天式寫碼”拉回到“可追蹤的工程流程”。這篇不聊概念直接給你可復制的 MCP 配置、一次端到端驗證動作以及我踩過的報錯。你跟著做能把一句“做個用戶登錄”拆成一份帶驗收標準的任務清單。2. TaoToken 前置給 Spec Workflow MCP 配一個穩(wěn)定的模型入口Spec Workflow MCP 本身不產生智能它負責組織上下文、生成文檔骨架、管理任務狀態(tài)真正寫 requirements.md、design.md 里那些內容的還是背后的大模型。所以你需要一個能穩(wěn)定調用模型的入口。我用的是 TaoToken它提供 OpenAI 兼容的 APIBase URL 是https://taotoken.net/api可以直接填進 Claude Code、Cline、Codex 這類客戶端的模型配置里。為什么要在 Spec Workflow 場景下單獨說模型入口因為規(guī)格生成是“長上下文 多輪工具調用”的活兒。AI 要讀你的 steering 文檔、讀已有 specs、再寫新文檔一次請求里塞進去的上下文比普通補全大得多。如果模型入口不穩(wěn)定你會看到 MCP 工具調用到一半斷流儀表盤上任務狀態(tài)卡在“生成中”。把模型入口固定下來是讓整個工作流可復現(xiàn)的前提。具體怎么接分兩條路。一條是 Claude Code 用戶通過環(huán)境變量把 Anthropic 兼容端點指過去另一條是 Cline / Cursor 用戶在 MCP 客戶端里同時配好模型 provider 和 spec-workflow 這個 server。下面兩節(jié)分別給配置。先拿 Key打開https://taotoken.net/api-keys創(chuàng)建一個 API Key復制出來。注意這個 Key 只在創(chuàng)建時完整顯示一次丟了就重建。拿到后先別急著填我們下一步在配置文件里一次性寫全三件套Base URL、Key、Model ID。提示Spec Workflow MCP 的文檔生成質量跟模型能力直接相關。拆任務、寫驗收標準這種活兒建議用推理能力強的模型 ID別用最便宜的小模型否則 tasks.md 會拆得又粗又漏。3. 可復制配置settings.json 與 Claude Code 三件套這一節(jié)是全文最該抄的部分。我按客戶端分開寫你對照自己的工具選一段。先說 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 的模型入口通過環(huán)境變量指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 生成規(guī)格時會先讀它們所以別空著哪怕每個文件寫三行也比沒有強。4. 端到端驗證從“做個用戶登錄”到任務清單配置好了來跑一次完整流程。目標把“做個用戶登錄”拆成帶驗收標準的任務清單。第一步在 AI 聊天窗口里發(fā)指令。別用“幫我寫登錄代碼”要用觸發(fā) 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里是拆好的任務大概五到八條每條帶一個可勾選的狀態(tài)。第二步驗證任務清單是不是“可執(zhí)行”。打開tasks.md看每條任務是不是滿足三個條件有明確動作實現(xiàn)登錄接口、有輸入輸出接收 emailpassword返回 token、有驗收標準密碼少于 8 位返回 400。如果某條寫成“完善登錄邏輯”這種說明模型拆得不夠細回聊天窗口說Break down task 1.3 into smaller steps with acceptance criteria第三步走審批。在儀表盤上點 Request Approval會生成approvals/user-auth/xxx.json。這一步的意義是讓規(guī)格凍結后面 AI 寫代碼時以這份凍結版本為準不再被聊天里的臨時想法帶偏。第四步執(zhí)行任務。點任務旁的 Copy Prompt把上下文粘回 AIImplement task 1.3: Validate email format and password strength in user-auth spec這時候 AI 拿到的不是一句孤立指令而是完整的 requirements design 當前任務上下文。它生成的代碼會遵守 design.md 里的技術約束比如用你定的哈希算法而不是隨手換個庫。驗證成功的標志儀表盤上任務狀態(tài)從 pending 變 in-progress 再變 done.spec-workflow/specs/user-auth/tasks.md里對應條目被勾選代碼文件出現(xiàn)在項目里且接口路徑跟 design.md 一致。這一套跑通你就有了一個可復現(xiàn)的 Vibe Coding 流程。5. 常見報錯排查401、local proxy failed 與 reading choices這一節(jié)按真實報錯來你遇到哪個對哪個。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。這個報錯通常出現(xiàn)在 MCP server 起來了但模型請求發(fā)不出去。檢查三件事環(huán)境變量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 用戶如果之前登錄過官方賬號環(huán)境變量可能被覆蓋。檢查~/.claude/settings.json里有沒有殘留的oauthAccount字段有就刪掉讓環(huán)境變量生效。Cline 用戶檢查是不是同時開了兩個 provider配置里只留一個。儀表盤打不開但 server 正常。CLI 用戶必須手動加--dashboard參數(shù)光注冊 MCP server 不會自動起 dashboard。另外 dashboard 和 server 必須同時運行關掉 dashboard 審批功能就失效任務狀態(tài)也不會更新。AI 不調用 spec-workflow 工具。檢查 MCP 客戶端里 server 狀態(tài)是不是 connected。Cursor 在設置里看 MCP 面板Claude Code 用claude mcp list看。如果顯示 failed多半是路徑寫錯/path/to/your/project這種占位符沒換成真實路徑。6. 把 Spec Workflow 接進你的日常編碼流跑通一次之后我建議你把 steering 文檔當成項目常駐資產來維護。product.md寫清楚這個產品解決什么問題、不做什么tech.md寫死技術棧和不可協(xié)商的約束比如“所有接口必須返回統(tǒng)一錯誤碼結構”structure.md寫目錄約定。這三份文檔是 AI 生成規(guī)格時的“憲法”寫得越具體后面 tasks.md 拆得越準。日常用法上別每個小改動都開新 spec。一個 spec 對應一個可獨立驗收的功能單元比如“用戶登錄”“購物車結算”。改 bug 或者調樣式這種直接對話就行不用走完整流程。spec 的價值在于“這件事需要多人對齊、需要留痕、需要回頭查為什么這么設計”的時候。另外儀表盤上的審批記錄別當形式。每次 Request Approval 生成的 json 文件其實是你項目的決策日志。三個月后有人問“為什么登錄用 JWT 不用 session”翻approvals/user-auth/里的記錄比翻聊天記錄靠譜得多。如果你還沒配模型入口先去https://taotoken.net/api-keys拿 Key再回來看第 3 節(jié)的配置。接入文檔在https://taotoken.net/doc里面有各客戶端的詳細字段說明。想先試試模型對話效果可以開https://taotoken.net/chat發(fā)一句“幫我拆一個用戶登錄的任務清單”感受一下結構化輸出長什么樣。長期做編碼和 Agent 的直接上 Coding Plan把模型入口固定下來Spec Workflow 的上下文才不會斷在半路。