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