1. 先搞清楚 Superpowers 到底在解決什么問(wèn)題如果你用過(guò) Claude Code 做稍微復(fù)雜一點(diǎn)的需求大概率遇到過(guò)這種場(chǎng)面你描述完需求它二話不說(shuō)開(kāi)始寫(xiě)代碼寫(xiě)完告訴你已完成。你打開(kāi)文件一看邏輯能跑但邊界條件沒(méi)處理、沒(méi)有測(cè)試、命名風(fēng)格和你項(xiàng)目里其它模塊完全兩套。你回頭補(bǔ)一句下次先寫(xiě)測(cè)試它答應(yīng)得很好換個(gè)新會(huì)話又忘得一干二凈。這不是模型能力問(wèn)題而是什么時(shí)候該做什么這件事默認(rèn)不在它的執(zhí)行路徑里。Agent 每次任務(wù)都是全新上下文沒(méi)有跨會(huì)話的肌肉記憶。你靠提示詞反復(fù)叮囑本質(zhì)是在用自然語(yǔ)言做流程編排穩(wěn)定性完全取決于模型當(dāng)次的理解和上下文有沒(méi)有被擠掉。Superpowers 這個(gè)技能框架Agentic Skills換了個(gè)思路把先規(guī)劃、再寫(xiě)測(cè)試、再評(píng)審這些工程動(dòng)作拆成一個(gè)個(gè)結(jié)構(gòu)化的 SKILL 文件再通過(guò)一條常駐的引導(dǎo)指令要求 Agent 在動(dòng)手前先檢查有沒(méi)有相關(guān)技能該觸發(fā)。于是 TDD、寫(xiě)計(jì)劃、代碼評(píng)審從你求它做變成開(kāi)工前的默認(rèn)檢查項(xiàng)。它適配 Claude Code、Codex、Cursor、Gemini CLI 等十多個(gè)智能體MIT 協(xié)議開(kāi)源是目前 Agentic Skills 方向最主流的參考實(shí)現(xiàn)之一。這篇文章聚焦落地怎么在 Claude Code 里把 Superpowers 裝好、配置好怎么驗(yàn)證它真的會(huì)觸發(fā) TDD 流程以及踩過(guò)的坑怎么排。適合已經(jīng)用 Claude Code 寫(xiě)業(yè)務(wù)代碼、想讓 AI 按固定工程流程推進(jìn)的開(kāi)發(fā)者。如果你只是偶爾讓它改個(gè)變量名這套東西的流程開(kāi)銷(xiāo)反而礙事可以先跳過(guò)。需要說(shuō)明的是Superpowers 負(fù)責(zé)流程編排模型調(diào)用本身仍然走你自己的 API 通道。下面配置里我會(huì)用 TaoToken 的 API 地址作為示例 Base URL你可以替換成自己實(shí)際使用的端點(diǎn)重點(diǎn)是配置結(jié)構(gòu)和驗(yàn)證方法。2. 前置準(zhǔn)備Claude Code 環(huán)境與 TaoToken 接入配置在裝技能框架之前先把底層通道理順。Claude Code 需要三樣?xùn)|西可用的 API Base URL、API Key、以及明確的 Model ID。這三件套缺一個(gè)都會(huì)在啟動(dòng)時(shí)報(bào)錯(cuò)而且報(bào)錯(cuò)信息往往不直觀所以先配好再談技能。TaoToken 的控制臺(tái)入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 登錄后進(jìn) API Keys 頁(yè)面創(chuàng)建密鑰。創(chuàng)建時(shí)建議按項(xiàng)目命名比如claude-code-dev方便后續(xù)輪換時(shí)定位。密鑰只在創(chuàng)建時(shí)完整顯示一次復(fù)制后立刻存進(jìn)本地環(huán)境變量不要寫(xiě)進(jìn)會(huì)提交到 Git 的文件。Claude Code 讀取配置的方式有兩種環(huán)境變量或者項(xiàng)目級(jí)/用戶(hù)級(jí)的 settings 文件。我建議用 settings 文件因?yàn)榭蓮?fù)制、可版本化管理團(tuán)隊(duì)里其他人拉下來(lái)改個(gè) Key 就能用。用戶(hù)級(jí)配置放在~/.claude/settings.json項(xiàng)目級(jí)放在項(xiàng)目根目錄的.claude/settings.json。項(xiàng)目級(jí)優(yōu)先級(jí)更高適合給不同倉(cāng)庫(kù)配不同模型。一個(gè)可復(fù)制的最小配置片段如下注意 JSON 里不能有注釋路徑按你實(shí)際環(huán)境調(diào)整{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的密鑰粘貼在這里, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-5-20251001 } }這里幾個(gè)字段的作用要分清ANTHROPIC_BASE_URL指向 API 網(wǎng)關(guān)地址注意不要帶末尾斜杠也不要拼上/v1Claude Code 會(huì)自己補(bǔ)路徑ANTHROPIC_AUTH_TOKEN放你的密鑰ANTHROPIC_MODEL是主模型負(fù)責(zé)規(guī)劃和寫(xiě)代碼ANTHROPIC_SMALL_FAST_MODEL用于標(biāo)題生成、文件摘要這類(lèi)輕量調(diào)用配個(gè)小模型能明顯省錢(qián)。如果你更習(xí)慣環(huán)境變量等價(jià)寫(xiě)法是在 shell 配置文件里導(dǎo)出export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的密鑰 export ANTHROPIC_MODELclaude-sonnet-4-5-20250929配完先別急著裝 Superpowers用一條最樸素的命令驗(yàn)證通道是否通claude -p 回復(fù)兩個(gè)字通了如果返回通了說(shuō)明 Base URL、Key、Model ID 三件套都對(duì)。如果報(bào) 401說(shuō)明 Key 無(wú)效或沒(méi)被讀到如果報(bào)連接失敗先檢查 Base URL 有沒(méi)有多寫(xiě)路徑。這一步過(guò)了再進(jìn)入技能安裝否則后面出問(wèn)題你分不清是通道問(wèn)題還是技能問(wèn)題。3. 安裝 Superpowers 技能框架與可復(fù)制配置片段Superpowers 在 Claude Code 里有兩條安裝路線我建議優(yōu)先走官方插件市場(chǎng)因?yàn)榧寄芎鸵龑?dǎo)指令一次配齊不用手動(dòng)維護(hù)文件。路線 A在 Claude Code 交互界面里直接敲斜杠命令/plugin install superpowersclaude-plugins-official這條命令從 Anthropic 官方插件市場(chǎng)拉取裝完技能目錄和 bootstrap 引導(dǎo)指令都會(huì)就位。路線 B 是走 Superpowers 自己的市場(chǎng)適合你還想裝它家其它關(guān)聯(lián)插件的情況/plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers-marketplace裝完之后技能文件會(huì)落在 Claude Code 的插件目錄下通常是~/.claude/plugins/下面按插件名分的子目錄。你可以用ls確認(rèn)一下有沒(méi)有superpowers相關(guān)目錄里面應(yīng)該能看到一堆.md結(jié)尾的 SKILL 文件比如brainstorming、writing-plans、test-driven-development、requesting-code-review這些。如果你所在的環(huán)境不方便用插件市場(chǎng)也可以手動(dòng)克隆倉(cāng)庫(kù)再軟鏈到插件目錄但這種方式升級(jí)要自己拉代碼不如插件市場(chǎng)省心。手動(dòng)方式大致是git clone https://github.com/obra/superpowers.git ~/.claude/plugins/superpowers然后在~/.claude/settings.json里確認(rèn)插件目錄被掃描到。不同 Claude Code 版本對(duì)插件目錄的約定略有差異裝完用/plugin list看一眼有沒(méi)有列出來(lái)最穩(wěn)妥。關(guān)于遙測(cè)Superpowers 默認(rèn)會(huì)從服務(wù)端加載一個(gè)視覺(jué)組件用于統(tǒng)計(jì)使用情況不含項(xiàng)目?jī)?nèi)容和提示詞。介意的話在 settings 的 env 里加一條{ env: { SUPERPOWERS_DISABLE_TELEMETRY: 1 } }這個(gè)字段和前面的 API 配置放在同一個(gè)env對(duì)象里即可不要重復(fù)寫(xiě)兩個(gè)env鍵JSON 重復(fù)鍵會(huì)導(dǎo)致后者覆蓋前者這是很常見(jiàn)的配置事故。裝完技能后還有一個(gè)容易被忽略的點(diǎn)引導(dǎo)指令bootstrap是否真的注入了會(huì)話。Superpowers 的核心機(jī)制是每次任務(wù)前檢查相關(guān)技能這條規(guī)則靠常駐指令維持。如果插件裝了但引導(dǎo)沒(méi)生效技能文件躺在磁盤(pán)上也不會(huì)被觸發(fā)。驗(yàn)證方法在下一節(jié)。4. 驗(yàn)證 AI 是否真的觸發(fā) TDD 流程裝完不等于生效。技能框架最怕的就是悄悄失效——你以為它在跑流程其實(shí)模型根本沒(méi)讀技能。所以必須做行為驗(yàn)證而不是看安裝日志。第一個(gè)驗(yàn)證點(diǎn)用一句最樸素的提示測(cè)試 brainstorming 是否自動(dòng)觸發(fā)Lets make a react todo list如果 Superpowers 生效Claude Code 不會(huì)立刻開(kāi)始寫(xiě)代碼而是先反問(wèn)你需求數(shù)據(jù)存哪里、要不要持久化、單用戶(hù)還是多用戶(hù)、UI 風(fēng)格偏好。這就是brainstorming技能被激活的表現(xiàn)。如果它直接甩給你一個(gè)App.jsx說(shuō)明引導(dǎo)指令沒(méi)生效回到上一節(jié)檢查插件是否被/plugin list識(shí)別。第二個(gè)驗(yàn)證點(diǎn)專(zhuān)門(mén)測(cè) TDD。給它一個(gè)帶明確行為的需求比如給 utils/date.ts 加一個(gè) formatRelative 函數(shù)輸入時(shí)間戳返回3分鐘前這種相對(duì)時(shí)間觀察它的動(dòng)作順序。走 TDD 流程時(shí)它應(yīng)該先寫(xiě)一個(gè)會(huì)失敗的測(cè)試文件比如utils/date.test.ts運(yùn)行測(cè)試看到 RED然后寫(xiě)最小實(shí)現(xiàn)讓測(cè)試變 GREEN最后才提交。你可以在它執(zhí)行過(guò)程中看終端輸出測(cè)試命令跑了幾次、第一次是不是失敗這些是硬證據(jù)。第三個(gè)驗(yàn)證點(diǎn)測(cè)代碼評(píng)審。在一個(gè)任務(wù)完成后看它有沒(méi)有主動(dòng)調(diào)用requesting-code-review技能對(duì)照計(jì)劃?rùn)z查改動(dòng)、按嚴(yán)重級(jí)別列問(wèn)題。如果它寫(xiě)完就說(shuō)完成沒(méi)有任何評(píng)審動(dòng)作說(shuō)明技能觸發(fā)鏈路在某處斷了。我實(shí)測(cè)下來(lái)最可靠的判斷方式是看它有沒(méi)有先問(wèn)再做。Superpowers 的設(shè)計(jì)哲學(xué)是開(kāi)工前先澄清所以任何直接動(dòng)手寫(xiě)代碼的行為都是反例。你可以故意給一個(gè)模糊需求比如優(yōu)化一下這個(gè)接口看它是直接改還是先問(wèn)清楚優(yōu)化目標(biāo)性能、可讀性、還是錯(cuò)誤處理。先問(wèn)說(shuō)明流程在跑。還有一個(gè)細(xì)節(jié)技能觸發(fā)是有 token 開(kāi)銷(xiāo)的每輪都要做一次有沒(méi)有相關(guān)技能的檢查。所以小改動(dòng)時(shí)你會(huì)感覺(jué)它話變多了這是正常現(xiàn)象不是配置錯(cuò)誤。5. 常見(jiàn)報(bào)錯(cuò)排查401、local proxy failed 與技能不觸發(fā)配置和驗(yàn)證過(guò)程中幾類(lèi)報(bào)錯(cuò)出現(xiàn)頻率最高逐個(gè)說(shuō)清楚。401 未授權(quán)。典型輸出是API Error: 401 {error:{message:invalid api key}}。原因通常是三個(gè)Key 復(fù)制時(shí)帶了空格或換行settings 文件里ANTHROPIC_AUTH_TOKEN拼寫(xiě)錯(cuò)了注意是 AUTH_TOKEN 不是 API_KEY或者環(huán)境變量和 settings 同時(shí)存在且值不一致后者覆蓋了前者。排查順序是先echo $ANTHROPIC_AUTH_TOKEN看環(huán)境變量再檢查 settings 文件確保只有一處生效。另外確認(rèn) Base URL 是https://taotoken.net/api不要寫(xiě)成帶/v1/messages的完整路徑。local proxy failed / connection refused。這類(lèi)報(bào)錯(cuò)說(shuō)明 Claude Code 嘗試連的地址根本不通。常見(jiàn)原因是 Base URL 末尾多了斜杠或者寫(xiě)成了https://taotoken.net/api/拼接后變成雙斜杠路徑。也可能是本地網(wǎng)絡(luò)策略攔截了出站請(qǐng)求。先用curl -I https://taotoken.net/api看能不能拿到響應(yīng)頭能通再回來(lái)看配置。如果 curl 通但 Claude Code 不通檢查是不是有全局代理環(huán)境變量HTTP_PROXY在干擾臨時(shí)unset掉再試。reading choices / 響應(yīng)解析失敗。報(bào)錯(cuò)里出現(xiàn)reading choices或類(lèi)似字段通常意味著返回體不是預(yù)期的對(duì)話格式可能是網(wǎng)關(guān)返回了錯(cuò)誤頁(yè) HTML或者模型 ID 寫(xiě)錯(cuò)導(dǎo)致路由到了不支持的端點(diǎn)。核對(duì)ANTHROPIC_MODEL的值是否拼寫(xiě)正確以及該模型是否在你的賬戶(hù)權(quán)限內(nèi)。換一個(gè)確定可用的模型 ID 做對(duì)照測(cè)試能快速定位是模型問(wèn)題還是通道問(wèn)題。OAuth 相關(guān)報(bào)錯(cuò)。如果你之前用官方賬號(hào)登錄過(guò) Claude Code本地可能殘留 OAuth 憑據(jù)和 API Key 模式?jīng)_突。表現(xiàn)是啟動(dòng)時(shí)提示認(rèn)證失敗或反復(fù)跳轉(zhuǎn)。處理方式是清理~/.claude/下的憑據(jù)緩存文件或者在啟動(dòng)時(shí)明確使用 API Key 模式。具體文件名隨版本變化進(jìn)目錄看一眼帶auth或credential字樣的文件即可。技能裝了但不觸發(fā)。這個(gè)最隱蔽。先確認(rèn)/plugin list里有 superpowers再確認(rèn)當(dāng)前會(huì)話是新開(kāi)的舊會(huì)話不會(huì)熱加載新插件然后檢查引導(dǎo)指令有沒(méi)有被系統(tǒng)提示擠掉——超長(zhǎng)會(huì)話在壓縮上下文后bootstrap 可能失效這時(shí)新開(kāi)一個(gè)會(huì)話通常就恢復(fù)了。Superpowers 自帶一個(gè)診斷技能直接對(duì)它說(shuō)figure out what went wrong with superpowers in this session它會(huì)讀會(huì)話記錄用行級(jí)證據(jù)告訴你哪一步該觸發(fā)但沒(méi)觸發(fā)。這個(gè)自查能力是它區(qū)別于普通提示詞合集的關(guān)鍵設(shè)計(jì)排障時(shí)優(yōu)先用。6. 把工程規(guī)范固化為可復(fù)用技能下一步怎么走裝好、驗(yàn)證通、排障有手段之后真正的價(jià)值在于把這套機(jī)制用起來(lái)而不是裝完就放著。第一件事把團(tuán)隊(duì)約定寫(xiě)進(jìn)項(xiàng)目級(jí)配置。比如你們要求所有新功能必須有測(cè)試、PR 前必須過(guò) lint這些可以在項(xiàng)目根目錄的.claude/settings.json里配合技能觸發(fā)點(diǎn)固化下來(lái)。項(xiàng)目級(jí)配置優(yōu)先級(jí)高于用戶(hù)級(jí)團(tuán)隊(duì)成員拉下代碼就繼承同一套流程不用每個(gè)人口頭叮囑。第二件事學(xué)會(huì)寫(xiě)自己的技能。Superpowers 自帶writing-skills技能教你怎么把一條團(tuán)隊(duì)規(guī)范寫(xiě)成結(jié)構(gòu)化的 SKILL 文件。比如你們有一套特定的錯(cuò)誤碼規(guī)范、日志格式、或者數(shù)據(jù)庫(kù)遷移流程都可以寫(xiě)成技能讓 Agent 在對(duì)應(yīng)場(chǎng)景自動(dòng)觸發(fā)。這才是工程肌肉記憶的真正含義——不是記住某一次對(duì)話而是把規(guī)范變成可復(fù)用的資產(chǎn)。第三件事控制流程開(kāi)銷(xiāo)。強(qiáng)制流程在復(fù)雜任務(wù)上收益最大在小修小補(bǔ)上是純摩擦。我的做法是按任務(wù)規(guī)模切換跨多文件、涉及新邏輯的需求走完整流程改個(gè)文案、調(diào)個(gè)樣式就直接說(shuō)跳過(guò)流程只改這一處。技能是默認(rèn)行為不是不可關(guān)閉的枷鎖明確告訴它跳過(guò)是允許的。如果你還沒(méi)配好底層通道先去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 創(chuàng)建密鑰再按第 2 節(jié)的 JSON 片段填進(jìn) settings。想先確認(rèn)模型對(duì)話是否正?？梢杂媚Ｐ蛯?duì)話頁(yè)面發(fā)一條測(cè)試消息長(zhǎng)期跑編碼任務(wù)、需要穩(wěn)定額度的話Coding Plan 更適合持續(xù)使用。接入細(xì)節(jié)和字段說(shuō)明在接入文檔里有完整對(duì)照遇到本文沒(méi)覆蓋的報(bào)錯(cuò)可以去查。最后給一個(gè)實(shí)用建議裝完 Superpowers 的第一周刻意觀察它每次任務(wù)的第一個(gè)動(dòng)作。如果連續(xù)三次都是先問(wèn)再做說(shuō)明流程真的內(nèi)化了如果又開(kāi)始直接寫(xiě)代碼就新開(kāi)會(huì)話并跑一次診斷技能。這套框架的價(jià)值不在于裝的那一刻而在于你能否通過(guò)驗(yàn)證和排障讓它持續(xù)按預(yù)期運(yùn)轉(zhuǎn)。