最近 AI 編程圈的幾個群里superpowers 這個詞出現(xiàn)的頻率高得嚇人。不是中二病也不是什么漫畫梗它是一套給 AI 編程代理用的技能擴(kuò)展框架主要跑在 Claude Code、Codex 這類命令行工具上。簡單說你可以把它理解成給 AI 裝上的一套標(biāo)準(zhǔn)化作業(yè)手冊——原來你問一句它答一句現(xiàn)在你丟一個任務(wù)它會自己走完先聊清楚需求、再拆計劃、再寫測試、再動手實現(xiàn)、最后重構(gòu)收尾的完整流程。我用它大概有三周了最大的感受是AI 寫出來的東西不再是能跑就行而開始像同事手里交出來的活。如果你最近也在折騰 superpowers 安裝、superpowers 使用教程或者想在 Codex、Java 項目里把它用起來這篇文章應(yīng)該能幫你省不少時間。我會從它到底解決什么問題講起再給到完整的上手路徑和我在實際項目中踩過的坑。1. 項目解讀superpowers 到底在解決什么問題1.1 一句話講清它是什么superpowers 是一個開源項目由 Jesse Vincent網(wǎng)名 obra發(fā)起本質(zhì)上是給 AI 編程代理準(zhǔn)備的一套技能包。它不是 IDE 插件也不是獨立的 AI 模型而是一堆高度結(jié)構(gòu)化的 Markdown 技能文件外加一個把它們加載進(jìn) AI 工作流的框架。每個技能文件都定義了一個完整的工作流程AI 在對話中調(diào)用它就相當(dāng)于進(jìn)入了按套路干活的模式。比如你想讓 AI 實現(xiàn)一個新功能它不會直接甩出一大段代碼而是先跟你確認(rèn)驗收標(biāo)準(zhǔn)然后寫計劃再按測試驅(qū)動開發(fā)的節(jié)奏把功能做出來。打個比方你讓實習(xí)生寫個登錄功能他大概率能寫出來但可能漏掉參數(shù)校驗、密碼加密、錯誤提示?？赡阋墙o他一本帶檢查清單的《登錄功能作業(yè)規(guī)范》他至少不會漏掉該有的步驟交上來的東西也有章法。superpowers 就是那本規(guī)范。1.2 為什么叫 superpowers從回答者到執(zhí)行者用過 Claude Code 或 Codex 的人應(yīng)該都有類似的體驗AI 很聰明但沒耐心。你讓它寫一個函數(shù)它五分鐘就寫完了你讓它重構(gòu)一個模塊它改了三分之一就停下來等你確認(rèn)下一步。這不是能力問題是工作方法問題——模型本身缺乏一套穩(wěn)定的做事的節(jié)奏。superpowers 解決的就是這個問題。它把領(lǐng)域里被驗證過的好方法比如測試驅(qū)動開發(fā)、小步重構(gòu)、計劃先行、規(guī)范的提交信息固化成 AI 的默認(rèn)行為。讓 AI 從你問什么我答什么的回答者變成拿到任務(wù)自己規(guī)劃、自己執(zhí)行、自己檢查的執(zhí)行者。我用一個真實場景對比一下。沒有 superpowers 時我讓 AI 給 UserService 加一個 findByEmail 方法它可能直接給你一個能編譯通過的實現(xiàn)然后問你還需要什么嗎。有 superpowers 時它會先問email 不存在時應(yīng)該拋異常還是返回空然后寫一個失敗的測試再寫實現(xiàn)最后跑一遍測試確認(rèn)全綠。同樣是完成一個需求后者交付的東西明顯更可維護(hù)。1.3 哪些人最該用哪些人可以先不用先說適合用的天天泡在終端里用 Claude Code 或 Codex 寫代碼的人。想讓 AI 輸出的代碼有測試、有文檔、可維護(hù)的人。帶團(tuán)隊、想統(tǒng)一大家 AI 使用姿勢的人——技能包可以放進(jìn) Git 倉庫全組共用一套標(biāo)準(zhǔn)。再說暫時不用的偶爾用 AI 寫個腳本、處理一次臨時需求的人技能包會顯得重。完全沒有版本控制概念的新手。因為 superpowers 里的很多技能高度依賴 Git比如它會頻繁查看 diff、創(chuàng)建分支、用提交信息模板如果對 Git 不熟容易不知道自己正在被 AI 引導(dǎo)著干什么。2. 核心設(shè)計技能Skills機制拆解2.1 技能 可復(fù)用的標(biāo)準(zhǔn)作業(yè)程序superpowers 里最核心的概念就是 Skill。一個技能文件通常由兩部分組成開頭是一段 YAML 格式的 frontmatter寫著技能名稱、描述、適用場景正文是完整的操作指引告訴 AI 遇到這類任務(wù)應(yīng)該按什么順序執(zhí)行、每一步要產(chǎn)出什么、有哪些要點。這種設(shè)計本質(zhì)上就是把一個資深工程師腦子里那套遇到問題怎么做的流程變成一份機器能讀取、模型能執(zhí)行的文檔。它和普通提示詞最大的區(qū)別是提示詞是臨時的用完就忘技能文件是持久的可以反復(fù)調(diào)用可以被其他技能引用可以放進(jìn) Git 里做版本管理。我剛開始以為這就是換了個方式寫 prompt用了一段時間才發(fā)現(xiàn)區(qū)別很大。普通 prompt 是請按測試驅(qū)動開發(fā)來寫模型大概率會回答好的我按 TDD 來然后依然是先寫實現(xiàn)再補測試。技能文件不一樣它把先寫失敗測試拆成了一個不可跳過的步驟模型在每一步都會讀到現(xiàn)在你在這個 Skill 的第 2 步請先完成這一步的產(chǎn)出這樣就不會蒙混過去。2.2 內(nèi)置技能盤點superpowers 倉庫里預(yù)置了不少技能我用得比較多的是下面這幾個技能名稱觸發(fā)場景主要產(chǎn)出物brainstorming需求模糊需要先討論方案明確的功能描述、驗收標(biāo)準(zhǔn)、邊界情況清單writing-plans任務(wù)較大需要拆解步驟帶依賴關(guān)系的執(zhí)行計劃test-driven-development實現(xiàn)新功能或修復(fù) Bug先失敗的測試、最小實現(xiàn)、重構(gòu)后的最終代碼refactoring既有代碼需要調(diào)整結(jié)構(gòu)分步完成的多次小提交而不是一次大改commit-message提交代碼前規(guī)范化的 Git 提交信息using-git需要安全地操作版本庫對 git 操作安全性的檢查結(jié)論debugging遇到難以定位的問題基于假設(shè)驗證的調(diào)試過程和根因結(jié)論這些技能不是孤立的它們可以互相調(diào)用。比如 test-driven-development 在執(zhí)行中途發(fā)現(xiàn)實現(xiàn)很糟糕可能自動調(diào)用 refactoring 來整理結(jié)構(gòu)在所有代碼改完后又會調(diào)用 commit-message 來生成提交信息。組合起來AI 的工作流就變成了流水線而不是一個孤零零的問答。2.3 為什么技能優(yōu)于普通提示詞這個問題我問過自己很多遍最終總結(jié)出三個關(guān)鍵點。第一穩(wěn)定復(fù)現(xiàn)。模型嘴上說我按 TDD 來和真的按 TDD 做是兩回事。技能文件用步驟清單和檢查點約束模型的行為讓它每次都能做出差不多質(zhì)量的事而不是看心情發(fā)揮。第二可組合嵌套。普通提示詞寫完之后你很難讓另一個提示詞去調(diào)用它。技能文件可以把任務(wù)拆成多個技能的串聯(lián)比如先 brainstorming 澄清需求再 writing-plans 制定計劃然后用 TDD 分步實現(xiàn)。這種組合能力讓 AI 面對復(fù)雜任務(wù)時不至于亂套。第三集體進(jìn)化。技能文件是純文本放在 Git 里就能做版本管理和多人維護(hù)。我自己就 fork 了一個技能把團(tuán)隊內(nèi)部的一些規(guī)范加了進(jìn)去比如提交信息里必須帶任務(wù)單號。這樣 AI 在開發(fā)時使用的就不再是互聯(lián)網(wǎng)通用的最佳實踐而是你們團(tuán)隊自己的最佳實踐。2.4 技能文件長什么樣很多人對 superpowers 的印象是一堆神秘腳本我拆開看之后發(fā)現(xiàn)其實特別樸素。一個技能文件大概長這樣--- name: test-driven-development description: 使用測試驅(qū)動開發(fā)流程實現(xiàn)新功能先寫測試再寫實現(xiàn)最后重構(gòu)。 --- 執(zhí)行本技能時 1. 和用戶確認(rèn)功能的驗收標(biāo)準(zhǔn)包括正常情況和異常情況。 2. 先編寫一個會失敗的測試覆蓋驗收標(biāo)準(zhǔn)中的關(guān)鍵場景。 3. 運行測試確認(rèn)它確實失敗。 4. 用最小實現(xiàn)讓測試通過。 5. 檢查實現(xiàn)是否有重復(fù)或壞味道有小步重構(gòu)的空間就重構(gòu)。 6. 重新運行全部測試確認(rèn)沒有回歸。結(jié)構(gòu)清楚、意圖明確、沒有玄學(xué)。它之所以有效就是因為它把寫代碼這事應(yīng)該有什么節(jié)奏講得非常具體。模型讀到的不只是一句你要遵守 TDD而是一套可以用代碼逐行解釋的操作序列。這也是我建議所有想深入了解 superpowers 的人都去通讀一遍技能文件的原因——你會發(fā)現(xiàn)原來 AI 的超能力不是什么魔法而是把好習(xí)慣寫成了文檔。3. 實操從安裝到在項目里真正用起來3.1 安裝前的基礎(chǔ)環(huán)境先把前提條件說清楚免得你裝到一半發(fā)現(xiàn)缺東西。你需要準(zhǔn)備一個能跑 AI 編程代理的終端環(huán)境。目前主流的宿主就是 Claude Code 和 Codex CLI至少裝其中一個。Node.js 18 及以上版本。雖然 superpowers 本身很大程度上是 Markdown 文件但它的加載腳本和命令工具是用 JavaScript 生態(tài)跑的所以 Node 環(huán)境繞不開。Git 環(huán)境。技能文件本身要 clone 下來而且很多技能在運行時會調(diào)用 git 來查看差異、創(chuàng)建提交所以 Git 必須可用。安裝前我習(xí)慣先跑一遍版本檢查比如node --version、git --version確認(rèn)沒有奇怪的報錯再去裝技能。一個小坑如果你用的是公司內(nèi)網(wǎng)環(huán)境clone GitHub 倉庫前記得先把代理配好不然極容易卡在下載那一步。注意不同宿主的技能加載機制差異很大版本更新也快下面的步驟我以最常見的做法為準(zhǔn)具體細(xì)節(jié)請以項目 README 的最新說明為準(zhǔn)。不要把這篇博文當(dāng)成永遠(yuǎn)不變的官方文檔。3.2 兩種常見安裝方式方式一宿主支持插件機制以 Claude Code 為例。新版 Claude Code 有插件系統(tǒng)直接用命令行安裝claude plugin install superpowers裝完之后在對話界面里輸入/應(yīng)該就能看到 superpowers 相關(guān)的斜杠命令比如/superpowers、/thinking之類。這種方式最省事升級也方便適合絕大多數(shù)人。方式二手動把技能目錄掛到宿主能讀到的位置。如果你用的宿主暫時沒有插件市場或者你想自己 fork 一份技能文件來改可以用手動安裝。先把倉庫 clone 下來git clone https://github.com/obra/superpowers.git然后把 skills 目錄鏈接到宿主的技能加載位置。Claude Code 默認(rèn)會讀~/.claude/skills所以可以這樣ln -s $(pwd)/superpowers/skills ~/.claude/skills如果你希望只在某個項目里啟用就把技能目錄放進(jìn)項目的.claude/skills目錄這樣不同項目可以用不同版本的技能。手動安裝的核心邏輯是搞清楚你的宿主從哪個目錄讀取技能文件然后讓 superpowers 的 skills 目錄出現(xiàn)在那里。理解了這一點你就不會因為換了個宿主就手足無措。3.3 驗證安裝是否成功裝完之后別急著開干先花兩分鐘驗證。在對話里直接輸入/superpowers正常會列出可用的技能列表。如果宿主沒有斜杠命令機制你直接問一句你現(xiàn)在能使用哪些技能請列出文件名和適用場景模型應(yīng)該能報出一串名字。我更推薦用一個真實的小任務(wù)來驗證。比如丟給它一個空模塊說幫這個模塊補一個測試然后觀察它的行為。如果它會先跟你確認(rèn)測試目標(biāo)、再寫失敗用例、再跑測試那基本可以確定技能已經(jīng)被加載并生效了。如果它直接開始噼里啪啦寫實現(xiàn)說明技能文件沒被正確加載回到 3.2 檢查目錄路徑。3.4 Codex 里怎么用 superpowers熱詞里 codex superpowers 被問得很多因為 Codex CLI 沒有 Claude Code 那樣完整的插件市場很多人在這一步卡住。Codex 的約定是讀項目里的 AGENTS.md 文件這個文件相當(dāng)于給 AI 的項目工作手冊。你可以這樣操作第一步把 superpowers/skills 目錄放進(jìn)項目的某個路徑比如.claude/skills或docs/skills路徑本身不重要重要的是在 AGENTS.md 里寫清楚位置。第二步在 AGENTS.md 里加上一段本項目啟用 superpowers 技能框架。技能文件位于 .claude/skills 目錄。 所有開發(fā)和修改任務(wù)先閱讀技能列表然后按對應(yīng)技能的步驟執(zhí)行。第三步重啟 Codex 會話讓它重新讀取 AGENTS.md。然后隨便丟一個任務(wù)測試看它是否會先去翻技能文件。Codex 的加載方式不像插件那么自動化但反而更透明——你能清楚地看到 AI 是怎么理解你給它的規(guī)則手冊的。如果你發(fā)現(xiàn)它不遵守多半是 AGENTS.md 里的描述不夠強硬可以改成你必須先讀取 xxx skill不得跳過其中任何步驟。3.5 Java 項目實戰(zhàn)給 Spring Boot 服務(wù)加一個查詢接口熱搜詞里有 superpowers java我特意用 Java 場景演示一遍因為 Java 項目往往對工程規(guī)范要求更高也更適合體現(xiàn)技能框架的價值。我本地有一個 Spring Boot 項目核心服務(wù)類長這樣Service public class UserService { private final UserRepository userRepository; public UserService(UserRepository userRepository) { this.userRepository userRepository; } // 需要一個按郵箱精確查找用戶的方法 }我直接在對話里說用 superpowers 的 TDD 技能給 UserService 加一個 findByEmail 方法郵箱不存在時拋 UserNotFoundException。隨后 AI 開始按技能流程走。它先是跟我確認(rèn)驗收標(biāo)準(zhǔn)郵箱存在時返回用戶對象郵箱不存在時拋 UserNotFoundException參數(shù)為空時拋 IllegalArgumentException。 確認(rèn)完它先寫了測試Test void findByEmail_shouldReturnUser_whenUserExists() { User user new User(aliceexample.com, Alice); userRepository.save(user); User found userService.findByEmail(aliceexample.com); assertThat(found.getEmail()).isEqualTo(aliceexample.com); } Test void findByEmail_shouldThrowException_whenUserNotExists() { assertThatThrownBy(() - userService.findByEmail(nobodyexample.com)) .isInstanceOf(UserNotFoundException.class); }然后跑測試確認(rèn)它失敗再寫最小實現(xiàn)public User findByEmail(String email) { if (email null || email.isBlank()) { throw new IllegalArgumentException(email must not be blank); } return userRepository.findByEmail(email) .orElseThrow(() - new UserNotFoundException(email)); }最后再跑一遍測試全部通過。整個過程和沒有技能時的差別很明顯AI 不會跳步驟它從頭到尾都知道自己要干什么也沒出現(xiàn)那種寫到一半開始自由發(fā)揮的毛病。Java 項目尤其適合這套玩法因為測試文化本來就是 Java 工程里繞不開的一環(huán)AI 主動幫你把測試補上后續(xù)合并代碼時省很多溝通成本。3.6 如果宿主是 WordBuddy 這類集成工具也有朋友問worbuddy 怎么用 superpowers或者 WordBuddy 這類集成工具能不能用。這類工具本質(zhì)上是把多個 AI 能力包了一層入口superpowers 對它們來說就是一套可掛載的技能集合。我的建議是先去工具設(shè)置里找技能目錄或外部 Skills之類的配置入口然后把 superpowers/skills 的路徑指過去。如果沒有這個入口再看它支持不支持自定義指令通常在設(shè)置里叫 Custom Instructions 或 System Prompt把技能文件的加載規(guī)則寫進(jìn)去讓模型每次啟動時先讀取技能列表。不過說實話如果你用的是這類工具說明你更看重開箱即用那 superpowers 的收益會被打一些折扣。它的優(yōu)勢是裸奔在終端里時帶來的完全控制感集成工具層層封裝反而會讓技能的加載過程變得不可見出問題時不好排查。4. 常見問題與排查技巧實錄4.1 裝了技能但 AI 完全不按流程走這是最常見的坑。現(xiàn)象是技能明明裝了但讓它做任務(wù)時它還是老一套——直接給實現(xiàn)、跳過測試、也不問驗收標(biāo)準(zhǔn)。優(yōu)先檢查這三件事看宿主工具版本。Claude Code 的技能機制是后面才加的如果你的版本太老斜杠命令可能根本不存在?？醇寄苁欠癖患虞d。在對話里輸入命令列出技能如果列表是空的說明目錄沒接上?？茨Ｐ桶姹尽Ｌ醯哪Ｐ图词棺x到了技能文件也可能執(zhí)行不好建議使用 Claude 3.5 Sonnet 以上的模型或同等能力的模型。還有一個土辦法直接把技能文件全文貼給 AI告訴它現(xiàn)在按這個技能的步驟執(zhí)行我這個任務(wù)。如果這樣它還不遵守那就是模型能力或版本問題如果這樣能遵守說明是加載環(huán)節(jié)出了問題回 3.2 檢查目錄路徑。4.2 技能目錄加載失敗手動安裝最常見的問題是符號鏈接壞了或者路徑寫不對。clone 完之后先自己看一眼目錄結(jié)構(gòu)ls -la ~/.claude/skills如果發(fā)現(xiàn)是空的多半是軟鏈沒建成功。還有朋友 clone 到一半網(wǎng)絡(luò)斷了導(dǎo)致 skills 目錄里缺文件也會表現(xiàn)為加載失敗。這種情況重跑一次git clone或者git pull就好。Windows 下還要注意ln -s可能需要管理員權(quán)限或者改用 mklink。如果是在 Git Bash 里操作直接用ln -s通常沒有大問題但在 CMD 或 PowerShell 里就得用不同的命令。4.3 多個項目之間技能版本打架如果你同時維護(hù)多個項目全局只放一份技能文件可能會出問題。比如 A 項目用 v1.0 的技能B 項目需要 v1.2 的新規(guī)則全局目錄一更新所有項目跟著變。我的做法是全局目錄只放最通用的技能項目目錄放和當(dāng)前項目強相關(guān)的技能然后在項目里鎖版本。具體可以用 Git submodule 或者直接在項目里用單獨的目錄放一份 fork 出來的技能文件。這樣做的成本是多一份文件收益是可控性。尤其團(tuán)隊協(xié)作時大家統(tǒng)一用項目里的技能版本才不會出現(xiàn)我的機器上 AI 會寫測試你的機器上 AI 不寫測試這種事。4.4 AI 生成的測試質(zhì)量太差技能框架能保證流程但保證不了質(zhì)量。如果 AI 寫的測試都是為了通過而通過的寫法比如斷言一個函數(shù)返回了某個固定值但沒有真正覆蓋行為問題往往出在兩處一是模型對業(yè)務(wù)理解不夠二是技能里的驗收標(biāo)準(zhǔn)不夠具體。我的經(jīng)驗是在任務(wù)描述里把邊界情況寫清楚比如郵箱為空時是什么行為不存在時是什么行為“大小寫敏感不敏感”。驗收標(biāo)準(zhǔn)越明確AI 寫的測試就越有針對性。別指望技能文件替你理解業(yè)務(wù)它是流程外套不是領(lǐng)域?qū)＜摇?.5 常見問題速查表癥狀可能原因解決動作斜杠命令不存在宿主版本過舊或插件未啟用升級宿主重裝插件技能列表為空技能目錄路徑不對檢查軟鏈和目錄結(jié)構(gòu)AI 不遵守技能加載失敗或模型太弱直接貼技能文本測試技能版本混亂全局和項目技能混用項目內(nèi)單獨鎖版本測試質(zhì)量差驗收標(biāo)準(zhǔn)不明確在任務(wù)描述中補充邊界情況Clone 到一半失敗網(wǎng)絡(luò)不穩(wěn)定重跑 git clone 或 git pull我的建議是每次升級 superpowers 之前先把你 fork 出來的技能文件 diff 一下看看官方改了什么。不要盲目合并因為新規(guī)則很可能和你團(tuán)隊的現(xiàn)有流程沖突看清楚再動。我在自己項目里用得最多的其實是 brainstorming 和 TDD 兩個技能。剛開始也會懷疑無非是一堆 Markdown憑什么讓 AI 變強直到有一天我讓 AI 為一個前端組件補測試它老老實實先寫了一個渲染后出現(xiàn)錯誤提示的失敗用例然后才寫實現(xiàn)——那一刻我意識到模型缺的從來不是知識而是一套工作方法。superpowers 就是把老工程師腦子里的那套標(biāo)準(zhǔn)流程固化給 AI 的黏合劑。工具迭代很快功能邊界一直在變但思路是通的。建議你裝好之后別急著投入生產(chǎn)先把兩三個技能文件從頭到尾讀一遍你會比 AI 更了解它自己。