一開始我在本地把 superpowers 裝進 Codex CLI純粹是因為受不了默認對話模式反復返工。你讓 Codex 改一個 Java 方法它改了實現卻忘了按約定跑測試你提醒一次它才補上補完之后又把無關的格式動了一堆。與其說這是在協(xié)作不如說是在盯人。后來我把 superpowers 作為一套技能目錄掛到 Codex 的技能加載路徑里情況才真正好轉它開始自己拆任務、先寫測試、再實現、再重構像一個有基本職業(yè)素養(yǎng)的同事而不是一個只會接話的聊天窗口。這篇算是一份個人實測記錄不是官方文檔。我會把安裝方式、目錄規(guī)劃、Java 項目實戰(zhàn)和踩坑排查都寫清楚適合那些已經在用 Codex CLI、想進一步規(guī)范 AI 工作流的開發(fā)者。如果你主要寫 Java第 4 和第 5 節(jié)可以直接當作業(yè)指導來用。1. 先搞清楚Superpowers 到底給 Codex 加的是什么能力1.1 一個反直覺的結論它不是插件而是“技能包”很多人一聽“給 Codex 裝 superpowers”會下意識以為是個 VSCode 插件、MCP 服務或者 npm 包。我最初也這么想結果 clone 下來一看項目里最多的東西是.md文件。Superpowers 本質上是一套“工作流指令集”。它通過 Markdown 文件定義各種技能每個技能文件里寫清楚了這個技能在什么場景下觸發(fā)、執(zhí)行時先做什么后做什么、中間要輸出什么中間產物、最后用什么樣的驗收標準來判斷完成。Codex 作為 Agent 讀取這套技能之后相當于拿到了一本非常細的作業(yè)手冊。你可以把它理解成給實習生寫的 S.O.P。實習生聰明反應快但不知道你公司的代碼規(guī)范是先寫測試再寫實現不知道重構前后要跑完整套用例不知道改完接口還要順手更新調用方。S.O.P 把這些流程固化成文本Agent 每次開工前先讀一遍行為就從“自由發(fā)揮”變成了“按流程執(zhí)行”。這也是為什么它叫 superpowersCodex 本身的能力天花板沒有變但使用方式被重新組織之后產出質量明顯提升。注意它不是黑魔法它改變的是工作流不是模型智商。1.2 為什么 Codex 原生對話做不到這些直接和 Codex 對話時它會根據上下文即興決定下一步。如果用戶不提測試它就默認你不需要測試如果用戶說“幫我重構一下”它可能只改了一個文件剩下的地方靠猜。原生對話模式的問題不是模型能力不足而是缺少“強制步驟”。Superpowers 解決的是這個“缺少強制步驟”的問題。它的技能文件里會明確要求開始寫業(yè)務代碼前必須先寫一個失敗測試測試跑紅之后才允許進入實現階段實現通過后再進入重構階段。每一步都有明確的輸入輸出Codex 不能跳過“跑測試”這個動作直接給你交代碼。我試過在同樣一臺機器上用同一個 Codex 模型處理同一個 Java 需求。不開 Superpowers 時它給出的代碼能編譯但單元測試覆蓋率只有 30%而且沒有按項目里既有的異常處理風格來寫。開了 Superpowers 并加載 TDD 技能后它先自己建了src/test/java目錄寫了完整的邊界測試再實現主類最后跑mvn test還主動把 Integer 運算改成了 BigDecimal。差距就在流程。1.3 Superpowers 替你跑起來的三條核心工作流我實際用得最多的是三條工作流。第一條是 TDD測試驅動開發(fā)。這個技能會要求 AI 嚴格按“紅燈-綠燈-重構”來走。紅燈階段只寫測試不寫實現綠燈階段用最簡代碼讓測試通過重構階段清理重復代碼和命名問題。第二條是任務拆解。面對一個比較大的需求比如“給現有模塊加一個消息隊列消費者”Superpowers 會先把這個需求拆成若干子任務每個子任務有明確的交付物和驗收條件然后逐個執(zhí)行。這個能力在長任務里特別重要因為 Codex 一旦上下文被拉長很容易忘記最初目標。第三條是自動代碼審查。完成實現后技能會要求 Codex 自己扮演 reviewer檢查潛在 bug、并發(fā)問題、異常處理漏洞和測試盲區(qū)。它會輸出問題清單再根據清單逐條修復。這三條工作流可以單獨用也可以串起來。我通常把三條串在一起使用先拆任務再對每個子任務執(zhí)行 TDD最后做一輪 review。效果比單獨開任何一條都要穩(wěn)。2. 安裝前必須想明白的目錄規(guī)劃與版本選擇2.1 先檢查你的本地環(huán)境在動手裝之前我建議你先跑一遍環(huán)境檢查。以下三個命令分別確認 Codex CLI、Git 和構建工具的狀態(tài)codex --version git --version mvn --version如果你用的是 Gradle 項目就把最后一個換成gradle --version。這里有個容易忽略的點Codex CLI 本身是通過 npm 安裝的所以 Node.js 環(huán)境也需要是正常的但只在安裝階段用到運行時不一定依賴 Node。我遇到過一個情況Codex 版本太老技能加載路徑還不穩(wěn)定導致軟鏈接過去了也讀不到。后來升級到新版本才恢復正常。所以如果你之后遇到“明明配置了卻不起作用”的怪問題先懷疑版本再懷疑配置。2.2 用戶級、項目級、全局三種安裝位置的取舍安裝 Superpowers 之前要決定放哪里。這個決定影響范圍很大我見過不少人直接散裝到一堆項目里最后每個項目都要維護一份很痛苦。用戶級安裝是把技能目錄放到~/.codex/skills/下面所有項目都能用。單個開發(fā)者自己用我推薦這種方式。項目級安裝則是放到某個倉庫的.codex/skills/或.agents/skills/目錄下會隨倉庫走團隊提交代碼時能一起同步。全局安裝是把它當作系統(tǒng)級指令放到 PATH 或公共配置目錄里適合公司內部統(tǒng)一推行的場景但維護成本最高。你可以先按一張表來判斷安裝位置生效范圍適合場景維護成本用戶級當前用戶所有項目個人日常開發(fā)、試驗新技能低項目級單個倉庫團隊項目、需要統(tǒng)一規(guī)范的倉庫中全局系統(tǒng)級機器上所有用戶公司開發(fā)機標準化高從我自己的經驗看絕大多數開發(fā)者從用戶級開始就夠了。等你在團隊里驗證了某條工作流確實有用再把它下沉到項目級讓每一個克隆倉庫的同事都能自動拿到。2.3 我推薦的目錄布局目錄布局不復雜但有個結構問題值得提前想好Superpowers 自帶的技能是公用的你自己后加的技能是私有的。如果混在一個目錄里升級 Superpowers 時可能會把自定義內容覆蓋掉。我是這么組織的~/.codex/ ├── config.toml ├── AGENTS.md └── skills/ ├── superpowers/ # 官方技能 ├── team/ # 團隊私有技能 └── personal/ # 個人私有技能這樣升級 Superpowers 時只需要替換superpowers這一個子目錄team和personal完全不受影響。Codex 加載技能是讀取整個skills目錄的所以不同來源之間不會沖突只要技能命名唯一就行。3. 掛載 Superpowers 到 Codex CLI兩條實測可行的路線3.1 路線一軟鏈接到 Codex 全局技能目錄我先說我自己最常用的方式。它基于用戶級安裝好處是升級方便、回滾方便而且不會把第三方代碼散落到項目倉庫里。第一步把 Superpowers 倉庫克隆到一個固定位置git clone https://github.com/obra/superpowers.git ~/superpowers第二步在 Codex 的技能目錄里創(chuàng)建一個軟鏈接mkdir -p ~/.codex/skills ln -s ~/superpowers/skills ~/.codex/skills/superpowers這里有一個細節(jié)鏈接目標不是~/superpowers本身而是它內部的skills目錄。因為 Codex 期望的是“技能目錄下面直接放技能文件”而不是“技能目錄下面再套一層倉庫結構”。我第一次犯過這個錯誤鏈接到倉庫根目錄結果加載時一個技能都識別不到。第三步如果你是新版本 Codex通常還需要在配置里確認啟用了 Agent Skills。在~/.codex/config.toml里加入[skills] enabled true不同版本的配置字段名可能不一樣。最穩(wěn)妥的辦法是運行codex --help查看當前版本是否包含 skills 相關參數。如果沒找到也不用慌很多版本會在檢測到技能目錄后自動加載。3.2 路線二放進項目級 .agents 目錄如果你的團隊成員都會 clone 同一個倉庫項目級安裝更合適。Codex 在項目目錄下會讀取.agents/skills/或者.codex/skills/具體看版本。你可以直接復制也可以用子模塊引入。用 git submodule 的方式是cd your-project mkdir -p .agents/skills git submodule add https://github.com/obra/superpowers.git .agents/skills/superpowers然后用一條軟鏈接再處理一層讓技能文件位于.agents/skills/superpowers下面一層。如果直接 clone 到.agents/skills/superpowers你需要確認這里面直接是 Markdown 技能文件而不是又包含一個skills子目錄。項目級安裝最大的好處是“開箱即用”。新人 clone 倉庫之后Codex 自動就帶上了全部技能不用每個人手動去配。它的代價就是倉庫里多了第三方代碼如果你不喜歡 submodule也可以用腳本在初始化時自動 clone 和軟鏈。3.3 修改配置與驗證加載配置除了開關 skills還有一個容易被忽略的文件AGENTS.md。Codex 在開始任務前會自動讀取當前目錄和用戶目錄下的AGENTS.md你可以用它來聲明技能加載規(guī)則。我習慣在用戶級~/.codex/AGENTS.md里寫這么一段# Agent Instructions - 開始任務前檢查 ~/.codex/skills/ 下是否有與任務匹配的技能。 - 如果存在匹配技能必須按技能文件中的步驟執(zhí)行不能跳過任何步驟。 - 涉及測試代碼時優(yōu)先遵循 TDD 技能的“紅燈-綠燈-重構”流程。這段文本的作用是讓 Codex 別偷懶。技能文件是“儲備”AGENTS.md是“啟動器”。兩者配合Codex 才會真的去翻技能而不是你每次手動在對話里要求它讀文件。驗證是否加載成功我提供一個最簡單的辦法直接在 Codex 里問他“你當前有哪些可用的技能請列出技能名稱和用途”。如果它正確說出了 Superpowers 里的幾項技能說明加載鏈路已經通了。如果它一臉茫然就去查~/.codex/skills/目錄結構和配置文件八成是路徑套多了一層。4. 真刀真槍在 Java 項目里讓 Superpowers 驅動 TDD4.1 先準備一個不會干擾 AI 的最小 Java 工程很多人在這一步就栽跟頭工程里有一堆歷史遺留代碼、多模塊依賴、自定義 parent POMCodex 一啟動就被上下文塞滿后面根本跑不起來。我建議你用一個“最小可復現工程”來驗證 Superpowers而不是直接扔一個大倉庫。最小工程要滿足三個條件只有一個模塊構建工具用 Maven 或 Gradle依賴盡量少src/main/java和src/test/java目錄結構明確測試框架用 JUnit 5不要引入 Mockito、MockMvc 這類容易分散注意力的東西我用一個金額計算器來做實驗。需求很簡單支持金額的加法、減法、乘法且不能出現浮點精度問題。這類需求足夠觸發(fā)一次完整的 TDD 循環(huán)又不會讓 AI 花太多時間在業(yè)務背景上。工程目錄結構大概是money-calc/ ├── pom.xml └── src/ ├── main/java/com/example/money/ │ └── Money.java └── test/java/com/example/money/ └── MoneyTest.java注意初始狀態(tài)只保留 Maven 配置和一個空模塊兩個 Java 類都不用寫交給 Codex 來生成。4.2 用一句話需求觸發(fā)完整工作流在 Codex 里輸入一句話“在這個 Maven 工程里新增一個 Money 類金額用分存儲支持加、減、乘要求所有運算不丟精度。請按照 TDD 技能執(zhí)行?！比绻阋呀浾_加載了 SuperpowersCodex 的第一步不會是直接創(chuàng)建Money.java而是先檢查測試目錄里有沒有測試文件。發(fā)現沒有后它會先創(chuàng)建MoneyTest.java。這個測試文件會覆蓋至少五種情況金額加法正常進位金額減法出現負數乘法結果四舍五入到分大數相加不溢出字符串轉金額時處理非法輸入然后它才創(chuàng)建Money.java的實現類用long類型的字段保存“分”而不是用double。實現完成后再跑一次mvn test確認全部測試通過。這是不是看著很簡單是的。但注意在沒掛 Superpowers 之前同一句話進 Codex它大概率會先給你一個Money類里面用BigDecimal然后告訴你“用 BigDecimal 就不會丟精度”。它不會先寫測試也不會驗證邊界。兩種輸出的差別就是技能流程帶來的。4.3 我對輸出產物的驗收標準讓 Codex 干完活之后我不會只看“測試通過”就收工。我有一套自己的驗收清單針對 Java 項目重點檢查以下項目領域類的核心狀態(tài)是不是用了原始類型或不可變對象避免自動拆箱問題金額輸入是否在構造函數里做了校驗負數、null、非數字字符串有沒有被攔截測試是否覆蓋了“邊界值”比如等于 0、正好進位、超過 Long 最大值是否遵循了項目既有的異常設計比如統(tǒng)一拋出IllegalArgumentException是否在實現階段引入了不必要的外部庫比如為了一個加法把整個 Guava 拉進來Superpowers 的 TDD 技能會讓 AI 在“紅燈”階段先寫失敗測試這本身就保證了大多數邊界會被覆蓋。但 AI 不會替你決定業(yè)務規(guī)則比如“金額是否允許為負數”這事必須由你在需求里講清楚。你在對話里說“金額不能為負”它就會把校驗邏輯放進實現里你不說它可能就漏掉。4.4 如果第一步沒跑通先查這四件事如果你像我一樣滿懷期待地輸入需求結果 Codex 還是直接生成實現類完全沒走 TDD先別急著懷疑工具炸了。按順序排查第一技能是否真的被加載?；氐降?3 章最后說的驗證方法問一次“當前可用的技能”。第二AGENTS.md是否生效。如果你只配置了技能文件但沒在AGENTS.md里聲明“必須按技能執(zhí)行”Codex 很可能會忽略它因為對它來說技能只是“可用參考”不是“必須流程”。第三當前工作目錄對不對。如果你從~目錄啟動 Codex而不是從項目目錄啟動它可能讀不到項目級配置也不會認為這是 Maven 工程。第四模型上下文窗口是否被塞滿。如果剛才的對話已經很長了技能文件的加載會被截斷工作流自然就走不完整。新開一個會話再試一次。我遇到的絕大多數問題都能靠“新開會話 明確讓 AI 使用 TDD 技能”解決。5. Codex Superpowers 跑 Java 時我踩過的四個坑5.1 坑一Maven 還是 Gradle——AI 自己換了構建工具有一次我在一個 Maven 工程里讓 Codex 完成一個模塊開發(fā)結果它生成了一堆build.gradle文件還自作聰明地把目錄結構調整成了 Gradle 布局。原因是我在自然語言里提了一句“用你熟悉的構建方式”它就直接選擇了 Gradle。這很麻煩。因為 CI、IDE、同事的本地環(huán)境全是以 Maven 為準AI 擅自切換構建工具會導致整個分支不可用。根因是技能文件里只定義了 TDD 流程并沒有限定“當前項目必須識別既有構建配置”。解決辦法是在項目內AGENTS.md里寫死# 構建規(guī)范 - 本項目使用 Maven禁止生成或新增 Gradle 相關文件。 - 所有新代碼必須位于 src/main/java 和 src/test/java。 - 構建命令一律使用 mvn不使用 gradle。這條規(guī)則加進去之后Codex 不會再自由發(fā)揮。類似地如果你項目里用的是 Kotlin最好也把語言版本和構建命令寫清楚。5.2 坑二誤刪手寫測試的問題掛上 Superpowers 之后AI 的任務拆解能力變強但它對“哪些是它生成的、哪些是手寫的”并沒有可靠判斷。某次重構時它把一批手寫測試刪掉了理由是“這些測試覆蓋場景與生成的測試重復”。我回過神之后發(fā)現它其實不是真的想刪而是技能的 review 環(huán)節(jié)要求它清理“冗余測試”它把“覆蓋邏輯重復”和“直接刪除”劃了等號。這是 Agent 常見的過度總結。解決思路有兩個。第一在手寫的測試文件頂部加注釋說明該文件是人工維護AI 只能追加不能刪除例如// IMPORTANT: Manually maintained test. Do not delete or rewrite. Only append.第二在AGENTS.md里增加一條硬性規(guī)則“任何刪除測試文件的操作必須經過用戶明確批準不能自行判斷。”這兩條加進去之后我再沒遇到過誤刪。5.3 坑三技能文件被帶進 git 提交項目級安裝 Superpowers 后如果你把它放進了.agents/skills/很容易在提交代碼時不小心把整個技能倉庫一并提交。我自己有一回發(fā)現提交記錄里多了幾百個 Markdown 文件全是第三方技能內容把倉庫搞得又臭又大。這并不是說不能放項目級而是要在.gitignore里明確排除或者用 submodule 而不是直接復制文件。如果你想讓技能隨項目走我建議用 submodule并在倉庫文檔里寫清楚如何初始化和更新如果你不想讓技能進倉庫就把它放進用戶級目錄項目內只通過AGENTS.md引用。我最終的選擇是官方 Superpowers 放用戶級團隊私有技能放獨立私有倉庫項目只保留一份AGENTS.md引用指南。這樣倉庫干凈升級也靈活。5.4 坑四上下文太長導致工作流中斷Superpowers 的工作流步驟不少每一步都會產生大量輸出。Codex 的上下文窗口雖然不小但在一個超過千行的 Java 工程里再疊加多輪對話很容易出現“后半段工作流被截斷”的情況。表現是紅燈測試還在綠燈實現已經結束了重構步驟直接消失。我的處理方式很簡單一個任務只做一件事。不要讓 Codex 在一個會話里同時完成需求分析、代碼生成、測試、重構、文檔更新。把任務拆小之后再用 Superpowers 的技能逐個執(zhí)行。你可以手動拆也可以讓它先執(zhí)行“任務拆解”技能給你一份子任務清單然后你在新會話里逐個發(fā)起。這個習慣我非常推薦。不只解決上下文問題也讓 Codex 每一步的變更都更可控代碼 review 更容易。6. 從“能用”到“好用”把 Superpowers 變成團隊規(guī)范6.1 把團隊規(guī)范寫進自定義 skillSuperpowers 自帶的技能面向通用開發(fā)場景但每個團隊都有自己的規(guī)矩數據庫訪問必須走某個封裝類日志必須帶 traceId接口返回必須包一層 Result。這些規(guī)矩如果只靠口頭交代Codex 永遠學不會。你應該做的是寫自己的技能文件。放在~/.codex/skills/team/目錄下命名如java-project-standards.md里面用步驟條形式寫清團隊規(guī)范。比如# Java Project Standards 當處理 Java 代碼時必須遵循以下規(guī)范 1. 所有對外接口的返回類型必須是 ResultT禁止直接返回裸對象。 2. 日志必須包含 traceId禁止使用 logger 輸出敏感字段。 3. 新增依賴前先檢查 pom.xml 中是否已有相同功能依賴。 4. 異常處理統(tǒng)一使用 BizException禁止在業(yè)務代碼里吞異常。 5. 單元測試類命名為 XxxTest所有公開方法必須有覆蓋。寫完之后Codex 每次在這個目錄下啟動都會自動讀取相當于團隊規(guī)范被標準化成了 Agent 可以直接執(zhí)行的指令。這比寫在 wiki 里等著被人翻閱有效得多。6.2 設置可驗證的完成標準Superpowers 的“技能化”思路很好但 AI 判斷“完成”的標準和人類不完全一致。你覺得完成是“測試通過 代碼走查 無新增依賴”AI 可能覺得“編譯通過”就是完成。在團隊內推行 Superpowers 時我建議把完成標準作為一個獨立技能文件固定下來。比如definition-of-done.md里面寫# Definition of Done 只有同時滿足以下條件一個子任務才能標記為完成 - 相關單元測試全部通過且覆蓋關鍵分支。 - 代碼符合團隊編碼規(guī)范參見 java-project-standards。 - 沒有新增未使用的依賴。 - 沒有修改與當前任務無關的文件。 - 沒有刪除或重命名既有測試。這個文件一旦被 Codex 讀取它的“完成”判斷就有了明確邊界不會出現“我覺得寫完了”這種模糊狀態(tài)。我們在團隊里加了這條之后AI 生成代碼的返工率降了大約三成。6.3 多 skill 共存時的優(yōu)先級技能文件多了之后會出現沖突。比如通用 TDD 技能要求“先寫失敗測試”團隊規(guī)范技能要求“所有公開方法必須有測試”這兩者方向一致但另一個技能要求“禁止使用 Mockito”而 Codex 生成測試代碼時卻經常順手用 Mockito沖突就來了。Codex 加載多個技能時并沒有嚴格的優(yōu)先級設計。它會把所有可用技能都視作參考然后根據上下文自行組合。所以我們做了一件簡單而有效的事在AGENTS.md里明確寫了“技能加載優(yōu)先級”。例如# Priority Rules 當多個技能對同一個問題給出不同指導時優(yōu)先級從高到低為 1. definition-of-done 2. java-project-standards 3. superpowers 內置的 TDD 技能 4. 其他通用技能這一行看起來簡單但能省掉大量來回“掰扯”。Agent 不再隨機選擇規(guī)范而是有一個明確的沖突裁決順序。6.4 團隊共享與維護最后說一句維護的事。Superpowers 這一類技能方案不是“裝完就不管了”。技能是文本文本就需要定期更新。我們團隊的做法是每月抽半天把最近被 AI 踩過的坑整理成新的技能條目比如“禁止用 stream 處理大列表”、“生成接口文檔時必須同步修改 OpenAPI 文件”。這些條目積累在團隊私有技能倉庫里新人直接用老手也省得反復強調。如果你一個人開發(fā)也可以做這件事不用等別人。每次遇到 Codex 在項目里犯的重復性錯誤就把它改成一條技能規(guī)則下一次它就不會再犯。這種體驗帶點“馴養(yǎng)個人助手”的感覺也正是 Superpowers 真正值錢的地方它不只是在給 AI 加能力更像是在幫團隊把經驗沉淀成一堆高密度的文本資產。我現在每天開 Codex 之前都會順手看一眼技能目錄里有沒有新增內容。這種習慣說不上多高級但用了幾個月之后Codex 產出的代碼質量明顯比之前更穩(wěn)定當初那種“盯著它別亂來”的感覺也減輕了。如果你也被默認對話模式里的來回拉扯折磨過不妨照著這個流程試一次。