1. 為什么“能跑通”和“能交付”之間隔著一道鴻溝寫代碼這件事最近兩年最大的變化不是某個(gè)語言出了新版本而是寫代碼的人旁邊多了一個(gè)隨時(shí)待命的助手。Claude Code、各類 AI 編程工具輪番上陣補(bǔ)全、生成、重構(gòu)、寫測試幾乎什么都能干。但真正把 AI 編程用在正經(jīng)項(xiàng)目里的人都會(huì)有一個(gè)共同感受它快得驚人也飄得驚人。同一個(gè)需求問兩遍出來的代碼結(jié)構(gòu)可能完全不同讓它改一個(gè)函數(shù)它順手把你沒讓它動(dòng)的三個(gè)文件也改了跑測試的時(shí)候信誓旦旦說“已通過”結(jié)果你手動(dòng)一跑紅的。這個(gè)問題的本質(zhì)不是模型不夠聰明而是缺少一套約束機(jī)制。模型的能力是概率性的它每次都在“猜”你想要什么猜對(duì)了就是驚喜猜錯(cuò)了就是事故。而 Superpowers 這套東西要解決的恰恰就是這個(gè)“猜”的問題——它把 AI 編程從“碰運(yùn)氣”拉向“可復(fù)現(xiàn)”。我最初接觸 Superpowers 的時(shí)候第一反應(yīng)是“又一個(gè)包裝層”。但用下來發(fā)現(xiàn)它的定位其實(shí)很清晰它不是模型也不是 IDE而是一套給 AI 編程助手用的技能Skill體系。你可以把它理解成給 AI 裝了一本“作業(yè)規(guī)范手冊(cè)”——什么任務(wù)該走什么流程、每一步該產(chǎn)出什么、什么情況下必須停下來問人全都寫死在 Skill 里。這樣一來AI 的行為就從“自由發(fā)揮”變成了“按章辦事”。這篇文章適合三類人看一是已經(jīng)在用 Claude Code 或類似工具、但被它的不穩(wěn)定性折磨過的開發(fā)者二是想把 AI 編程引入團(tuán)隊(duì)、但擔(dān)心代碼質(zhì)量失控的技術(shù)負(fù)責(zé)人三是單純好奇“Skill 到底是什么、值不值得折騰”的觀望者。我會(huì)從 Skill 的底層邏輯講起把安裝、配置、核心 Skill 的用法、踩坑經(jīng)驗(yàn)、以及怎么把它接進(jìn)真實(shí)項(xiàng)目流程一層層拆開說。不吹不黑講清楚它到底解決了什么問題以及它解決不了什么問題。2. Skill 到底是什么把“提示詞”升級(jí)成“可執(zhí)行規(guī)范”2.1 從提示詞到 Skill 的認(rèn)知躍遷大部分人用 AI 編程的方式是在對(duì)話框里敲一段提示詞然后等結(jié)果。提示詞寫得好結(jié)果就好一點(diǎn)寫得隨意結(jié)果就隨緣。這種方式的問題在于提示詞是一次性的、不可復(fù)用的、無法版本管理的。你今天寫了一段很精妙的提示詞讓 AI 做代碼審查明天換個(gè)項(xiàng)目這段提示詞就找不到了或者環(huán)境變了就不適用了。Skill 的思路完全不同。它把“怎么做一件事”固化成一個(gè)結(jié)構(gòu)化的文件里面包含觸發(fā)條件、執(zhí)行步驟、檢查清單、輸出格式。你可以把它提交到 Git 倉庫里可以 review可以迭代。提示詞是口頭交代Skill 是書面 SOP。這個(gè)區(qū)別聽起來簡單但它帶來的行為差異是巨大的。舉個(gè)具體的例子。你讓 AI “幫我審查這段代碼”它可能給你一堆泛泛而談的建議“建議增加錯(cuò)誤處理”“可以考慮提取公共方法”。但如果你用的是 Superpowers 里的代碼審查 Skill它會(huì)按照預(yù)設(shè)的檢查維度逐項(xiàng)過邊界條件、并發(fā)安全、資源釋放、命名一致性、測試覆蓋。每一項(xiàng)都有明確的判斷標(biāo)準(zhǔn)輸出也是結(jié)構(gòu)化的。這就是“規(guī)范”和“建議”的區(qū)別。2.2 Skill 的文件結(jié)構(gòu)與加載機(jī)制一個(gè) Skill 本質(zhì)上就是一個(gè)目錄里面通常包含一個(gè)主描述文件一般是 Markdown 格式和若干輔助資源。主描述文件里會(huì)寫清楚這個(gè) Skill 叫什么、什么時(shí)候觸發(fā)、執(zhí)行流程是什么、有哪些注意事項(xiàng)。輔助資源可能是模板文件、檢查清單、示例代碼。加載機(jī)制上Claude Code 這類工具會(huì)在啟動(dòng)時(shí)掃描指定的 Skill 目錄把可用的 Skill 注冊(cè)進(jìn)來。當(dāng)你的對(duì)話內(nèi)容匹配到某個(gè) Skill 的觸發(fā)條件時(shí)它就會(huì)自動(dòng)加載對(duì)應(yīng)的規(guī)范來約束自己的行為。這個(gè)過程對(duì)用戶是透明的——你不需要手動(dòng)“調(diào)用”某個(gè) Skill只要你的需求落在它的覆蓋范圍內(nèi)它就會(huì)生效。這里有個(gè)容易被忽略的細(xì)節(jié)Skill 的觸發(fā)是靠語義匹配的不是靠關(guān)鍵詞精確匹配。這意味著你寫 Skill 描述的時(shí)候觸發(fā)條件的措辭會(huì)直接影響它能不能被正確激活。寫得太窄很多該觸發(fā)的時(shí)候不觸發(fā)寫得太寬不該觸發(fā)的時(shí)候亂觸發(fā)。這個(gè)度需要根據(jù)實(shí)際使用情況反復(fù)調(diào)。2.3 為什么“約束”反而提升了效率直覺上給 AI 加約束應(yīng)該會(huì)讓它變慢。但實(shí)際用下來恰恰相反。原因在于AI 編程最大的時(shí)間浪費(fèi)不是生成代碼而是返工。它生成得快你發(fā)現(xiàn)不對(duì)重新描述需求它再生成你再發(fā)現(xiàn)不對(duì)……這個(gè)循環(huán)才是真正吃時(shí)間的。Skill 通過提前鎖定流程把返工消滅在源頭。比如一個(gè)“新功能開發(fā)”的 Skill 會(huì)強(qiáng)制要求先確認(rèn)需求邊界再寫接口定義再寫實(shí)現(xiàn)最后寫測試。每一步都有產(chǎn)出物每一步都可以被檢查?？雌饋聿襟E多了但因?yàn)槊恳徊蕉际菍?duì)的整體反而更快。這就像裝修房子先出圖紙?jiān)偈┕け冗吰鰤吀脑O(shè)計(jì)要快得多。3. 安裝與配置那些文檔里不會(huì)寫的細(xì)節(jié)3.1 環(huán)境準(zhǔn)備的真實(shí)門檻Superpowers 的安裝本身不復(fù)雜但它對(duì)運(yùn)行環(huán)境有要求。你需要一個(gè)支持 Skill 機(jī)制的 AI 編程工具作為宿主目前主流的是 Claude Code。安裝 Claude Code 的方式根據(jù)操作系統(tǒng)不同有差異Windows、macOS、Linux 各有各的路徑。這里不展開具體命令重點(diǎn)說幾個(gè)實(shí)際安裝時(shí)容易卡住的地方。第一個(gè)坑是權(quán)限問題。Skill 目錄通常需要工具本身有讀寫權(quán)限如果你把它放在系統(tǒng)保護(hù)目錄下加載會(huì)靜默失敗——不報(bào)錯(cuò)但 Skill 就是不生效。建議放在用戶目錄下的專用文件夾里路徑里不要有中文和空格。第二個(gè)坑是版本兼容。Skill 機(jī)制本身在迭代不同版本的宿主工具對(duì) Skill 文件格式的支持程度不一樣。如果你從別人那里拷來一個(gè) Skill 用不了先別懷疑 Skill 寫錯(cuò)了大概率是版本對(duì)不上。養(yǎng)成習(xí)慣拿到一個(gè) Skill先看它的說明里有沒有標(biāo)注適配的宿主版本。第三個(gè)坑是網(wǎng)絡(luò)環(huán)境。有些 Skill 在執(zhí)行過程中需要訪問外部資源如果你的環(huán)境訪問不了Skill 會(huì)在某一步卡住。這種情況下的表現(xiàn)往往是“執(zhí)行到一半沒反應(yīng)了”而不是明確報(bào)錯(cuò)。排查的時(shí)候要有意識(shí)地去想“這一步是不是需要聯(lián)網(wǎng)”。3.2 目錄組織與命名約定Skill 放多了之后目錄組織就變成一個(gè)真問題。我的建議是按功能域分目錄而不是按來源分。比如skills/ code-review/ testing/ refactor/ docs/ project-setup/每個(gè)目錄下放對(duì)應(yīng)的 Skill。這樣找起來快也方便你按需啟用或禁用某一類。命名上用動(dòng)詞開頭、小寫、連字符分隔比如review-pull-request、generate-unit-test。別用中文名別用駝峰別用空格——這些在跨平臺(tái)和腳本調(diào)用時(shí)都會(huì)出問題。還有一個(gè)經(jīng)驗(yàn)給每個(gè) Skill 寫一個(gè) README。哪怕只有三行寫清楚它干什么、什么時(shí)候用、有什么前提條件。三個(gè)月后你自己回來看沒有 README 的 Skill 你根本不敢用。3.3 驗(yàn)證 Skill 是否真正生效裝完之后怎么確認(rèn)它真的在工作最直接的辦法是故意觸發(fā)一次。找一個(gè)明確落在某個(gè) Skill 覆蓋范圍內(nèi)的任務(wù)比如讓 AI 做一次代碼審查然后觀察它的輸出格式。如果輸出是結(jié)構(gòu)化的、有明確檢查維度的說明 Skill 生效了如果還是那種泛泛而談的風(fēng)格說明沒生效。沒生效的排查順序先看目錄路徑對(duì)不對(duì)再看文件格式是否符合規(guī)范然后看宿主工具的日志里有沒有加載記錄。這三步能解決八成問題。剩下兩成通常是 Skill 描述里的觸發(fā)條件寫得太模糊導(dǎo)致語義匹配沒命中。提示不要一次性裝幾十個(gè) Skill。裝太多會(huì)導(dǎo)致觸發(fā)沖突——同一個(gè)需求可能同時(shí)匹配到多個(gè) Skill行為就不可預(yù)測了。建議按項(xiàng)目需要一次啟用五到八個(gè)用完再換。4. 核心 Skill 拆解代碼審查、測試生成與重構(gòu)4.1 代碼審查 Skill把“感覺不對(duì)”變成“逐項(xiàng)核對(duì)”代碼審查是 Superpowers 里價(jià)值最高的 Skill 之一。人工審查代碼的問題在于注意力是有限的、標(biāo)準(zhǔn)是不統(tǒng)一的。同一個(gè)人上午審和下午審嚴(yán)格程度可能都不一樣。AI 審查如果不受約束問題更大——它會(huì)漏掉關(guān)鍵問題卻對(duì)無關(guān)緊要的風(fēng)格問題喋喋不休。一個(gè)設(shè)計(jì)良好的代碼審查 Skill會(huì)把審查拆成幾個(gè)固定維度每個(gè)維度有明確的檢查項(xiàng)。常見的維度包括審查維度具體檢查項(xiàng)常見問題邊界條件空值、越界、極端輸入數(shù)組訪問未判空錯(cuò)誤處理異常捕獲、錯(cuò)誤傳播、降級(jí)策略catch 塊里什么都不做資源管理文件句柄、連接、鎖的釋放異常路徑下資源泄漏并發(fā)安全共享狀態(tài)、競態(tài)條件、死鎖多線程寫同一變量可測試性依賴注入、副作用隔離硬編碼外部依賴這個(gè)表格本身就是 Skill 的一部分。AI 拿到它之后會(huì)逐項(xiàng)過一遍而不是憑感覺給建議。實(shí)測下來這種結(jié)構(gòu)化審查能抓出的人工遺漏率明顯更低尤其是在邊界條件和資源管理這兩塊。但要注意代碼審查 Skill 不能替代人的判斷。它能告訴你“這里可能有問題”但“這個(gè)問題在這個(gè)業(yè)務(wù)場景下是否真的嚴(yán)重”還是得人來定。我的用法是讓 Skill 做第一遍掃描把可疑點(diǎn)列出來然后我針對(duì)性地看。這樣比我自己從頭讀一遍快得多也比讓 AI 自由發(fā)揮靠譜得多。4.2 測試生成 Skill從“補(bǔ)測試”到“按契約寫測試”測試生成是另一個(gè)高頻場景。大部分人讓 AI 寫測試的方式是“給這個(gè)函數(shù)寫個(gè)測試”結(jié)果出來的測試往往只覆蓋了正常路徑邊界和異常路徑基本沒有。這不是 AI 偷懶而是它不知道你的測試標(biāo)準(zhǔn)是什么。測試生成 Skill 的核心價(jià)值在于定義“什么算一個(gè)合格的測試”。一個(gè)典型的測試 Skill 會(huì)要求每個(gè)公開方法至少覆蓋正常路徑、邊界路徑、異常路徑三類用例測試命名要能反映被測行為和預(yù)期結(jié)果斷言要具體不能只斷言“不拋異?！盡ock 的范圍要最小化能不用就不用有了這些約束AI 生成的測試質(zhì)量會(huì)穩(wěn)定很多。我自己的習(xí)慣是在 Skill 里再加一條生成的測試必須先跑一遍確認(rèn)能通過再交付。這一條能過濾掉大量“看起來對(duì)但跑不起來”的測試代碼。這里有個(gè)實(shí)操心得測試 Skill 最好和你的測試框架綁定。不同框架的斷言風(fēng)格、Mock 方式、異步處理都不一樣。如果你的項(xiàng)目用 JestSkill 里就寫 Jest 的規(guī)范用 pytest就寫 pytest 的。通用型的測試 Skill 看起來適用范圍廣實(shí)際用起來哪哪都不順手。4.3 重構(gòu) Skill小步走每步都可回退重構(gòu)是最容易出事的場景。AI 重構(gòu)的典型問題是步子太大——它可能一次性改十幾個(gè)文件你根本 review 不過來出了問題也不知道是哪一步引入的。重構(gòu) Skill 的設(shè)計(jì)原則應(yīng)該是強(qiáng)制小步提交。具體來說Skill 會(huì)要求每次只重構(gòu)一個(gè)邏輯單元重構(gòu)前后必須能通過同一套測試如果測試覆蓋不足先補(bǔ)測試再重構(gòu)每一步的改動(dòng)范圍要明確列出這套約束看起來繁瑣但它把重構(gòu)從“高風(fēng)險(xiǎn)操作”變成了“可控的漸進(jìn)過程”。我踩過的最大的坑就是讓 AI 一次性重構(gòu)一個(gè)模塊結(jié)果它把某個(gè)方法的語義悄悄改了測試沒覆蓋到上線后才發(fā)現(xiàn)。從那以后我用的重構(gòu) Skill 里第一條就是“禁止跨文件批量修改除非明確授權(quán)”。5. 把 Skill 接進(jìn)真實(shí)項(xiàng)目流程的幾種姿勢(shì)5.1 個(gè)人開發(fā)者的輕量用法如果你是一個(gè)人寫項(xiàng)目Skill 的用法可以很輕。我的建議是只裝三個(gè)代碼審查、測試生成、提交信息規(guī)范。這三個(gè)覆蓋了日常最高頻的場景而且互相不沖突。工作流大概是這樣寫完一個(gè)功能先讓審查 Skill 過一遍把明顯問題修掉然后讓測試 Skill 補(bǔ)測試最后提交的時(shí)候提交信息 Skill 會(huì)幫你把 commit message 寫規(guī)范。整個(gè)過程你還是在主導(dǎo)Skill 只是在你容易疏忽的地方兜底。這種用法的好處是心智負(fù)擔(dān)低。你不需要記住每個(gè) Skill 的細(xì)節(jié)只需要知道“寫完代碼之后走這三步”。習(xí)慣養(yǎng)成之后代碼質(zhì)量的底線就被抬高了。5.2 團(tuán)隊(duì)協(xié)作中的 Skill 共享團(tuán)隊(duì)用 Skill核心問題是標(biāo)準(zhǔn)統(tǒng)一。如果每個(gè)人用的 Skill 不一樣那 AI 產(chǎn)出的代碼風(fēng)格就會(huì)五花八門review 的時(shí)候又是一場災(zāi)難。正確的做法是把 Skill 納入版本管理作為項(xiàng)目規(guī)范的一部分。新成員入職拉下代碼的同時(shí)也拉下 Skill 目錄配置好之后AI 的行為就和團(tuán)隊(duì)標(biāo)準(zhǔn)對(duì)齊了。這比寫一堆文檔然后指望大家去看要有效得多——文檔沒人看但 Skill 是 AI 強(qiáng)制執(zhí)行。團(tuán)隊(duì)場景下Skill 的迭代也要走 review 流程。誰想改審查標(biāo)準(zhǔn)提 PR大家討論合并。這樣 Skill 本身的質(zhì)量也有保障。我見過一些團(tuán)隊(duì)Skill 目錄比業(yè)務(wù)代碼還亂那還不如不用。5.3 和 CI/CD 的結(jié)合點(diǎn)Skill 能不能接進(jìn) CI/CD可以但要分清邊界。Skill 負(fù)責(zé)的是“生成階段”的約束CI 負(fù)責(zé)的是“驗(yàn)證階段”的把關(guān)。兩者是互補(bǔ)的不是替代關(guān)系。具體來說你可以在 CI 里加一步檢查本次提交的代碼是否經(jīng)過了審查 Skill 的處理比如檢查有沒有審查報(bào)告文件。但這只是形式上的檢查真正的質(zhì)量還是靠 Skill 在生成階段就約束住。指望 CI 去抓 AI 生成代碼的所有問題不現(xiàn)實(shí)——CI 跑的是測試和靜態(tài)檢查它抓不到“邏輯寫錯(cuò)了但測試也寫錯(cuò)了”這種情況。6. 踩坑實(shí)錄Skill 不生效、亂觸發(fā)、輸出跑偏怎么排查6.1 Skill 裝了但沒反應(yīng)這是最高頻的問題。表現(xiàn)是你明明裝了某個(gè) Skill但 AI 的行為和沒裝一樣。排查鏈路應(yīng)該是這樣的第一步確認(rèn)文件被加載了?？此拗鞴ぞ叩膯?dòng)日志或者用一個(gè)明確的測試任務(wù)去觸發(fā)觀察有沒有 Skill 相關(guān)的輸出。如果日志里根本沒有加載記錄那就是路徑或權(quán)限問題。第二步確認(rèn)觸發(fā)條件匹配。Skill 的觸發(fā)是靠語義匹配的如果你的需求描述和 Skill 里寫的觸發(fā)條件措辭差異太大可能就匹配不上。解決辦法是在 Skill 的觸發(fā)條件里多寫幾個(gè)同義表述覆蓋不同的說法。第三步確認(rèn)沒有沖突。如果同時(shí)有多個(gè) Skill 匹配到了同一個(gè)需求宿主工具可能會(huì)選擇一個(gè)或者干脆都不選。這時(shí)候要檢查 Skill 之間的覆蓋范圍有沒有重疊有的話要收窄。6.2 Skill 亂觸發(fā)導(dǎo)致行為異常和上一個(gè)問題相反這個(gè)是有時(shí)候不該觸發(fā)的時(shí)候觸發(fā)了。典型表現(xiàn)是你只是想讓 AI 改個(gè)錯(cuò)別字結(jié)果它啟動(dòng)了一整套代碼審查流程輸出一大堆你不需要的東西。這個(gè)問題的根源通常是觸發(fā)條件寫得太寬。比如一個(gè)代碼審查 Skill如果觸發(fā)條件只寫“涉及代碼”那基本上任何和代碼相關(guān)的對(duì)話都會(huì)觸發(fā)它。正確的寫法應(yīng)該是加上限定比如“當(dāng)用戶明確要求審查、檢查、review 代碼時(shí)觸發(fā)”。調(diào)整觸發(fā)條件是個(gè)反復(fù)試的過程。我的經(jīng)驗(yàn)是寧可寫窄一點(diǎn)用的時(shí)候手動(dòng)觸發(fā)也不要寫太寬導(dǎo)致到處亂觸發(fā)。手動(dòng)觸發(fā)雖然多一步但行為可預(yù)測。6.3 輸出格式不符合預(yù)期有時(shí)候 Skill 確實(shí)觸發(fā)了但輸出格式和你想要的不一樣。這通常是 Skill 描述里的輸出模板寫得不夠具體。比如你希望審查結(jié)果是一個(gè)表格但 Skill 里只寫了“列出問題”那 AI 就可能用段落、用列表、用各種格式。解決辦法是在 Skill 里給出明確的輸出示例。不要只描述“輸出一個(gè)表格”而是直接寫一個(gè) Markdown 表格的樣例。AI 對(duì)示例的遵循程度遠(yuǎn)高于對(duì)描述的遵循程度。這個(gè)技巧在寫所有 Skill 的時(shí)候都適用——示例比描述管用。7. 關(guān)于 Skill 的邊界它解決什么不解決什么用了這么久我對(duì) Superpowers 這類 Skill 體系的定位越來越清晰。它解決的是流程規(guī)范化和行為可復(fù)現(xiàn)的問題。它讓 AI 編程從“每次都是新的冒險(xiǎn)”變成“每次都在已知軌道上運(yùn)行”。這個(gè)價(jià)值是實(shí)打?qū)嵉挠绕涫窃谛枰L期維護(hù)的項(xiàng)目里。但它不解決判斷力的問題。Skill 能告訴 AI“檢查邊界條件”但“這個(gè)邊界條件在這個(gè)業(yè)務(wù)里是否重要”還是得人來判斷。Skill 能生成測試但“這個(gè)測試是否測到了真正重要的東西”還是得人來 review。Skill 是放大器不是替代品。你的工程判斷力越強(qiáng)Skill 幫你放大的效果越好你的判斷力越弱Skill 也只是讓你更快地產(chǎn)生一堆看起來規(guī)范但實(shí)際沒用的東西。還有一個(gè)現(xiàn)實(shí)問題維護(hù) Skill 本身是有成本的。寫一個(gè) Skill、調(diào)觸發(fā)條件、迭代輸出格式這些都要花時(shí)間。如果你的項(xiàng)目是一次性的、用完就扔的那投入產(chǎn)出比可能不劃算。但如果是一個(gè)要維護(hù)半年以上的項(xiàng)目那前期在 Skill 上的投入后面會(huì)以“少返工、少救火”的形式加倍還回來。我自己的做法是從最小的 Skill 開始。先寫一個(gè)代碼審查的用兩周覺得有價(jià)值再加測試生成的。不要一上來就搞一套大而全的體系那樣大概率會(huì)因?yàn)榫S護(hù)不過來而廢棄。Skill 這東西用起來的才有價(jià)值躺在目錄里的只是負(fù)擔(dān)。最后分享一個(gè)我踩過的坑我曾經(jīng)寫了一個(gè)特別詳細(xì)的 Skill把某個(gè)模塊的所有編碼規(guī)范都塞進(jìn)去了結(jié)果 AI 每次觸發(fā)都要處理一大堆上下文響應(yīng)變慢不說還經(jīng)常因?yàn)樾畔⑦^載而抓不住重點(diǎn)。后來我把它拆成了三個(gè)小 Skill每個(gè)只聚焦一個(gè)方面效果反而好得多。Skill 的粒度寧小勿大。