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