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