1. 為什么要在 Claude Code 里把 Openspec 和 Superpowers 拼起來(lái)用如果你已經(jīng)在 Claude Code 里寫過(guò)幾個(gè)真實(shí)項(xiàng)目大概率遇到過(guò)這兩種別扭一種是讓 AI 直接開(kāi)寫代碼能跑但結(jié)構(gòu)隨緣需求一變就推倒重來(lái)另一種是需求文檔寫得很漂亮但落到代碼時(shí) AI 又開(kāi)始自由發(fā)揮規(guī)范和實(shí)現(xiàn)兩張皮。Openspec 和 Superpowers 正好各治一半——Openspec 是規(guī)范驅(qū)動(dòng)的開(kāi)發(fā)框架主張先定規(guī)范再動(dòng)手、每個(gè)變更獨(dú)立歸檔Superpowers 是編碼 agent 的執(zhí)行框架主張先把需求問(wèn)清楚再拆成 2-5 分鐘能完成的小任務(wù)用 subagent 并行執(zhí)行并做雙重審查。把這兩個(gè)東西組合起來(lái)的思路其實(shí)很樸素用 Openspec 替代 Superpowers 自帶的 brainstorm 環(huán)節(jié)把 Openspec 產(chǎn)出的 tasks.md 直接喂給 Superpowers 的 writing-plans然后關(guān)掉 Openspec 自己的 apply 命令讓實(shí)現(xiàn)環(huán)節(jié)完全交給 Superpowers。這樣需求拆解有規(guī)范兜底代碼生成有執(zhí)行框架約束中間不用人工搬運(yùn)上下文。這篇面向需要在 Claude Code 里做規(guī)范化需求拆解與代碼生成銜接的開(kāi)發(fā)者交付一套可復(fù)制的 settings.json 與 config.toml 骨架、TaoToken 統(tǒng)一 Key/API 通道的接入配置以及工作流跑通后的驗(yàn)證動(dòng)作和報(bào)錯(cuò)排查清單。適合誰(shuí)已經(jīng)裝好 Claude Code、想把手寫 prompt 升級(jí)成可復(fù)用工作流的同學(xué)也適合團(tuán)隊(duì)里想把 AI 輔助開(kāi)發(fā)流程固定下來(lái)的技術(shù)負(fù)責(zé)人。2. 前置準(zhǔn)備TaoToken 統(tǒng)一 Key 與 API 通道接入在配置工作流之前先把模型通道打通。TaoToken 提供統(tǒng)一的 API 入口Claude Code 以及后續(xù) Superpowers 觸發(fā)的 subagent 都走同一個(gè) Key省得每個(gè)插件單獨(dú)配一遍。官網(wǎng)入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 這個(gè)地址不加 UTM 參數(shù)。第一步去控制臺(tái)創(chuàng)建 API Key。打開(kāi) https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登錄后在 API Keys 頁(yè)面新建一個(gè) Key復(fù)制出來(lái)先存到本地環(huán)境變量里別直接寫進(jìn)會(huì)提交到 git 的配置文件。具體操作頁(yè)在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。第二步把 Key 寫進(jìn) shell 環(huán)境。macOS 或 Linux 下編輯~/.zshrc或~/.bashrcexport TAOTOKEN_API_KEYsk-你的key export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY$TAOTOKEN_API_KEYWindows PowerShell 用戶用$env:TAOTOKEN_API_KEYsk-你的key $env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEY$env:TAOTOKEN_API_KEY這里把ANTHROPIC_BASE_URL指向 TaoToken 的 API 基址Claude Code 默認(rèn)讀這兩個(gè)環(huán)境變量改完重開(kāi)終端生效。如果你用的是 Claude Code 的 Anthropic 兼容接入方式參考文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里的說(shuō)明路徑和鑒權(quán)頭都對(duì)齊了不用額外改。注意Key 只放環(huán)境變量或本地未納入版本管理的配置文件別貼進(jìn) settings.json 提交到倉(cāng)庫(kù)。團(tuán)隊(duì)協(xié)作時(shí)用.env.local并加進(jìn).gitignore。3. 可復(fù)制配置settings.json 與 config.toml 骨架Claude Code 的插件與權(quán)限配置放在項(xiàng)目根目錄的.claude/settings.jsonOpenspec 的 profile 配置走它自己的 config.toml。下面兩份骨架可以直接抄改掉路徑和 Key 引用即可。先看.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: ${TAOTOKEN_API_KEY} }, permissions: { allow: [ Bash(openspec:*), Bash(npx openspec:*), Read, Write, Edit ], deny: [ Bash(rm -rf:*), Bash(git push --force:*) ] }, plugins: { openspec: { enabled: true, commandPrefix: opsx }, superpowers: { enabled: true, commandPrefix: superpowers } } }env段里用${TAOTOKEN_API_KEY}引用環(huán)境變量避免明文。permissions.allow放開(kāi) openspec 相關(guān)命令和文件讀寫deny擋住危險(xiǎn)操作這是跑 subagent 并行執(zhí)行時(shí)的基本護(hù)欄。再看 Openspec 的config.toml重點(diǎn)是關(guān)掉 apply 命令把實(shí)現(xiàn)交給 Superpowers[profile] delivery both [workflows] propose true explore true new_change true continue_change true apply_tasks false fast_forward true sync_specs true archive_change true bulk_archive true verify_change true onboard falseapply_tasks false是關(guān)鍵一行。你也可以用交互命令改openspec config profile進(jìn)入后選 Workflows only在列表里把Apply tasks取消勾選其余按需保留回車確認(rèn)。這樣 Openspec 只負(fù)責(zé)規(guī)范產(chǎn)出不碰實(shí)現(xiàn)。Superpowers 側(cè)不需要額外 toml它的 skills 是自動(dòng)觸發(fā)的只要插件啟用、命令前綴對(duì)得上即可。裝插件用npx openspec init npx superpowers init兩條命令會(huì)分別在.claude/下注冊(cè)命令與 skills跑完重啟 Claude Code 讓配置生效。4. 跑通驗(yàn)證從 explore 到 archive 的完整動(dòng)作配置就緒后用一個(gè)小需求把整條鏈路走一遍確認(rèn)每個(gè)環(huán)節(jié)都能接上。下面以給一個(gè)狀態(tài)欄工具加版本指示器為例。第一步探索需求。在 Claude Code 里輸入/opsx:explore把要解決的問(wèn)題聊清楚顯示什么、用什么形式、多色指示具體代表什么狀態(tài)。這一步多花點(diǎn)時(shí)間比邊做邊改快。第二步生成 proposal/opsx:propose ccstatusline-update-indicator系統(tǒng)會(huì)生成 proposal、design、specs、tasks 四個(gè)文件落在openspec/changes/下。檢查tasks.md確認(rèn)任務(wù)粒度合理。第三步寫實(shí)現(xiàn)計(jì)劃/superpowers:writing-plansSuperpowers 會(huì)讀取上一步的tasks.md把每個(gè)任務(wù)拆成 2-5 分鐘可完成的步驟附代碼示例和測(cè)試方法。執(zhí)行完成后它會(huì)提示你選 inline 還是 subagent 方式實(shí)現(xiàn)選 subagent。第四步執(zhí)行/superpowers:subagent-driven-development每個(gè)任務(wù)過(guò)兩道關(guān)Spec 合規(guī)、代碼質(zhì)量。實(shí)測(cè)跑 5 個(gè)任務(wù)都能過(guò)。第五步驗(yàn)證需求/opsx:verify這一步別跳過(guò)。之前實(shí)測(cè)就發(fā)現(xiàn)過(guò)問(wèn)題Widget 沒(méi)有正確使用context.updateStatus顯示不同指示符渲染出來(lái)總是同一個(gè)樣子。發(fā)現(xiàn)問(wèn)題就回到 writing-plans subagent-driven 再走一遍然后重新 verify。第六步歸檔/opsx:archive完整流程結(jié)束變更歸檔到openspec/changes/archive/之后回顧決策有文檔可查。驗(yàn)證成功的標(biāo)志/opsx:verify輸出無(wú)未通過(guò)項(xiàng)openspec/changes/archive/下出現(xiàn)本次變更目錄且 tasks.md 里所有任務(wù)標(biāo)記為完成。5. 本篇常見(jiàn)報(bào)錯(cuò)排查清單工作流跑不通時(shí)按下面順序排查基本能覆蓋九成問(wèn)題。報(bào)錯(cuò)一ANTHROPIC_BASE_URL未生效請(qǐng)求打到默認(rèn)地址。檢查環(huán)境變量是否在啟動(dòng) Claude Code 的同一個(gè) shell 里 export改完.zshrc要source或重開(kāi)終端。用echo $ANTHROPIC_BASE_URL確認(rèn)輸出是https://taotoken.net/api。報(bào)錯(cuò)二401 鑒權(quán)失敗。多半是 Key 沒(méi)讀到或?qū)戝e(cuò)。確認(rèn)TAOTOKEN_API_KEY有值settings.json 里的${TAOTOKEN_API_KEY}引用格式正確。如果 Key 泄露過(guò)去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成一個(gè)。報(bào)錯(cuò)三/opsx:propose無(wú)響應(yīng)或提示命令不存在。插件沒(méi)注冊(cè)成功。重跑npx openspec init確認(rèn).claude/settings.json里plugins.openspec.enabled為 true命令前綴是opsx。重啟 Claude Code。報(bào)錯(cuò)四Superpowers 沒(méi)有讀取 tasks.md。檢查openspec/changes/下當(dāng)前變更目錄里 tasks.md 是否存在且非空。writing-plans 默認(rèn)讀最近一次 propose 的產(chǎn)出如果中間切過(guò)變更重新 propose 一次。報(bào)錯(cuò)五apply 命令還在實(shí)現(xiàn)被 Openspec 搶走?；氐絚onfig.toml確認(rèn)apply_tasks false或重跑openspec config profile取消勾選 Apply tasks。報(bào)錯(cuò)六subagent 執(zhí)行時(shí)權(quán)限被拒。settings.json 的permissions.allow里補(bǔ)上對(duì)應(yīng) Bash 命令前綴別用通配符放開(kāi)全部。報(bào)錯(cuò)七verify 報(bào) Spec 不合規(guī)。這是正常攔截說(shuō)明實(shí)現(xiàn)和規(guī)范對(duì)不上?？?verify 輸出的具體條目回到 writing-plans 重新拆任務(wù)別手動(dòng)改代碼繞過(guò)驗(yàn)證。提示排查時(shí)優(yōu)先看 Claude Code 的日志輸出環(huán)境變量和插件注冊(cè)問(wèn)題都會(huì)在啟動(dòng)階段打印。6. 把通道和流程固定下來(lái)整套工作流跑順之后日常開(kāi)發(fā)就是 explore → propose → writing-plans → subagent-driven → verify → archive 這個(gè)循環(huán)驗(yàn)證發(fā)現(xiàn)問(wèn)題就再走一遍 plan → execute → verify。模型通道統(tǒng)一走 TaoTokenClaude Code 和 subagent 共用一個(gè) Key換模型或調(diào)額度都在控制臺(tái)一處搞定不用每個(gè)插件單獨(dú)配。如果你主要做長(zhǎng)期編碼和 Agent 任務(wù)建議把 Coding Plan 用起來(lái)額度規(guī)劃更清晰入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。想先驗(yàn)證模型對(duì)話效果可以直接在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 里試。接入細(xì)節(jié)和參數(shù)說(shuō)明看文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Claude Code 的 Anthropic 兼容接入方式在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 有專門說(shuō)明。最后留一個(gè)實(shí)操建議先把a(bǔ)pply_tasks false和ANTHROPIC_BASE_URL這兩處配好再跑一遍完整流程比一上來(lái)就調(diào)任務(wù)粒度省事得多。