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