我最早接觸 Codex CLI 的時(shí)候感覺這東西確實(shí)比直接開個(gè)網(wǎng)頁對(duì)話框強(qiáng)不少但你用得越久越會(huì)發(fā)現(xiàn)一個(gè)問題它每次開始干活都像失憶了一樣明明上次已經(jīng)調(diào)教好的編碼風(fēng)格、測(cè)試規(guī)范、項(xiàng)目約束下一次對(duì)話里它又忘了又得重新把上下文喂一遍。直到我試了 GitHub 上那套叫 superpowers 的開源技能包才意識(shí)到問題的本質(zhì)不在模型能力而在工作流組織方式。這篇文章我就把自己從零開始安裝、配置、實(shí)際用它寫 Java 項(xiàng)目的完整過程寫出來包括它內(nèi)部的文件結(jié)構(gòu)和觸發(fā)邏輯是怎么設(shè)計(jì)的以及我踩過的那些坑。這套東西適合誰適合已經(jīng)在用 Codex CLI、或者打算深度使用 AI 編程助手的開發(fā)者。如果你只是偶爾讓 AI 寫個(gè)爬蟲腳本那可能用不太上但如果你是想讓 AI 真正參與到日常項(xiàng)目開發(fā)里希望它每次都能按同樣的思路處理問題、復(fù)用你沉淀下來的代碼規(guī)范那 superpowers 這套東西幾乎就是你現(xiàn)在缺的那塊拼圖。1. 項(xiàng)目定位與核心設(shè)計(jì)思路拆解1.1 superpowers 到底解決了什么問題先說個(gè)背景。OpenAI 的 Codex CLI 是個(gè)跑在終端里的編程代理你給它一個(gè)任務(wù)它自己會(huì)計(jì)劃、寫代碼、跑測(cè)試、看報(bào)錯(cuò)、再改代碼反復(fù)迭代直到搞定。這個(gè)形態(tài)聽起來很理想但實(shí)際用起來有個(gè)特別別扭的地方每一次會(huì)話都是獨(dú)立的。你上次告訴它“單元測(cè)試要用 JUnit 5 不要用 JUnit 4”“重構(gòu)之前先跑一遍全量測(cè)試”“遇到編譯錯(cuò)誤先讀日志再改代碼”這些東西在下次會(huì)話里全都?xì)w零了。AI 編程助手缺的不是推理能力缺的是“穩(wěn)定的工作習(xí)慣”。你可以把 Codex CLI 理解成一個(gè)能力很強(qiáng)但性格像金魚的新同事你每次都要重新教他一遍做事流程。superpowers 就是針對(duì)這個(gè)問題誕生的它把“如何做計(jì)劃”“如何調(diào)試”“如何寫代碼”“如何排查問題”這些方法論固化成了可復(fù)用的技能文件skills放進(jìn) Codex 的配置目錄里讓 AI 在每次會(huì)話中都能自動(dòng)加載這些技能。這個(gè)項(xiàng)目原本是自動(dòng)化交互小說里的世界觀設(shè)定后來作者把它移植成了 Codex CLI 的插件式技能庫。里面不止有硬核的調(diào)試、重構(gòu)、性能優(yōu)化技能還保留了小說世界觀里的一些理念型技能比如“正念”“感恩”“非暴力溝通”這些。聽起來有點(diǎn)玄乎但實(shí)際用下來你會(huì)發(fā)現(xiàn)這些技能是在約束 AI 的行為模式幫它建立一套穩(wěn)定的做事原則效果比單純堆提示詞強(qiáng)太多。1.2 技能庫的分層結(jié)構(gòu)與觸發(fā)機(jī)制superpowers 的技能不是一堆亂七八糟的 prompt 文件堆在一起它的組織方式是分層的這跟我們?cè)诠こ汤镒瞿K化設(shè)計(jì)是一個(gè)道理。頂層是規(guī)則型技能定義的是 AI 的基本行事準(zhǔn)則比如“在行動(dòng)前先思考”“使用系統(tǒng)化方法解決問題”“分清事實(shí)與假設(shè)”這類元認(rèn)知層面的約束。中間層是核心協(xié)作技能包括制定計(jì)劃、分解任務(wù)、漸進(jìn)式總結(jié)這些跨場(chǎng)景通用的能力。再往下才是具體的技術(shù)技能像寫代碼、調(diào)試、代碼復(fù)現(xiàn)、瀏覽器操作、性能優(yōu)化等等。最后是工作流技能把多個(gè)子技能串聯(lián)起來形成完整的執(zhí)行流程。這個(gè)分層最大的價(jià)值在于組合性。AI 接到一個(gè)任務(wù)后不是簡(jiǎn)單套用某一個(gè)技能而是會(huì)根據(jù)任務(wù)類型動(dòng)態(tài)組合多個(gè)技能。比如讓它修一個(gè) bug它會(huì)先調(diào)用“制定計(jì)劃”技能拆解任務(wù)再調(diào)用“調(diào)試”技能定位問題修復(fù)時(shí)調(diào)用“寫代碼”技能最后用“遵循規(guī)范”技能檢查代碼風(fēng)格。每一層技能各司其職又可以通過前置條件互相引用形成一個(gè)完整的技能調(diào)用鏈。觸發(fā)機(jī)制也很有意思。你不需要手動(dòng)告訴 AI “現(xiàn)在請(qǐng)使用制定計(jì)劃技能”技能文件里的前置條件描述會(huì)讓 AI 在遇到對(duì)應(yīng)場(chǎng)景時(shí)自動(dòng)調(diào)用。這個(gè)原理類似于我們給 AI 準(zhǔn)備了一堆工具每個(gè)工具描述了“當(dāng)出現(xiàn)什么情況時(shí)應(yīng)該使用我”AI 根據(jù)當(dāng)前的上下文自己判斷是否觸發(fā)。實(shí)際用下來只要把技能文件放到位AI 的響應(yīng)邏輯確實(shí)會(huì)發(fā)生明顯改變它在動(dòng)手之前會(huì)先輸出思考過程和計(jì)劃不再像以前那樣直接甩代碼。2. 環(huán)境準(zhǔn)備與安裝全流程實(shí)錄2.1 安裝 Codex CLI 并完成認(rèn)證superpowers 依賴 Codex CLI 運(yùn)行所以第一步是先把 Codex 裝好。如果你之前已經(jīng)裝過可以直接跳到目錄配置部分但如果你是從零開始這里我把完整步驟寫一遍。# 安裝 Codex CLI我用的是 npm 方式 npm install -g openai/codex安裝完成后先驗(yàn)證一下版本確保裝的是支持 skills 目錄的版本。我當(dāng)前用的是 0.37 版本這之后的版本基本都支持~/.codex/skills目錄。codex --version然后是登錄認(rèn)證。Codex CLI 的認(rèn)證方式有幾種ChatGPT 登錄、API Key、本地配置都行。我因?yàn)槿粘ｉ_發(fā)本來就要調(diào) API所以直接用了 API Key 方式。需要注意的是不同認(rèn)證方式影響的是計(jì)費(fèi)渠道和可用模型不影響技能系統(tǒng)的工作邏輯。# 建議第一次直接運(yùn)行 codex 進(jìn)入交互界面 codex首次運(yùn)行會(huì)提示你選擇認(rèn)證方式ChatGPT 登錄或者 API Key 按提示操作就可以了。裝好之后先隨便給它發(fā)一條消息測(cè)一下連通性確認(rèn)能正常返回再繼續(xù)下一步。2.2 拉取 superpowers 倉庫并部署技能文件接下來把 superpowers 倉庫拉下來。這個(gè)倉庫是開源的直接 git clone 即可。git clone https://github.com/obra/superpowers.git如果你 GitHub 拉取速度不太理想也可以直接去 Releases 頁面下載對(duì)應(yīng)版本的壓縮包。不過我個(gè)人建議用 git clone之后想更新技能庫可以直接git pull。拉下來后重點(diǎn)看兩個(gè)目錄skills目錄放的是所有技能文件scripts目錄里是構(gòu)建腳本。部署的核心操作就是把skills目錄里的內(nèi)容放到 Codex 的技能目錄里去。如果你之前沒用過 superpowers本地可能還沒有這個(gè)目錄需要手動(dòng)創(chuàng)建。# 創(chuàng)建技能目錄 mkdir -p ~/.codex/skills # 把 superpowers 倉庫里的 skills 內(nèi)容復(fù)制進(jìn)去 # 注意是把內(nèi)容復(fù)制進(jìn)去不是整個(gè)文件夾塞進(jìn)去 cp -r superpowers/skills/* ~/.codex/skills/這里有個(gè)細(xì)節(jié)必須提醒copypaste 之后要檢查目錄結(jié)構(gòu)確保~/.codex/skills下面直接就是各個(gè)技能文件夾比如writing、debugging、collaboration這些而不能多套了一層skills/skills。我第一次部署的時(shí)候就犯了這個(gè)錯(cuò)誤結(jié)果 Codex 一個(gè)技能都沒識(shí)別到。檢查完結(jié)構(gòu)后我還需要把你的項(xiàng)目級(jí)配置也處理一下。superpowers 的作者會(huì)在項(xiàng)目根目錄生成一個(gè)AGENTS.md文件里面寫了 Codex 應(yīng)該如何配合這套技能系統(tǒng)工作。我的做法是把關(guān)鍵內(nèi)容合并進(jìn)自己的項(xiàng)目說明文件里避免和已有的項(xiàng)目配置沖突。這個(gè)后面在常見問題部分我會(huì)詳細(xì)說。2.3 驗(yàn)證技能是否被成功識(shí)別部署完成后怎么確定技能真的裝上了打開 Codex CLI隨便問一句“你現(xiàn)在能用哪些技能”如果識(shí)別正常它會(huì)列出一堆技能名稱包括寫代碼、調(diào)試、規(guī)劃、重構(gòu)等等。如果它回答“我沒有技能系統(tǒng)”或者列不出來那基本就是目錄結(jié)構(gòu)出了問題。還有一種驗(yàn)證方式就是看日志。Codex CLI 啟動(dòng)的時(shí)候會(huì)掃描技能目錄如果目錄路徑不對(duì)日志里會(huì)報(bào)告掃描失敗或者掃描結(jié)果為 0 項(xiàng)。我那次路徑錯(cuò)誤就是靠看日志發(fā)現(xiàn)的。目錄結(jié)構(gòu)驗(yàn)證無誤后還有一步初始化動(dòng)作讓 AI 建立“記憶文件”。superpowers 的技能系統(tǒng)里包含記憶機(jī)制AI 會(huì)在每次會(huì)話結(jié)束時(shí)把關(guān)鍵結(jié)論、項(xiàng)目約定寫入 memory 目錄。首次使用時(shí)你可以主動(dòng)讓它“請(qǐng)創(chuàng)建記憶文件并記錄當(dāng)前項(xiàng)目的技術(shù)棧和架構(gòu)約定”這一步相當(dāng)于給 AI 建立第一份項(xiàng)目檔案之后每個(gè)會(huì)話它都會(huì)自動(dòng)讀取這些記憶實(shí)現(xiàn)跨會(huì)話的上下文連續(xù)。3. 核心機(jī)制拆解技能文件到底怎么工作3.1 SKILL.md 的解析與編寫規(guī)范superpowers 里的每個(gè)技能都是一個(gè)目錄目錄里有一個(gè)SKILL.md文件外加一些輔助資源。這個(gè)SKILL.md的格式是 Markdown但頭部帶了 YAML frontmatter有點(diǎn)像我們寫博客文章或者 Jekyll 頁面時(shí)的配置頭。frontmatter 里的字段不多最關(guān)鍵的是name和description。name是技能的唯一標(biāo)識(shí)AI 靠這個(gè)來引用技能description是這個(gè)技能的“自我介紹”它描述了“什么時(shí)候應(yīng)該使用這個(gè)技能”。這個(gè) description 必須在開頭就寫清楚該技能適用的觸發(fā)場(chǎng)景。--- name: 調(diào)試問題 description: 當(dāng)代碼出現(xiàn)報(bào)錯(cuò)、測(cè)試失敗、程序異常時(shí)使用該技能定位問題根源并給出修復(fù)方案。 ---我看到很多人在自定義技能的時(shí)候不注意 description 的寫法寫得要么太籠統(tǒng)比如“用于調(diào)試”要么太具體只描述某一個(gè) bug。正確的寫法是描述“觸發(fā)條件”什么時(shí)候該用、用來解決什么類別的任務(wù)。因?yàn)?AI 是根據(jù)語義來匹配技能的description 寫得越精確AI 越能在合適的時(shí)機(jī)把技能調(diào)出來。SKILL.md 正文部分寫的是技能的執(zhí)行流程。superpowers 的正文往往是分段式結(jié)構(gòu)從核心原則、執(zhí)行步驟、到最后的效果校驗(yàn)層次分明。以寫代碼技能為例正文會(huì)先給出幾條核心原則比如“遵循現(xiàn)有代碼風(fēng)格”“擴(kuò)展而非重寫”然后列出具體步驟先讀需求文檔、再制定修改計(jì)劃、然后寫代碼、最后驗(yàn)證測(cè)試最后還要一個(gè)完成后自查的檢查表。這個(gè)結(jié)構(gòu)本質(zhì)上是在約束 AI 的思考路徑。3.2 子技能引用與技能組合機(jī)制superpowers 最有意思的設(shè)計(jì)是技能之間可以互相調(diào)用。一個(gè)技能文件的正文里可以寫“前置條件需要先完成計(jì)劃制定技能”這就等于讓 AI 在執(zhí)行本技能之前先去調(diào)用另一個(gè)技能。我舉個(gè)例子collaboration協(xié)作技能是一個(gè)頂層技能它的執(zhí)行流程里會(huì)要求 AI 使用“思考”技能來做深度分析、使用“計(jì)劃”技能來制定實(shí)施步驟、使用“進(jìn)度追蹤”技能來管理任務(wù)狀態(tài)。而每個(gè)被調(diào)用的子技能自身又可能有更細(xì)粒度的前置技能。這樣就形成了一棵技能調(diào)用樹。這套機(jī)制的價(jià)值在于你不用把每個(gè)技能寫成一個(gè)包含所有步驟的巨型 prompt而是拆成細(xì)粒度的小技能再在需要的時(shí)候組合。真正的 AI 編程工作流跟我們?cè)诖a里做函數(shù)抽象一樣把公共邏輯抽出來復(fù)用。如果你自己也想往 superpowers 里添加自定義技能強(qiáng)烈建議遵循這個(gè)原則每個(gè)技能只做一件事但做得足夠深入通過前置條件和其他技能串聯(lián)。技能調(diào)用并不是強(qiáng)制的指令式調(diào)用而是建議式的。AI 讀到“前置條件需要先完成計(jì)劃制定技能”這句話會(huì)理解為在執(zhí)行當(dāng)前步驟前應(yīng)該先走完計(jì)劃技能但它也有一定的自主判斷空間。所以我個(gè)人的經(jīng)驗(yàn)是如果想要某個(gè)調(diào)用是絕對(duì)強(qiáng)制的就把話寫得更加絕對(duì)比如“不允許在制定書面的分步驟計(jì)劃之前開始編碼”效果比“建議先制定計(jì)劃”要明顯得多。3.3 起始工作流與記憶機(jī)制的價(jià)值superpowers 里還有一個(gè)starter工作流技能它相當(dāng)于整個(gè)技能系統(tǒng)的啟動(dòng)入口。每次 Codex 開啟新會(huì)話如果項(xiàng)目配好了這個(gè)工作流AI 會(huì)先執(zhí)行它再接收用戶的后續(xù)指令。這個(gè)啟動(dòng)過程包括讀取記憶文件、理解項(xiàng)目背景、檢查環(huán)境狀態(tài)、確認(rèn)目標(biāo)和約束最后才開始干活。這就像給 AI 立了一套“晨會(huì)制度”。以前每次新會(huì)話AI 都是被一個(gè)問題直接砸醒然后迷迷糊糊開始輸出代碼現(xiàn)在它先花一點(diǎn)時(shí)間把上下文拉齊確定自己知道項(xiàng)目是干嘛的、技術(shù)棧是什么、有沒有歷史約定再開始思考具體問題。實(shí)測(cè)下來這一步確實(shí)讓后續(xù)回答的準(zhǔn)確率高了不少至少不會(huì)再犯“把 Java 項(xiàng)目當(dāng)成 Python 項(xiàng)目來處理”這種低級(jí)錯(cuò)誤。記憶機(jī)制是我覺得最值得借鑒的設(shè)計(jì)。技能系統(tǒng)里有一個(gè)專門的記憶技能AI 會(huì)在會(huì)話結(jié)束時(shí)總結(jié)這次做完了什么、發(fā)現(xiàn)了什么問題、哪些約定需要長(zhǎng)期遵守并寫入記憶文件。下次新會(huì)話啟動(dòng)時(shí)AI 會(huì)自動(dòng)讀取這些記憶。這本質(zhì)上就是在給 AI 建立長(zhǎng)期記憶。你可以把它理解成 AI 版的變更日志changelog只不過記錄的不是代碼變更而是上下文和決策記錄。有一點(diǎn)需要注意記憶文件可能會(huì)在長(zhǎng)期使用中逐漸膨脹塞滿一堆過期的中間態(tài)信息。我自己會(huì)定期手動(dòng)清理一下記憶文件把已經(jīng)完成的項(xiàng)目和過時(shí)的決策刪除只保留當(dāng)前還需要遵守的約定。不然時(shí)間長(zhǎng)了AI 讀文件的速度變慢不說還可能被一些過時(shí)信息干擾判斷。4. 實(shí)戰(zhàn)記錄用 superpowers 驅(qū)動(dòng) Java 項(xiàng)目修復(fù)4.1 問題場(chǎng)景與初始調(diào)用光說不練沒有說服力。下面我用一個(gè)自己實(shí)際經(jīng)歷的場(chǎng)景完整走一遍 superpowers 的工作流程。當(dāng)時(shí)我在改一個(gè) Spring Boot 的庫存服務(wù)模塊遇到了一個(gè)典型的空指針問題。某些商品沒有設(shè)置默認(rèn)倉庫在查詢庫存時(shí)會(huì)直接拋 NPE。這是一個(gè)很常見的問題但如果直接讓 AI 修通常會(huì)得到一個(gè)“在調(diào)用處判空”的臨時(shí)補(bǔ)丁治標(biāo)不治本。我打開 Codex CLI給了它一個(gè)很簡(jiǎn)潔的指令“商品詳情接口現(xiàn)在會(huì)拋空指針異常幫我定位根因并徹底修復(fù)?！比绻菦]有配置技能系統(tǒng)的 Codex它大概率會(huì)直接開始翻代碼、找報(bào)錯(cuò)點(diǎn)、改兩行代碼完事。但在 superpowers 體系下它的響應(yīng)方式完全不一樣。它會(huì)先進(jìn)入起始工作流讀取項(xiàng)目記憶和倉庫結(jié)構(gòu)然后告訴你按照調(diào)試技能的流程先要復(fù)現(xiàn)問題再做根因分析。4.2 技能驅(qū)動(dòng)的完整排查與修復(fù)鏈路我記得當(dāng)時(shí)的會(huì)話過程大致是這樣的AI 先調(diào)用調(diào)試技能要求我提供完整的異常堆棧和復(fù)現(xiàn)步驟。我把棧信息貼給它之后它沒有馬上說“這里沒判空所以加個(gè)判斷”而是先做了一個(gè)假設(shè)列表列出了幾種可能的原因——實(shí)體類字段默認(rèn)值問題、查詢結(jié)果真的是空、映射層把 null 傳給了業(yè)務(wù)層、或者前端傳參本身就是空。然后它逐個(gè)驗(yàn)證這些假設(shè)。在驗(yàn)證過程中AI 使用了一個(gè)很關(guān)鍵的技能動(dòng)作向我要測(cè)試用例或者運(yùn)行測(cè)試。它自己在沙箱環(huán)境里寫了幾個(gè)單元測(cè)試來覆蓋“未設(shè)置默認(rèn)倉庫時(shí)查詢庫存”的分支。測(cè)試通過紅綠變化確認(rèn)了根因InventoryQueryService里的warehouseMapper.findById()返回了null數(shù)據(jù)庫里的庫存記錄存在但倉庫記錄因?yàn)橥怄I失效導(dǎo)致查不到問題不在實(shí)體類字段而在查詢鏈路的數(shù)據(jù)完整性邊界。接下來 AI 進(jìn)入修復(fù)階段。這次它沒有直接改業(yè)務(wù)代碼而是先問了一個(gè)問題根據(jù)當(dāng)前項(xiàng)目的代碼規(guī)范這類“查不到關(guān)聯(lián)數(shù)據(jù)”的情況業(yè)務(wù)層應(yīng)該報(bào)錯(cuò)、返回空對(duì)象、還是使用降級(jí)邏輯它主動(dòng)去查項(xiàng)目已有的異常處理規(guī)范和類似場(chǎng)景的歷史處理方法。我是把 superpowers 里的代碼規(guī)范類技能和項(xiàng)目AGENTS.md掛接在一起的所以它真的跑到AGENTS.md里查到了項(xiàng)目約定所有查詢服務(wù)遇到關(guān)聯(lián)數(shù)據(jù)缺失時(shí)統(tǒng)一拋出帶業(yè)務(wù)碼的BizException。最終代碼修復(fù)分兩步在查詢邏輯中顯式檢查倉庫對(duì)象是否為 null并拋出包含商品 ID 和倉庫 ID 的帶業(yè)務(wù)語義的異常在接口層的全局異常處理器中補(bǔ)充對(duì)該異常碼的映射返回 404。修完之后 AI 還自動(dòng)跑了一遍相關(guān)模塊的測(cè)試并且更新了記憶文件記錄了“庫存模塊的關(guān)聯(lián)查詢必須檢查空值”這一條長(zhǎng)期約定。4.3 修復(fù)前后的效果對(duì)比與經(jīng)驗(yàn)沉淀修復(fù)前后最大的區(qū)別不是“NPE 沒再出現(xiàn)了”這么簡(jiǎn)單而是整個(gè)處理過程的系統(tǒng)性。以前的 AI 修復(fù)是點(diǎn)狀的報(bào)錯(cuò)在哪就改哪superpowers 加持下是鏈狀的從復(fù)現(xiàn)、多條假設(shè)驗(yàn)證、根因確認(rèn)、項(xiàng)目規(guī)范查詢、修復(fù)實(shí)施、到回歸測(cè)試全覆蓋。從耗時(shí)上看第一次完整走這個(gè)流程確實(shí)比直接讓 AI 改代碼要慢多了至少 5 到 10 分鐘的交互過程主要是排查假設(shè)、寫測(cè)試、查規(guī)范這幾步。但這次修復(fù)之后同類問題在庫存模塊里再也沒出現(xiàn)過。如果還是以前那種“哪里報(bào)錯(cuò)改哪里”的思路我可能要反復(fù)修好幾輪才能把整個(gè)鏈路都補(bǔ)上。而且那幾條沉淀在記憶文件里的約定在后續(xù)所有有關(guān)庫存模塊的會(huì)話里都會(huì)自動(dòng)生效這個(gè)長(zhǎng)期價(jià)值無法估算。我自己復(fù)盤這次實(shí)操時(shí)有個(gè)體會(huì)superpowers 的核心價(jià)值不在于讓 AI 變“聰明”而在于讓 AI 變“穩(wěn)定”。聰明是模型自己決定的穩(wěn)定則完全依靠外部工作流系統(tǒng)的約束。把解決問題的方法論固化下來每次執(zhí)行都走同一套流程產(chǎn)出的質(zhì)量下限被大幅拉高了。5. 常見問題與避坑心得速查5.1 六個(gè)高頻問題排查表我自己還有不少群友在安裝和使用過程中踩過各種各樣的坑有些問題幾乎每換一個(gè)項(xiàng)目就會(huì)遇到一次。這里直接整理成速查表。問題表現(xiàn)可能原因解決辦法Codex 完全不理會(huì)技能回復(fù)跟沒裝之前一樣技能目錄路徑不對(duì)或者 Codex 版本過舊檢查~/.codex/skills下直接是否就是技能文件夾確認(rèn) Codex 版本 ≥ 0.37技能識(shí)別到了但沒有按流程執(zhí)行項(xiàng)目的AGENTS.md沒有關(guān)聯(lián)技能系統(tǒng)或者配置方式?jīng)_突在AGENTS.md中加入調(diào)用規(guī)范說明讓 Codex 在處理任務(wù)前先評(píng)估技能匹配情況技能調(diào)用鏈太長(zhǎng)導(dǎo)致響應(yīng)慢每次任務(wù)都要走太多技能步驟推理消耗大精簡(jiǎn)技能的前置條件避免不必要的深層嵌套記憶文件越來越大、越來越亂沒有定期清理過期決策堆積定期手動(dòng)清理記憶文件只保留當(dāng)前有效約定更新技能庫后自定義技能被覆蓋直接復(fù)制時(shí)把自定義技能文件混在官方技能目錄里自定義技能單獨(dú)用custom_skills目錄維護(hù)不要放進(jìn)官方同名目錄內(nèi)AI 過度依賴技能、死板執(zhí)行技能描述寫得過于強(qiáng)硬調(diào)整技能正文的語氣給 AI 留出一定的自主判斷空間這六個(gè)問題是我最常遇到的其中有幾個(gè)特別典型值得單獨(dú)展開聊一聊。5.2 配置沖突與路徑檢查路徑問題是第一關(guān)也是攔住最多人的一關(guān)。很多教程只說了要復(fù)制 skills 目錄但沒說清楚復(fù)制的是“內(nèi)容”而不是“目錄本身”。我第一次就是直接在~/.codex下把整個(gè)superpowers倉庫鏈接過去了結(jié)果技能目錄變成了~/.codex/superpowers/skillsCodex 掃描的時(shí)候什么都沒找到。檢查路徑是否正確的辦法很簡(jiǎn)單# 列出技能目錄應(yīng)該看到的是技能文件夾而不是其他嵌套層 ls -la ~/.codex/skills/ # 確認(rèn) Codex 日志里沒有技能加載失敗的信息 codex --debug另外Codex 版本太舊也會(huì)導(dǎo)致技能系統(tǒng)整個(gè)不可用。如果你確認(rèn)路徑?jīng)]問題但技能還是不被識(shí)別先升級(jí)一下 Codexnpm update -g openai/codex盡量保持 Codex 是最新版本因?yàn)檫@個(gè)項(xiàng)目迭代很快技能系統(tǒng)的接口也在持續(xù)變化中舊版本可能無法解析新版技能文件的某些字段。5.3 技能更新與自定義維護(hù)策略superpowers 倉庫更新很活躍隔三差五就會(huì)新增技能或者優(yōu)化原有技能的描述。這本來是好事但如果你有自定義技能直接git pull或者重新復(fù)制就可能被覆蓋。我自己維護(hù)了一套比較保險(xiǎn)的方案官方技能和自定義技能分開放。我的做法是~/.codex/skills里只放從 superpowers 官方倉庫復(fù)制來的技能自定義技能放在~/.codex/custom_skills目錄里然后在技能目錄里建一個(gè)軟鏈接指向它。這樣更新官方技能庫時(shí)只重新復(fù)制官方目錄的內(nèi)容自定義技能完全不受影響。# 在官方技能目錄里創(chuàng)建自定義技能的軟鏈接 ln -s ~/.codex/custom_skills/my-custom-skill ~/.codex/skills/my-custom-skill還有一個(gè)值得提醒的點(diǎn)不要貪多把所有技能都裝滿。技能文件越多AI 在每次匹配的時(shí)候需要考慮的范圍就越大決策時(shí)間會(huì)變長(zhǎng)。我通常只裝當(dāng)前工作需要的技能寫代碼、調(diào)試、重構(gòu)、測(cè)試、記憶管理、計(jì)劃制定再加一兩個(gè)項(xiàng)目特化技能。夠用就好保持系統(tǒng)輕量。5.4 關(guān)于過度自動(dòng)化的反思最后一個(gè)可能不算 bug 但值得反思的問題技能系統(tǒng)太強(qiáng)了會(huì)“過度自動(dòng)化”。什么意思AI 一旦養(yǎng)成了“先做計(jì)劃再寫代碼”的習(xí)慣即使你只是讓它改一個(gè)文本拼寫錯(cuò)誤它也會(huì)認(rèn)真走完整個(gè)流程包括讀記憶、做計(jì)劃、寫測(cè)試、更新記憶。對(duì)真正大的任務(wù)來說這是嚴(yán)謹(jǐn)對(duì)小任務(wù)來說這就是浪費(fèi)時(shí)間。我現(xiàn)在的處理方式是分場(chǎng)景使用。小任務(wù)直接用一個(gè)輕量的“快速任務(wù)”技能里面明確寫了“不需要做正式計(jì)劃、不需要寫測(cè)試、直接執(zhí)行并返回結(jié)果”重要改動(dòng)才走完整技能鏈路。在項(xiàng)目AGENTS.md里寫清楚“什么量級(jí)的任務(wù)應(yīng)該走什么流程”這比每次手動(dòng)控制 AI 要高效得多。另外一個(gè)深層的問題是過度依賴外部技能流程會(huì)不會(huì)讓開發(fā)者的判斷力鈍化我的體會(huì)是關(guān)鍵在于你要不要理解技能的機(jī)理。如果你只是把 superpowers 當(dāng)成一個(gè)黑盒裝上去看到 AI 變乖了就什么都不管那確實(shí)會(huì)鈍化。但如果你像我一樣把技能文件一個(gè)個(gè)打開讀一遍理解它是怎么描述任務(wù)、怎么編排步驟的那你其實(shí)是在把一套優(yōu)秀的工程方法論外化出去這種情況下收獲遠(yuǎn)大于損失。我個(gè)人在實(shí)際使用中最推薦的切入方式是先不裝全量技能只裝“制定計(jì)劃”和“調(diào)試問題”這兩個(gè)把一個(gè)已經(jīng)熟悉的小項(xiàng)目交給它重構(gòu)對(duì)比一下前后差異。等你理解了技能的運(yùn)行機(jī)制再逐步把其他技能加進(jìn)來這樣才能真正掌控這套系統(tǒng)而不是被它牽著走。技能文件就像項(xiàng)目管理里的流程模板它存在的意義是保證下限而上限永遠(yuǎn)取決于你怎么用。