1. 什么是 superpowers它到底解決什么問題先說結(jié)論如果你在用 Codex CLI 這類終端里的 AI 編程 Agent發(fā)現(xiàn)它“能寫代碼但不會(huì)干活”——單文件補(bǔ)丁沒問題跨模塊改功能就手忙腳亂還總記不住項(xiàng)目里約定俗成的寫法那 superpowers 大概率就是你缺的那一層。我最初接觸 Codex CLI 的時(shí)候感受是“什么都能聊但什么都淺”。讓它修個(gè) bug 還能應(yīng)付讓它按團(tuán)隊(duì)規(guī)范走完整的 TDD 流程、同時(shí)維護(hù)設(shè)計(jì)文檔、再跑回歸測(cè)試它就完全沒章法了。原因不難理解Codex 默認(rèn)的工作模式偏“對(duì)話驅(qū)動(dòng)的補(bǔ)丁生成”它對(duì)當(dāng)前對(duì)話上下文敏感可對(duì)長(zhǎng)期項(xiàng)目結(jié)構(gòu)、行業(yè)慣例、工具鏈約定幾乎沒有記憶。每次開啟新會(huì)話它都會(huì)退化成一個(gè)“懂很多但什么都不了解你的項(xiàng)目”的外來人員。superpowers 這類東西本質(zhì)上是一套給 AI Agent 用的配置和技能框架。它不是模型不重新訓(xùn)練任何參數(shù)也不替代 Codex CLI 本身。它提供的是一組明確的行為指令、可復(fù)用的技能腳本、以及按項(xiàng)目或全局生效的上下文文件讓同一個(gè)模型在你的終端里表現(xiàn)出完全不同的工作水準(zhǔn)。說白了就是把“提示詞工程”從對(duì)話里抽出來做成了工程化的、可版本管理的文件體系。這類框架在圈子里有各種名字有叫 skills 庫(kù)的有叫 command 集合的有叫 agent rules 的。superpowers 的特點(diǎn)是把這套東西做得比較徹底它不只給你一兩個(gè)命令示例而是搭了一套分層結(jié)構(gòu)全局的基礎(chǔ)能力、項(xiàng)目級(jí)的領(lǐng)域約束、語(yǔ)言級(jí)的語(yǔ)法規(guī)則全部拆開可以單獨(dú)啟用或覆蓋。配合 Codex CLI 的 flexible mode 和自定義 slash command一套配置下來你會(huì)明顯感覺到 Agent 變得像“一個(gè)熟悉這個(gè)倉(cāng)庫(kù)的老同事”而不是“一個(gè)每次都要重新認(rèn)識(shí)項(xiàng)目的實(shí)習(xí)生”。這篇文章從我的實(shí)際使用經(jīng)驗(yàn)出發(fā)講清楚 superpowers 的安裝、結(jié)構(gòu)、定制方式、常見坑以及怎么讓它服務(wù)于 Java 這類強(qiáng)規(guī)范的工程場(chǎng)景。后面的內(nèi)容全部是可復(fù)現(xiàn)的操作不是概念介紹。2. 安裝之前你需要明確的三個(gè)前提2.1 本機(jī)環(huán)境與前置工具superpowers 本身不復(fù)雜但它依賴的底座比較多前置裝不對(duì)后面所有步驟都會(huì)連鎖出問題。一個(gè)可以正常運(yùn)行 AI Agent 的 CLI 工具我這邊用的是 Codex CLI安裝方式是用 npm 全局裝。Node.js 版本建議 18 以上因?yàn)檫@堆配置腳本大多用 JavaScript 寫而且新版 Codex CLI 對(duì) Node 版本有明確要求。Git 必須可用因?yàn)榧寄軒?kù)的版本管理和更新依賴 git。編輯器方面VS Code 或 JetBrains 系都可以看你日常習(xí)慣。但我建議至少在初始階段讓終端保持干凈不要引入太多插件變量方便排查問題。這個(gè)組合不是我拍腦袋定的。Node.js 是 Codex CLI 的運(yùn)行時(shí)基礎(chǔ)Git 是做技能配置版本管理的唯一可靠方案編輯器的選擇則決定了你在哪些環(huán)節(jié)能可視化地看到 Agent 的行為日志。三個(gè)前置都到位后面裝什么東西都順暢。2.2 為什么推薦先在全局層面安裝而不是項(xiàng)目級(jí)很多教程一上來就讓你往項(xiàng)目里塞 AGENTS.md 和 skills 目錄我強(qiáng)烈不建議這么做。全局安裝的邏輯和“先裝操作系統(tǒng)再裝軟件”一樣。superpowers 的基礎(chǔ)技能里有很多是與具體項(xiàng)目無關(guān)的通用能力比如規(guī)范的 git commit 信息生成、自動(dòng)化單元測(cè)試的骨架搭建、代碼重構(gòu)步驟的標(biāo)準(zhǔn)化流程。這些能力應(yīng)該放在用戶級(jí)別的作用域下讓所有項(xiàng)目都能繼承。項(xiàng)目級(jí)配置的職責(zé)是“覆蓋”和“補(bǔ)充”而不是“從零搭建”。你總不想每拉一個(gè)新倉(cāng)庫(kù)就把整套技能復(fù)制一遍也不能接受不同項(xiàng)目里 Agent 的行為習(xí)慣五花八門。先全局安裝項(xiàng)目?jī)?nèi)做的只是引用和微調(diào)這才是可維護(hù)的做法。2.3 說清楚它對(duì) Codex CLI 做了什么、沒做什么我得把邊界講清楚免得有人期望過高。superpowers 沒有“增強(qiáng)模型智能”這種魔法。它做的三件事很樸素第一把任務(wù)拆解的思考過程固化在指令文件里讓 Agent 每次動(dòng)手前都按固定框架分析第二把高頻操作的完整步驟做成可復(fù)用的命令比如“給這個(gè)模塊補(bǔ)測(cè)試全覆蓋”就是一條命令第三把項(xiàng)目上下文、技術(shù)棧約束、代碼風(fēng)格偏好集中管理讓 Agent 在不同會(huì)話之間保持一致性。模型本身的邏輯推理能力不會(huì)因?yàn)檠b了這套東西就提升但你給它的“工作環(huán)境”變得更完整了它的輸出下限會(huì)明顯抬高。對(duì)我這種靠 Agent 處理大量重復(fù)模式的開發(fā)場(chǎng)景來說下限比上限重要得多。3. 完整安裝步驟與初始化配置3.1 安裝 Codex CLI 與準(zhǔn)備目錄結(jié)構(gòu)如果你還沒裝 Codex CLI打開終端直接執(zhí)行npm install -g openai/codex codex --version這一步正常的話你會(huì)看到版本號(hào)輸出。然后確認(rèn)配置文件目錄存在ls ~/.codex默認(rèn)情況下Codex CLI 的全局配置目錄就在用戶主目錄下的 .codex 文件夾里。如果看不到這個(gè)目錄就先執(zhí)行一次codex login讓它自動(dòng)創(chuàng)建。接著把 superpowers 克隆到本地git clone https://github.com/your-source/superpowers.git ~/.superpowers這里的路徑你可以自行調(diào)整但后面配置里會(huì)用到建議保持穩(wěn)定。我見過有人把技能庫(kù)放到項(xiàng)目目錄內(nèi)結(jié)果切項(xiàng)目就忘非常不建議。3.2 初始化核心配置文件superpowers 初始化最關(guān)鍵的一步是生成一份全局的 AGENTS.md 文件到 Codex CLI 的配置目錄里。這個(gè)文件相當(dāng)于 Agent 的“崗位說明書”它定義了基礎(chǔ)工作準(zhǔn)則比如“在不清楚需求時(shí)先提問不要猜”、“改完代碼必須跑干凈測(cè)試”、“提交說明按約定格式輸出”。我在安裝后的第一件事就是把這份全局 AGENTS.md 手工讀一遍而不是直接信任模板。因?yàn)檫@份文件直接決定了 Agent 后續(xù)所有行為模板里的任何一條規(guī)則你不同意都要在初始化之后立刻改掉。否則你會(huì)在未來某一天發(fā)現(xiàn) Agent 按照某個(gè)你并不認(rèn)可的規(guī)范工作而這規(guī)范源頭就是這份被忽略的文件。配置完成后驗(yàn)證一下codex --help如果你的版本支持 custom commandshelp 輸出里會(huì)看到相關(guān)說明。然后隨便跑一次codex exec 列出當(dāng)前目錄結(jié)構(gòu)確認(rèn) Agent 能正常響應(yīng)同時(shí)觀察它是否加載了全局配置文件。這一步?jīng)]有報(bào)錯(cuò)說明底座通了。3.3 在項(xiàng)目中啟用 superpowers 的最小步驟項(xiàng)目級(jí)啟用不需要復(fù)制整個(gè)技能庫(kù)通常只需要兩樣?xùn)|西。第一在項(xiàng)目根目錄放一份精簡(jiǎn)的 AGENTS.md開頭用引用句或明確聲明導(dǎo)入全局技能規(guī)則。第二建立你自己的 skills 目錄存放項(xiàng)目特有的技能文件。這個(gè)目錄的結(jié)構(gòu)我下一節(jié)展開講這里先說明為什么需要它全局技能是“通識(shí)”項(xiàng)目技能才是“私教”。比如你在一個(gè) Java Spring Boot 倉(cāng)庫(kù)里全局技能負(fù)責(zé)“怎么寫規(guī)范的 commit message”項(xiàng)目技能負(fù)責(zé)“新增一個(gè)帶完整測(cè)試的 REST 接口應(yīng)該按什么步驟走”。后者在不同項(xiàng)目里差異極大沒道理放在全局。我自己的做法是初始化之后先做一次“空跑驗(yàn)證”選一個(gè)很小的重構(gòu)任務(wù)讓 Agent 獨(dú)立完成然后檢查它的執(zhí)行軌跡。如果它表現(xiàn)出的行為模式和你期望的一致說明配置生效了如果不一致優(yōu)先檢查 AGENTS.md 是否被正確加載而不是急著加更多指令。4. superpowers 的原理拆解AGENTS.md、技能文件與 slash command4.1 AGENTS.md 的分層設(shè)計(jì)與行為約束機(jī)制AGENTS.md 是一種事實(shí)上的 Agent 指令標(biāo)準(zhǔn)。它不是 superpowers 發(fā)明的但 superpowers 把它的用法推到了更細(xì)的粒度。在我的配置里全局 AGENTS.md 至少覆蓋五類內(nèi)容基礎(chǔ)行為準(zhǔn)則、代碼風(fēng)格偏好、工具使用約定、任務(wù)拆解框架、以及錯(cuò)誤恢復(fù)策略。項(xiàng)目級(jí) AGENTS.md 則更聚焦通常包含技術(shù)棧清單、目錄結(jié)構(gòu)說明、常用命令表、以及團(tuán)隊(duì)特有的代碼規(guī)范。關(guān)鍵點(diǎn)是層級(jí)之間的覆蓋關(guān)系。全局說“所有提交信息必須遵循 Conventional Commits”項(xiàng)目級(jí)如果沒寫就按全局規(guī)則執(zhí)行項(xiàng)目級(jí)如果額外聲明“commit 的 scope 必須包含模塊名”那它會(huì)在全局規(guī)則之上疊加約束。這種精細(xì)的覆蓋機(jī)制靠純對(duì)話提示詞是實(shí)現(xiàn)不了的因?yàn)樘崾驹~在每次會(huì)話里都會(huì)被遺忘而 AGENTS.md 是每次會(huì)話都被加載的固定上下文。4.2 技能文件的結(jié)構(gòu)前置檢查、執(zhí)行步驟、后置驗(yàn)收superpowers 的核心資產(chǎn)是技能文件。一個(gè)技能文件不是簡(jiǎn)單的“指令提示詞”它是一份結(jié)構(gòu)化的操作流程通常包括三個(gè)部分。前置檢查記錄執(zhí)行前必須確認(rèn)的信息當(dāng)前分支是否干凈、相關(guān)測(cè)試基線是否通過、依賴是否安裝完整。執(zhí)行步驟定義按順序要做的操作每步盡可能具體。后置驗(yàn)收則列出任務(wù)完成前必須滿足的條件測(cè)試覆蓋率數(shù)字是否達(dá)標(biāo)、代碼格式檢查是否通過、有沒有留下未清理的臨時(shí)文件。這三個(gè)部分的價(jià)值在于它們把一個(gè)模糊的指令“幫忙加個(gè)配置項(xiàng)”變成了一條可執(zhí)行的流水線。Agent 在動(dòng)手之前先檢查前置條件執(zhí)行中按步驟推進(jìn)完成后自我驗(yàn)收。這比單純告訴它“好好干”靠譜得多因?yàn)椤昂煤酶伞睕]有驗(yàn)收標(biāo)準(zhǔn)。我給這套結(jié)構(gòu)做個(gè)類比普通提示詞是請(qǐng)了個(gè)自由職業(yè)者你說了需求他自由發(fā)揮技能文件是給了這個(gè)自由職業(yè)者一份詳細(xì)的項(xiàng)目章程、檢查表、驗(yàn)收清單。同樣的能力流程化管理之后產(chǎn)出穩(wěn)定性天差地別。4.3 自定義命令的注冊(cè)與調(diào)用如果你用過 Codex CLI 的 flexible mode你就知道 slash command 是它的核心交互方式。superpowers 的很多能力都封裝成自定義命令注冊(cè)方式是在配置目錄里放置對(duì)應(yīng)的命令描述文件。比如我注冊(cè)過一條review命令效果是讓 Agent 按我的代碼審查清單逐項(xiàng)檢查本次改動(dòng)輸出表格化的問題列表并對(duì)每個(gè)問題給出嚴(yán)重級(jí)別和建議修改方式。注冊(cè)后在終端里敲/review就能觸發(fā)不再需要輸入任何復(fù)雜的提示詞。slash command 的好處是“固定入口可變參數(shù)”。固定入口降低了記憶成本你不需要記住那條又長(zhǎng)又繞的提示詞可變參數(shù)則保留靈活性你可以讓命令接收具體文件名、模塊路徑等參數(shù)。不過這里有個(gè)容易踩的坑如果你在多個(gè)項(xiàng)目之間切換項(xiàng)目級(jí)注冊(cè)的命令不會(huì)自動(dòng)出現(xiàn)在全局命令列表里。Codex CLI 的默認(rèn)行為里項(xiàng)目級(jí)命令需要你在項(xiàng)目目錄內(nèi)才會(huì)被識(shí)別。這個(gè)問題排錯(cuò)了很久才搞清楚后面常見問題里會(huì)詳細(xì)說。4.4 為什么說它是“給 Agent 建肌肉記憶”我用了大半年的心得就一句話superpowers 的本質(zhì)是在給 Agent 建肌肉記憶。模型從訓(xùn)練角度講是“無記憶”的每一次對(duì)話都是從零開始。但當(dāng)你把高頻操作固化成技能文件把項(xiàng)目規(guī)范沉淀在 AGENTS.md 里把常用工作流封裝成 slash commandAgent 的每一次啟動(dòng)都不再是“重新認(rèn)識(shí)世界”而是“加載好的一套工作習(xí)慣”。這套工作習(xí)慣就是它的肌肉記憶。肌肉記憶的建立是有成本的維護(hù)成本和收益。你寫一個(gè)高質(zhì)量技能文件花半小時(shí)未來每一次觸發(fā)這個(gè)技能都省掉十五分鐘重復(fù)引導(dǎo)的時(shí)間。技能庫(kù)積累到一定數(shù)量后這種時(shí)間回報(bào)是指數(shù)級(jí)的。5. 讓 superpowers 在 Java 工程里發(fā)揮價(jià)值5.1 先想清楚 Java 場(chǎng)景的特殊訴求如果你是 Java 開發(fā)者沒有比這更吃上下文的技術(shù)棧了。Java 工程的痛點(diǎn)很集中模塊邊界清晰但依賴關(guān)系復(fù)雜、構(gòu)建工具鏈相對(duì)固定但配置繁瑣、測(cè)試框架統(tǒng)一但編寫模板代碼量大。通用技能當(dāng)然能覆蓋一部分場(chǎng)景比如“先生成測(cè)試再實(shí)現(xiàn)功能”的 TDD 流程但 Java 場(chǎng)景還需要更細(xì)顆粒度的支撐。比如 Spring Boot 項(xiàng)目里新加一個(gè)接口需要同步寫 Controller、Service、Repository、DTO、異常處理、單元測(cè)試、集成測(cè)試哪個(gè)文件落到哪個(gè)包下都有強(qiáng)約定。這對(duì) Agent 來說是巨大的上下文負(fù)擔(dān)你不可能每次都在對(duì)話里把這些約定描述一遍。superpowers 的解法是把這些約定寫在項(xiàng)目級(jí)技能文件里讓 Agent 每次執(zhí)行“新增接口”這類任務(wù)時(shí)自動(dòng)加載。5.2 定制一個(gè) Java 技能文件的完整示例以“新增 REST 接口”為例我寫了一個(gè)名為add-rest-endpoint的技能文件內(nèi)容包括以下步驟。第一步是確認(rèn)當(dāng)前模塊的包路徑讀取現(xiàn)有 Controller 的代碼風(fēng)格確定返回類型是 ResponseEntity 還是自定義 Result 封裝。第二步是列出這個(gè)接口需要觸達(dá)的 Service 方法是否存在不存在就先定義接口和實(shí)現(xiàn)。第三步是補(bǔ)測(cè)試單元測(cè)試覆蓋 Service 層的業(yè)務(wù)邏輯集成測(cè)試覆蓋 Controller 層的路由和序列化。第四步是運(yùn)行該模塊的 Maven 測(cè)試命令確認(rèn)全綠后給出提交說明模板。這個(gè)技能文件寫完后我在對(duì)話里輸入“給用戶模塊新增一個(gè)改昵稱的接口”Agent 會(huì)自動(dòng)觸發(fā)這個(gè)流程完全不靠我額外解釋任何項(xiàng)目約定。結(jié)果可能是它生成的代碼并非完美無缺但結(jié)構(gòu)和步驟永遠(yuǎn)是對(duì)的差別只在我做 review 時(shí)修多少細(xì)節(jié)。5.3 Java 項(xiàng)目里我實(shí)際用的三個(gè)高頻命令除了上面的接口技能我還有三個(gè)高頻命令。/run-mvn-tests它不只是執(zhí)行測(cè)試命令而是先檢查 maven wrapper 是否存在再用正確的方式觸發(fā)指定模塊的測(cè)試最后把失敗用例按包名分組輸出。/generate-repository是數(shù)據(jù)訪問層的生成器它讀取實(shí)體類定義按項(xiàng)目里的持久層框架生成對(duì)應(yīng) Repository 接口和基礎(chǔ)查詢方法。/refactor-module是用來處理重構(gòu)任務(wù)的核心是讓 Agent 先列出受影響的調(diào)用方、再逐層修改、最后跑全量回歸。這三個(gè)命令解決的是 Java 開發(fā)里出現(xiàn)頻率最高的三類需求。它們的共同特點(diǎn)是任務(wù)步驟明確、驗(yàn)收標(biāo)準(zhǔn)清晰、重復(fù)度高。正因如此它們才值得被固化成技能而不是每次重新向 Agent 解釋一遍。5.4 多語(yǔ)言混用項(xiàng)目里的技能切換策略實(shí)際項(xiàng)目里很少是純 Java。前端 TypeScript、基礎(chǔ)設(shè)施的 shell 腳本、數(shù)據(jù)同步的 Python 任務(wù)各占一部分。如果全局技能只針對(duì) Java 定制那 Agent 在處理前端代碼時(shí)就會(huì)表現(xiàn)平庸。我的經(jīng)驗(yàn)是在項(xiàng)目級(jí) AGENTS.md 里明確聲明“本倉(cāng)庫(kù)前端使用 TypeScript Vue后端使用 Java 17 Spring Boot腳本使用 Python 3.10”然后在 skills 目錄下按技術(shù)棧分子目錄。比如skills/java/下面放 Java 相關(guān)技能skills/ts/下面放前端技能。這樣 Agent 在讀取文件時(shí)能按目錄結(jié)構(gòu)快速定位適用規(guī)則不會(huì)出現(xiàn)用 Java 的規(guī)范去審查 TypeScript 代碼這種錯(cuò)位。這個(gè)“按棧隔離”的策略在混合倉(cāng)庫(kù)里非常管用。它避免了全局技能文件越長(zhǎng)越臃腫、最后失去約束力的窘境。6. 日常使用的工作流與配合技巧6.1 任務(wù)啟動(dòng)前的高效引導(dǎo)模板superpowers 不是萬能的它給你提供了完整的能力框架但每次任務(wù)的第一步引導(dǎo)質(zhì)量仍然決定后續(xù)走向。我存了一套自己打磨過的任務(wù)引導(dǎo)模板核心結(jié)構(gòu)是任務(wù)目標(biāo)一句話明確約束條件比如“不改動(dòng)公共接口簽名”“不引入新的第三方依賴”指定影響范圍比如“只涉及 user 模塊其他模塊不允許修改”給出驗(yàn)收標(biāo)準(zhǔn)比如“所有測(cè)試必須通過且新增用例覆蓋分支”。這套模板我在每個(gè)項(xiàng)目里都放了一份叫task-brief.md任務(wù)開始前把內(nèi)容填充好丟給 Agent。這么做表面看多了幾步實(shí)際上讓后續(xù)交互時(shí)間直接砍半。你要理解一個(gè)原則Agent 在信息不足時(shí)的默認(rèn)行為是猜測(cè)你給它的上下文越精確它的輸出就越接近可交付狀態(tài)。6.2 如何把 superpowers 和 WorBuddy 這類工具配合使用有人問過 WorBuddy 這類工具和 superpowers 是什么關(guān)系。我的理解是WorBuddy 這類偏任務(wù)編排的工管工具負(fù)責(zé)的是流程視圖它管的是“我們要做哪些任務(wù)、任務(wù)的依賴關(guān)系是什么、誰(shuí)負(fù)責(zé)什么”而 superpowers 解決的是“具體一個(gè)任務(wù)進(jìn)來之后Agent 應(yīng)該怎么高質(zhì)量完成”。這兩者天然互補(bǔ)。在我的工作流里WorBuddy 層面定義里程碑和任務(wù)看板每個(gè)任務(wù)分配到人或者分配到 Agent。當(dāng)任務(wù)真正落到 Agent 執(zhí)行時(shí)superpowers 的技能庫(kù)和全局指令就發(fā)揮作用。你可以說 WorBuddy 是“調(diào)度層”superpowers 是“執(zhí)行層”兩者配合之后管理者和執(zhí)行者都不迷茫。6.3 會(huì)話中途切換項(xiàng)目上下文的方法實(shí)際開發(fā)里經(jīng)常遇到的情況是同一個(gè)終端會(huì)話里先改完 Java 后端馬上又要處理前端問題。如果你不告訴 Agent 上下文已經(jīng)切換它極大概率還在用后端的項(xiàng)目管理規(guī)范來寫前端代碼。我的做法是在項(xiàng)目根目錄建一個(gè).context文件里面只寫三行當(dāng)前項(xiàng)目名稱、技術(shù)棧摘要、生效的規(guī)范文件路徑。每次切換到當(dāng)前目錄時(shí)我會(huì)先讓 Agent 讀這個(gè)文件再開始新任務(wù)。這個(gè)小動(dòng)作比在對(duì)話里反復(fù)解釋“現(xiàn)在是前端項(xiàng)目”可靠得多因?yàn)槲募浅志没腁gent 每次都讀到同一份說明。6.4 團(tuán)隊(duì)協(xié)作時(shí)如何統(tǒng)一技能庫(kù)版本如果你和團(tuán)隊(duì)一起用這套框架最大的問題一定是版本不統(tǒng)一。你更新了技能文件同事還在用老版Agent 在兩個(gè)人手里表現(xiàn)完全不一樣review 代碼的時(shí)候沖突不斷。解法不復(fù)雜技能庫(kù)用 git 管理團(tuán)隊(duì)內(nèi)部維護(hù)一個(gè)穩(wěn)定的主分支每次改動(dòng)走 merge request合并后所有人各自拉取。CI 環(huán)節(jié)加一個(gè)檢查腳本跑一遍技能庫(kù)里的語(yǔ)法校驗(yàn)和目錄結(jié)構(gòu)完整性檢查避免有人把技能文件格式寫錯(cuò)推上來影響所有人。我建議每個(gè)團(tuán)隊(duì)指定一個(gè)人當(dāng)技能庫(kù)的“維護(hù)者”專門負(fù)責(zé)合并請(qǐng)求、解決沖突、更新文檔。不是技術(shù)難度大而是這件事需要持續(xù)的關(guān)注度分散給所有人最后就是沒人管。7. 常見問題與排查技巧實(shí)錄7.1 命令被識(shí)別但沒有任何響應(yīng)這是最常碰到的問題注冊(cè)了/review命令輸入之后 Agent 像沒看到一樣既不報(bào)錯(cuò)也不執(zhí)行。排這個(gè)問題先確認(rèn)命令文件的位置對(duì)不對(duì)。全局命令應(yīng)該在~/.codex/commands目錄項(xiàng)目級(jí)命令在.codex/commands目錄。很多人直接寫在項(xiàng)目根目錄下Codex CLI 根本不去那里找。其次要看命令文件的前綴格式通常文件名就是命令名如果文件名帶空格或者包含特殊字符解析器會(huì)忽略。最后檢查命令描述里的觸發(fā)器參數(shù)是否和調(diào)用方式匹配比如你定義的時(shí)候要求帶參數(shù)調(diào)用時(shí)沒帶Agent 可能直接放棄執(zhí)行。7.2 AGENTS.md 被修改后不生效還是舊行為這個(gè)坑很隱蔽。Codex CLI 對(duì) AGENTS.md 的加載可能帶有緩存它不會(huì)每次任務(wù)都去重新讀取文件內(nèi)容。你修改了規(guī)則但 Agent 表現(xiàn)的還是舊規(guī)則下的行為很容易讓人誤以為“改錯(cuò)文件了”。我的經(jīng)驗(yàn)是修改后開一個(gè)新會(huì)話驗(yàn)證不要在當(dāng)前會(huì)話里繼續(xù)測(cè)試因?yàn)楫?dāng)前會(huì)話的上下文已經(jīng)攜帶了舊指令。如果新會(huì)話里仍然不生效檢查文件編碼格式有 BOM 頭或者非 UTF-8 編碼的情況下解析器有可能讀取失敗但不報(bào)錯(cuò)。7.3 技能文件在不同項(xiàng)目間串用技能串用是另一個(gè)高頻問題尤其在你有多個(gè)項(xiàng)目共用全局技能的前提下。你為 A 項(xiàng)目寫的接口規(guī)范被 Agent 用到了 B 項(xiàng)目的接口評(píng)審里結(jié)果報(bào)告里全是無關(guān)建議。根源在于技能文件的匹配機(jī)制。Codex CLI 通常根據(jù)命令名或文件路徑來調(diào)用技能但你在對(duì)話里描述任務(wù)時(shí)如果任務(wù)描述和多個(gè)技能文件都能語(yǔ)義匹配Agent 可能選錯(cuò)。解決辦法是項(xiàng)目級(jí)命令命名時(shí)加上項(xiàng)目前綴比如user-module-add-endpoint同時(shí)在 AGENTS.md 里明確說明“當(dāng)前項(xiàng)目只允許使用帶 user 前綴的項(xiàng)目級(jí)命令”。7.4 參數(shù)傳遞中的引號(hào)與空格問題slash command 的參數(shù)解析對(duì)特殊字符的容忍度很低。我踩過最深的坑是傳文件路徑參數(shù)時(shí)路徑里有空格命令被拆成了兩段Agent 跑到一半找不到文件。處理方式很簡(jiǎn)單命令文件里定義參數(shù)接收邏輯時(shí)顯式處理引號(hào)包裹。調(diào)用側(cè)也養(yǎng)成習(xí)慣帶空格的參數(shù)值一律用雙引號(hào)包起來。如果你在命令文件里寫的是 shell 腳本記得對(duì)$*做一層嚴(yán)格解析別直接拼接進(jìn)后續(xù)命令。7.5 快速診斷清單最后給一張排查清單遇到問題時(shí)按順序過一遍大部分問題都能解決。命令文件路徑是否位于 Codex CLI 期望的目錄下命令文件名是否符合命名規(guī)則無空格無特殊字符AGENTS.md 是否采用 UTF-8 無 BOM 編碼是否在修改文件后開了一個(gè)全新會(huì)話命令行參數(shù)是否用雙引號(hào)包裹完整全局技能和項(xiàng)目技能是否存在命名沖突Codex CLI 和 superpowers 版本是否匹配是否都升級(jí)到了最新。按這條清單走完還沒解決的基本就是技能文件內(nèi)部的邏輯問題需要你把文件內(nèi)容逐段讀一遍確認(rèn)流程步驟里沒有寫死某條并不存在的本地路徑。8. 寫在最后的一些個(gè)人經(jīng)驗(yàn)用了這么久 superpowers我最直觀的感受是它把我從“反復(fù)向 Agent 解釋我的項(xiàng)目”這件事里解放出來了。以前開個(gè)新會(huì)話要先花五分鐘粘貼項(xiàng)目說明、技術(shù)棧、代碼規(guī)范有時(shí)還要附帶幾條示例代碼就為了讓它寫出風(fēng)格一致的代碼。現(xiàn)在這些信息全部沉淀在配置文件和技能庫(kù)里一個(gè)會(huì)話打開Agent 自己就知道該按什么規(guī)矩干活。如果你剛開始接觸這套東西我的建議很明確先不要貪多不要一次性把所有技能裝滿。從一條命令開始選擇一個(gè)你每天都會(huì)做的重復(fù)任務(wù)把它的流程仔細(xì)寫成一個(gè)技能文件用半個(gè)月然后評(píng)估收益。確認(rèn)有價(jià)值再逐步加第二個(gè)、第三個(gè)。技能庫(kù)的核心不是數(shù)量是每條技能都能穩(wěn)定高質(zhì)量地輸出。我見過有人一次性導(dǎo)入了上百個(gè)技能結(jié)果 Agent 在任務(wù)選擇上頻繁混亂最后退回去只留了十幾個(gè)精品的反而順暢。還有一點(diǎn)要分享的這個(gè)框架的價(jià)值邊界很清楚。它優(yōu)化的是“工具使用方式”不是“決策能力”。當(dāng)你在做一個(gè)業(yè)務(wù)解決方案的架構(gòu)決策時(shí)superpowers 幫不了你那還是得靠你自己的判斷。但當(dāng)你確定了方案、明確了步驟它能讓 Agent 以極高的穩(wěn)定性和一致性把方案落地成代碼這種“執(zhí)行層面的確定性”對(duì)我來說已經(jīng)值回所有安裝成本。最后給個(gè)小技巧可以定期翻一下技能庫(kù)把那些已經(jīng)很久沒被觸發(fā)過的技能刪掉。技能和代碼一樣不維護(hù)就會(huì)過期。倉(cāng)庫(kù)里的技術(shù)棧變了命令變了舊技能描述里的路徑全是錯(cuò)的留在那里只會(huì)增加 Agent 選擇時(shí)的噪音。精簡(jiǎn)過三輪技能庫(kù)之后我明顯感覺觸發(fā)準(zhǔn)確率上了一個(gè)臺(tái)階。