最近開發(fā)圈里冒出來的“superpowers”熱度高得有點夸張。很多人以為它是個新的 AI 編碼工具裝上就能讓代碼自動寫起來其實沒那么簡單。我把它完整跑了一遍之后最大的感受是這東西不是“又一個 Copilot”而是一套重新組織 AI 編碼工作方式的“工作流 規(guī)范 CLI 腳手架”。名字叫 superpowers但它真正給的超能力是讓 AI 不再一股腦生成一大坨代碼而是像真正的工程師那樣先理解需求、拆解任務(wù)、寫測試、再實現(xiàn)代碼最后用測試結(jié)果證明自己沒寫錯。這篇文章我打算把這套東西從原理到落地講透。我會先講清楚它解決了什么痛點再帶你把環(huán)境裝起來然后把“規(guī)范驅(qū)動開發(fā) 測試驅(qū)動開發(fā)”的核心理念拆開揉碎最后用 Java 場景完整走一遍流程附上我實操中踩過的坑和排查技巧。適合的人群很明確用過 AI 編程助手但覺得“生成一時爽維護火葬場”的人以及團隊里想給 AI 編碼建立一套標(biāo)準(zhǔn)化流程的工程師。小白可以照著一步一步做有經(jīng)驗的開發(fā)者可以跳過基礎(chǔ)安裝直接看核心機制和避坑部分。1. 先搞清楚 superpowers 到底解決什么問題先說結(jié)論superpowers 不是某個大廠出的官方工具而是一個開源項目最早火起來是因為它能把“AI 寫代碼”這件事從“人給一句需求、AI 吐一堆代碼”這種不可控的模式轉(zhuǎn)變成“人寫規(guī)范文檔、AI 按任務(wù)拆解、逐步實現(xiàn)、測試自證”的可控流程。它的核心關(guān)鍵詞有兩個規(guī)范驅(qū)動開發(fā)Spec-Driven Development和測試驅(qū)動開發(fā)TDD。聽起來像是老生常談的工程方法論但放在 AI 編碼這個場景里效果完全不一樣。我見過太多人用 AI 寫代碼的方式是這樣的把需求往對話框里一貼AI 直接生成幾百行代碼然后人再手動去修編譯錯誤、改邏輯漏洞。遇到簡單的小功能還好一旦項目上了規(guī)模這種方法立刻就崩了。原因在于模型本質(zhì)上是基于概率在預(yù)測下一段 token它沒有能力在心里維護一個完整的項目狀態(tài)圖。你讓它一口氣寫一個模塊它可能寫出一份“看起來對”的代碼但缺了邊界條件、忘了錯誤處理、跟已有代碼風(fēng)格脫節(jié)這些都不是它在生成那一刻能感知到的。superpowers 的思路是既然 AI 容易在長上下文里失控那就把工作切碎讓它一次只面對一個小而明確的任務(wù)并且用測試來給它一個“客觀的驗收標(biāo)準(zhǔn)”。這里要提一個很關(guān)鍵的詞自證。superpowers 的模式里AI 寫完代碼不算完它必須自己把測試跑起來跑通了才算這個任務(wù)結(jié)束。如果測試失敗它要繼續(xù)修修到通過為止。這一下就把“AI 生成代碼”從單向輸出變成了“生成—驗證—修正”的閉環(huán)。實際用下來代碼質(zhì)量的提升非常明顯尤其是那些容易遺漏的異常分支和邊界情況AI 在測試的約束下會老實很多。還有一個容易被忽略的設(shè)計點superpowers 把“需求分析”和“代碼實現(xiàn)”徹底分開了。傳統(tǒng)對話式編程里需求描述和行為實現(xiàn)是混在一起的AI 經(jīng)常做著做著就“忘了”原始需求。superpowers 會讓你在項目的 specs 目錄里把需求寫成 markdown 文檔把設(shè)計決策寫成設(shè)計文檔把具體步驟拆成任務(wù)清單。這樣 AI 每一輪工作都有一份穩(wěn)定的、可回溯的“施工圖紙”不會跑偏。我自己用下來最大的體會是這套流程意外地適合團隊協(xié)作。以前 AI 寫的代碼只有當(dāng)事人知道上下文現(xiàn)在規(guī)范、任務(wù)、測試全落在倉庫里任何一個新成員或者新的 AI 會話拉下來就能無縫接手。說它是“給 AI 編程建立工程紀(jì)律”一點不夸張。2. 安裝與環(huán)境準(zhǔn)備5分鐘跑起來2.1 Node 環(huán)境與依賴要求superpowers 在本地跑起來需要的基礎(chǔ)環(huán)境并不復(fù)雜核心依賴主要是 Node.js。我這里直接給出我實測可行的版本組合避免你在網(wǎng)上搜到一堆過時教程。Node.js 建議 18 或更高版本20 以上更穩(wěn)。它自帶的 npm 用來裝項目依賴。第二個關(guān)鍵依賴是 bun。這是一個 JavaScript 運行時很多 CLI 腳本在 bun 下跑得更快。你如果沒裝過用一行命令就能搞定curl -fsSL https://bun.sh/install | bash。然后就是編碼助手本尊了。superpowers 最初主要對接 Claude Code后來社區(qū)也適配了其他工具鏈熱詞里那個 “codex superpowers” 指的就是它和 OpenAI Codex 這類編碼代理搭配使用。核心邏輯是一樣的配置文件能通用。我開始沒太在意版本結(jié)果在一個老項目里用 Node 16 跑直接報了一堆語法錯誤。所以如果你是從零配環(huán)境別在舊版上糾結(jié)直接裝最新穩(wěn)定版 Node 和最新版 bun省得浪費半小時。2.2 安裝與 codex 集成配置項目安裝方式和大多數(shù) npm 全局 CLI 一樣核心命令是npm install -g superpowers裝完之后命令行里就可以直接調(diào)superpowers命令來查看了。不過要讓它真正干起活來還得讓它能調(diào)用 AI 編碼助手的能力。以 Claude Code 為例你需要在項目的配置文件 CLAUDE.md 里聲明引入 superpowers 的能力。比如# CLAUDE.md 項目的其他約定 ...然后把 superpowers 提供的工作流說明文件追加進去或者用/plugin之類的命令把它加載進來不同版本加載方式略有差異以當(dāng)時的superpowers --help輸出為準(zhǔn)。如果你用的是 Codex 這一路的工具配置思路也一樣代碼庫上下文加載的字段里加入 superpowers 的規(guī)則文件路徑讓編碼代理知道有哪些命令和流程可用。說白了superpowers 本身不直接替你去調(diào)模型它只是把“規(guī)則”喂給模型讓模型在對話過程中遵循一套固定的步驟。這個設(shè)計很巧妙本質(zhì)上它就是一個“思維腳手架”模型還是那個模型但行為方式被規(guī)范了。驗證是否裝好最簡單的方法是在任意空項目里執(zhí)行superpowers start如果它能正常在終端里啟動一個交互式引導(dǎo)并且問你類似“這個項目是做什么的”這樣的問題那就說明環(huán)境沒問題了。我第一次跑的時候前兩次都因為缺少某個環(huán)境變量直接靜默失敗后來檢查才發(fā)現(xiàn)是沒有聲明 API 密鑰。所以如果你這一步?jīng)]反應(yīng)優(yōu)先檢查環(huán)境變量。3. 核心機制拆解規(guī)范驅(qū)動開發(fā) 測試驅(qū)動開發(fā)3.1 三步規(guī)范文件明確 AI 的“施工圖紙”superpowers 的核心工作目錄只有一個項目下的specs文件夾。所有對話、任務(wù)生成、代碼迭代都圍繞這個文件夾里的 markdown 文件展開。一開始我以為是臨時約定后來才發(fā)現(xiàn)這是整套體系的靈魂。正常情況下這個目錄下有三種文件requirements-analysis.md需求分析文檔。描述這個項目到底要做什么有哪些功能點、有哪些邊界場景、用戶是誰。design.md設(shè)計文檔。記錄技術(shù)選型、模塊劃分、接口設(shè)計、數(shù)據(jù)流走向。tasks.md任務(wù)清單。把所有需求拆成一個一個可執(zhí)行的子任務(wù)每個子任務(wù)對應(yīng)一個小的可交付結(jié)果。為什么用 markdown 而不是像傳統(tǒng)任務(wù)管理那樣用 JSON 或數(shù)據(jù)庫我個人的理解是markdown 是對 AI 最友好的結(jié)構(gòu)化文本格式既保留語義層級又允許自然語言描述。你用 JSON 寫需求會很費勁用純文本又容易缺少結(jié)構(gòu)markdown 恰好折中。實際跑下來的感受是需求分析文檔決定 AI 的上限。如果你在 requirements-analysis.md 里只寫一句“實現(xiàn)用戶登錄”AI 大概率會給你一套極簡實現(xiàn)沒有 token 刷新、沒有記住登錄狀態(tài)、沒有防暴力破解。但如果你寫上“需要支持郵箱密碼登錄、第三方 OAuth 登錄、會話過期策略、登錄失敗鎖定機制”AI 出來的東西馬上就專業(yè)一個層級。說白了你自己寫需求都含糊其辭就別指望 AI 幫你補齊思考。這一步花錢花得最值。3.2 任務(wù)分解從規(guī)范到原子化任務(wù)寫完 specs 里的需求分析和設(shè)計文檔之后接下來就該執(zhí)行superpowers plan。這個命令會讀取 specs 目錄下的內(nèi)容讓 AI 生成一個 tasks.md 任務(wù)清單并且按照合理的依賴順序排列。我給一個我實際跑出來的例子。比如我讓它做一個簡單的任務(wù)管理 API第一個任務(wù)是初始化項目結(jié)構(gòu)和數(shù)據(jù)庫 schema第二個任務(wù)是實現(xiàn)創(chuàng)建任務(wù)的接口第三個任務(wù)是實現(xiàn)列表查詢并且先寫測試再寫實現(xiàn)第四個任務(wù)是實現(xiàn)任務(wù)狀態(tài)變更第五個任務(wù)是補充異常處理與校驗這里的關(guān)鍵在于任務(wù)的粒度。如果任務(wù)粒度太大比如“實現(xiàn)整個 CRUD”AI 又回到一口氣生成一大坨的老路如果粒度太小比如“創(chuàng)建一個文件夾”那又會讓整個流程碎片化上下文切換的成本比收益還高。我的經(jīng)驗是一個任務(wù)應(yīng)該對應(yīng)一個能獨立驗證的功能點并且最好涉及一次完整的“寫測試—寫代碼—跑測試”循環(huán)。plan命令生成 tasks.md 后建議你人工讀一遍。AI 的任務(wù)拆分通常靠譜但偶爾會有一些不合邏輯的依賴關(guān)系尤其是涉及外部服務(wù) mock 的部分。我自己就遇到過它把一個需要第三方 API 的功能排在 mock 測試之前導(dǎo)致測試根本沒法穩(wěn)定跑?；◣追昼娬{(diào)整一下順序后面能省很多事。3.3 測試驅(qū)動循環(huán)AI 如何自己證明代碼可用任務(wù)清單就緒后執(zhí)行superpowers code這時候 AI 會逐條讀取 tasks.md 里的任務(wù)按順序往下執(zhí)行。每執(zhí)行一個任務(wù)它會遵循一個固定的循環(huán)先寫一個失敗的測試再實現(xiàn)最小代碼讓測試通過然后跑測試確認綠色再提交一次代碼。這個過程其實就是經(jīng)典 TDD 的 Red-Green-Refactor只不過執(zhí)行者換成了 AI。你可能要問讓 AI 自己寫測試、自己寫實現(xiàn)、自己跑測試這不就是自己監(jiān)考自己嗎聽起來確實有種“左手考右手”的感覺但實際效果比想象中要可靠得多。關(guān)鍵在于測試代碼是一種可執(zhí)行的、客觀的驗收標(biāo)準(zhǔn)一旦測試?yán)锇藢吔鐥l件、異常分支、期望返回值的斷言AI 在寫實現(xiàn)代碼的時候就必須滿足這些斷言這就堵住了它“糊弄過去”的路。舉個我遇到的例子我讓 AI 實現(xiàn)一個金額格式化函數(shù)。如果只寫實現(xiàn)它可能直接toFixed(2)完事但 superpowers 的流程里它會先寫測試測試?yán)锇恕拜斎?0 返回 0.00”、“輸入負數(shù)返回 -1.23”、“輸入極大值不溢出”這幾個用例。有了這些用例卡著它后續(xù)的實現(xiàn)自然就對邊界情況更敏感。這就是測試對行為的反推作用。整個循環(huán)跑完之后AI 會把代碼提交到本地 git很多時候還會順手生成一個 PR 描述。如果你中途不滿意可以回到specs/requirements-analysis.md里修改需求然后重新執(zhí)行 plan 和 code增量迭代。這個機制讓我徹底棄用了“一條指令生成整個項目”的舊習(xí)慣因為那種方式改需求簡直是一場災(zāi)難而在 superpowers 模式下改需求就是改文檔、重新拆任務(wù)、重新執(zhí)行整個過程完全可追蹤。4. Java 場景實操從寫規(guī)范到功能落地4.1 初始化一個 Java 項目并編寫第一步規(guī)范熱詞里有“superpowers java”說明不少人關(guān)心它在 Java 項目里的實際效果。我這邊正好用 Java 場景做一次完整演示。先說結(jié)論superpowers 對語言沒有偏見它對 Java 的支持完全建立在“測試框架 構(gòu)建工具”的可復(fù)現(xiàn)性上。只要你的項目能在命令行里用一條命令完成測試它就能跑起來。我以 Maven 標(biāo)準(zhǔn)結(jié)構(gòu)的項目為例。假設(shè)我們做一個用戶注冊服務(wù)只處理兩件事檢查用戶名是否重復(fù)、創(chuàng)建用戶記錄。先建一個空項目mvn archetype:generate -DgroupIdcom.example -DartifactIduser-register -DarchetypeArtifactIdmaven-archetype-quickstart進入目錄后手動把src/test/java結(jié)構(gòu)和 JUnit 依賴配好確保這句命令能跑通mvn test此時如果輸出BUILD SUCCESS說明環(huán)境就緒。然后是關(guān)鍵一步創(chuàng)建 specs 目錄寫需求分析文檔。注意這里我建議你直接面向“驗收標(biāo)準(zhǔn)”寫需求比如用戶可以注冊、用戶名不能重復(fù)、重復(fù)時返回明確錯誤碼、用戶名長度限制在 3 到 20 個字符之間。這些內(nèi)容越具體后面 tasks.md 的任務(wù)拆分就越細AI 寫出來的代碼越貼合預(yù)期。4.2 運行 plan 生成開發(fā)計劃接下來執(zhí)行superpowers plan這會讓編碼代理讀取 specs 里的需求設(shè)計和設(shè)計文檔生成任務(wù)清單。我當(dāng)時生成的 tasks.md 大致是這樣的設(shè)置 Spring Boot 基礎(chǔ)工程及 Maven 依賴創(chuàng)建 User 實體和 Repository 接口先寫測試實現(xiàn) UserService 中的重復(fù)檢測邏輯先寫測試實現(xiàn)注冊接口及參數(shù)校驗先寫測試驗證整體測試通過并補充集成測試可以看到它把“測試”作為每個任務(wù)的前置條件不斷提及這說明任務(wù)拆分本身就是在引導(dǎo) TDD 流程。你如果發(fā)現(xiàn)某個任務(wù)描述得太籠統(tǒng)比如只是“實現(xiàn)某個東西”直接手動改一下 tasks.md把它改成帶驗收標(biāo)準(zhǔn)的描述。這個文件你完全有控制權(quán)AI 只是建議者不是決定者。4.3 運行 code 讓 AI 迭代實現(xiàn)任務(wù)清單搞定后執(zhí)行superpowers codeAI 就按照順序跑起來了。我觀察到的過程大致是這樣它先讀取第一個任務(wù)然后在項目里初始化或補充 pom.xml、創(chuàng)建目錄結(jié)構(gòu)運行一次測試確保當(dāng)前基線是綠的。然后進入第二個任務(wù)先寫一個 UserRepository 的測試類再寫對應(yīng)實現(xiàn)運行單個測試類通過后繼續(xù)下一個。這個過程中終端會不斷輸出測試日志你能實時看到它哪一步通過了、哪一步還在紅。值得注意的一個細節(jié)它并不總是一次通過。我那次跑第三個任務(wù)時它第一次實現(xiàn)的重復(fù)檢測忽略了大小寫問題測試立刻給了一個紅。然后它回頭看了看測試期望自己修正成了忽略大小寫的比較邏輯再跑測試綠了。整個過程完全不需要我介入。這種“試錯—反饋—修正”的能力只有在測試閉環(huán)里才能實現(xiàn)也正因如此它輸出的代碼比直接生成的要抗打很多。4.4 驗證、收尾與提交流程所有任務(wù)跑完后最好別直接信任“全部通過”的輸出自己再手動跑一次完整構(gòu)建。mvn clean verify我建議你特別檢查一下測試覆蓋率。superpowers 生成的測試通常不是為了覆蓋率而覆蓋率方法覆蓋和分支覆蓋做得都還可以但集成層面的測試偏少。如果你這個項目涉及數(shù)據(jù)庫交互它默認可能用 H2 內(nèi)存庫來測試此時要確認本地真實 MySQL 或 PostgreSQL 的行為是否一致避免“測試綠、上線紅”的悲劇。代碼提交方面AI 默認行為是每個任務(wù)完成后獨立提交一次提交信息寫得還挺規(guī)范的。我在實操過程中會把多個任務(wù) squash 成一個功能提交保持 git 歷史干凈這個看團隊習(xí)慣。如果你用 GitHub讓 AI 在最后一個任務(wù)完成后生成 PR 描述效果也不錯。整體上我用 superpowers 跑了這個 Java 注冊服務(wù)從空項目到功能落地大概十分鐘左右其中大部分時間是花在等待測試執(zhí)行上真正的人工干預(yù)很少。5. 常見問題與排查技巧實錄5.1 常見報錯與修復(fù)速查表實操中一定會遇到各種奇奇怪怪的問題我把高頻的整理成表格方便你對癥下藥?，F(xiàn)象可能原因處理方式superpowers命令找不到npm 全局 bin 目錄不在 PATH檢查 npm config get prefix手動加入 PATH啟動時靜默報錯API 環(huán)境變量未設(shè)置確認編碼助手的 API 密鑰已寫入當(dāng)前 shell 環(huán)境plan 生成的任務(wù)順序不合理需求描述不夠具體回改 requirements-analysis.md補充依賴關(guān)系描述code 運行時反復(fù)修改同一功能測試太弱沒有覆蓋邊界增強測試用例加入邊界值和異常路徑斷言跑完測試但代碼沒有提交git 身份未配置先執(zhí)行 git config user.name 和 user.email某個任務(wù)始終過不了外部依賴 mock 不穩(wěn)定檢查測試中是否有網(wǎng)絡(luò)請求或時間依賴替換為可重復(fù)的 stub這里我想單獨說說“某個任務(wù)始終過不了”的情況。很多人在這一步就放棄了手動把代碼改了讓測試過。但我的建議是先別急著動手改代碼先改測試。觀察一下失敗信息到底是測試期望錯了還是實現(xiàn)確實錯了。superpowers 的流程里測試是“合同”實現(xiàn)是“履約方”如果測試期望本身就不合理比如要求一個有損算法做到無損輸出那合同就該改。把這一點想清楚你能省很多調(diào)試時間。5.2 別忽略 .superpowers 目錄里的上下文項目根目錄下除了 specs還會生成一個.superpowers或類似的隱藏目錄。我一開始覺得這是緩存數(shù)據(jù)沒怎么管后來排查一個詭異問題才發(fā)現(xiàn)這里存了很多關(guān)鍵的中間狀態(tài)和對話上下文。包括 AI 在分析需求時的思考記錄、plan 的生成過程、每輪 code 循環(huán)的狀態(tài)記錄。比如有一次我改了 tasks.md 重新執(zhí)行 code發(fā)現(xiàn) AI 表現(xiàn)的像是沒看到最新修改。排查后發(fā)現(xiàn)是舊的任務(wù)狀態(tài)快照還在 .superpowers 里它讀的是緩存狀態(tài)而不是最新的 tasks.md。解決方式是刪掉該目錄下對應(yīng)的狀態(tài)文件再重新 plan。這個坑很隱蔽網(wǎng)上也不太有人提。5.3 體驗優(yōu)化的幾個小技巧最后分享幾個我實測提升體驗的小技巧全是常規(guī)文檔里不會寫的東西。第一規(guī)范文檔的顆粒度要和團隊能力匹配。如果你的團隊對 AI 生成的代碼還處于觀望階段不要一上來就要求 AI 做全棧大項目。先挑一個小模塊用 superpowers 走一遍完整流程讓團隊成員看到測試閉環(huán)帶來的穩(wěn)定感比任何宣傳都有說服力。第二別只盯代碼盯規(guī)范。這套體系的杠桿點全在 specs 目錄里。代碼寫崩了改代碼只是治標(biāo)改需求分析才可能治本。如果你發(fā)現(xiàn) AI 生成的代碼頻繁偏離目標(biāo)大概率是需求分析里存在歧義而不是 AI 偷懶。第三多語言項目的測試命令要固定。superpowers 是靠“跑測試”來驗收的所以項目里必須有一條穩(wěn)定的、可重復(fù)的測試命令。Java 里是 mvn testNode 里是 npm testPython 里是 pytest開工前先把這條命令確?？捎煤竺嫠辛鞒潭紩槙澈芏?。第四給 AI 一個“大本營”文檔。項目根目錄的 CLAUDE.md 或類似說明文件里除了引入 superpowers 規(guī)則還可以寫一點項目自己的約定比如代碼風(fēng)格、數(shù)據(jù)庫命名規(guī)范、提交信息格式。這些內(nèi)容每次對話都會加載進上下文你會驚訝地發(fā)現(xiàn) AI 生成的代碼風(fēng)格瞬間就貼合作業(yè)習(xí)慣了。我個人的體會是superpowers 最大的價值不是某個具體命令而是那套“先想清楚再動手、先用測試約束再實現(xiàn)”的思維方式。以前我總是急著讓 AI 生成代碼現(xiàn)在反而會先坐在 specs 文檔前把需求和邊界理清。這個過程多花二十分鐘后面的迭代時間至少省一半。另外我建議你第一次嘗試時別直接就上正式項目用一個小練習(xí)項目跑通整個循環(huán)感受一下“需求—計劃—代碼—測試”的節(jié)奏。等你真正習(xí)慣之后再把它引入到日常工作流里那時候你會發(fā)現(xiàn)AI 編程從“碰運氣”變成了“走流程”穩(wěn)定性和可控性完全不是一個量級。這就是 superpowers 給我的最大啟發(fā)真正的超能力不是讓 AI 替你寫代碼而是讓你和 AI 之間建立一套彼此都遵守的工程契約。