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