矩：從自由發(fā)揮到規(guī)范交付)
1. AI 寫代碼不缺能力缺的是“邊界感”先講一個我上個月的真實(shí)經(jīng)歷。當(dāng)時我用 Claude 寫一個內(nèi)部工具的后端接口需求很簡單從第三方服務(wù)拉取數(shù)據(jù)、清洗、落庫、給前端返回分頁結(jié)果。我把需求描述得足夠清楚模型也給出了看起來非常合理的實(shí)現(xiàn)。結(jié)果代碼 review 的時候我發(fā)現(xiàn)它在沒有任何提示的情況下自作主張給數(shù)據(jù)庫表加了兩個索引、引入了一個自己覺得“更好”的 ORM 方法、還把分頁參數(shù)從 offset/limit 改成了 cursor 風(fēng)格。單看每一處改動單獨(dú)拎出來可能都算合理優(yōu)化。但放在一個團(tuán)隊(duì)項(xiàng)目里這種“自由發(fā)揮”就是災(zāi)難——你沒有跟別人對齊就動表結(jié)構(gòu)輕則埋坑重則直接影響到上下游服務(wù)的契約。這其實(shí)就是現(xiàn)在 AI 編程最核心的痛點(diǎn)模型本身的能力已經(jīng)不是瓶頸瓶頸是它沒有工程紀(jì)律。它像一個能力很強(qiáng)但沒有受過職業(yè)訓(xùn)練的新人你讓它“寫個模塊”它恨不得把整個架構(gòu)都重構(gòu)了。你讓它“改個 bug”它能順手把旁邊的文件也格式化一遍。后來我開始系統(tǒng)性使用 Superpowers 這套 skills 體系來約束 Agent 行為配合 Claude Code 和 OpenSpec 一起用實(shí)測下來效果非常明顯。這篇文章我就把完整的思路、安裝方法、核心技能拆解和實(shí)戰(zhàn)記錄分享出來希望能幫到在 AI 編程里被“失控感”困擾的人。尤其適合這幾類人參考正在用 Cursor、Windsurf、Claude Code 做全棧項(xiàng)目的開發(fā)者想給團(tuán)隊(duì)引入統(tǒng)一 AI 編碼規(guī)范的技術(shù)負(fù)責(zé)人以及被 Agent 生成的“一次性代碼”搞到不敢合并 PR 的人。2. 先搞懂一個關(guān)鍵問題Agent 為什么總愛“自由發(fā)揮”2.1 失控的根源LLM 天然是“接龍機(jī)器”拋開所有花哨的概念大模型本質(zhì)上是“根據(jù)上文預(yù)測下文”的統(tǒng)計模型。它沒有“項(xiàng)目全局觀”也沒有“穩(wěn)定的長期記憶”。每生成一個 token它都在做同一件事猜測“接下來最應(yīng)該出現(xiàn)的字符是什么”。這就帶來兩個致命問題。第一模型沒有工作流意識。它不知道“先寫測試再寫實(shí)現(xiàn)”和“先寫實(shí)現(xiàn)再補(bǔ)測試”有什么區(qū)別更不知道“先確認(rèn)需求再動手”和“邊寫邊猜”哪個更穩(wěn)妥。它只會根據(jù) prompt 里的信息用最省力的路徑生成內(nèi)容。你讓它“寫一個登錄接口”它就直接開始寫接口代碼完全不會考慮“這個接口跟現(xiàn)有用戶系統(tǒng)的關(guān)系是什么”。第二模型的輸出傾向是“補(bǔ)完”而不是“執(zhí)行”。你給它一個需求它會傾向于生成一個“看起來完整”的方案而不是“執(zhí)行當(dāng)前就需要的部分”。所以你會看到它瘋狂給自己加戲——補(bǔ)你沒提的參數(shù)校驗(yàn)、加它認(rèn)為需要的索引、重構(gòu)它覺得不優(yōu)雅的代碼這些都是“補(bǔ)完傾向”的體現(xiàn)。我用一個生活化的類比來解釋普通對話式 AI 像一個反應(yīng)很快的實(shí)習(xí)生你說什么它都能接上但你不盯著它它就會按自己的喜好干活。Superpowers 的作用是給這個實(shí)習(xí)生發(fā)一本厚厚的工作手冊上面寫清楚接到任務(wù)第一步干什么、第二步干什么、什么情況下需要停下來問人、什么情況下可以自己做主。2.2 傳統(tǒng) prompt 為什么解決不了這個問題很多人嘗試用“超級 prompt”來約束 Agent。我也試過。比如在系統(tǒng)提示詞里寫“你必須遵循以下步驟1. 理解需求 2. 搜索代碼 3. 制定計劃 4. 執(zhí)行計劃 5. 自測”。問題在于Prompt 是靜態(tài)文本而 Agent 的執(zhí)行是動態(tài)過程。你寫了一大段規(guī)則模型在開始階段確實(shí)會遵循但一旦對話輪次變長、上下文變復(fù)雜這些規(guī)則就會被稀釋、遺忘、甚至被后續(xù)內(nèi)容覆蓋。舉個很具體的例子。我在 Cursor 里用過一個很長的系統(tǒng)提示詞要求 AI 每次改動前先讀相關(guān)文件。前兩輪對話它確實(shí)照做了。到了第五輪我問它“順便把這個按鈕的顏色改一下”它直接就改代碼完全跳過了“讀文件”這個步驟。原因很簡單——模型認(rèn)為“改顏色”是個簡單任務(wù)沒必要走完整流程。所以問題不是 prompt 寫得不夠長而是prompt 沒有把“流程”固化成“能力”。你需要的不是一段寫在系統(tǒng)提示詞里的文本而是一套能被 Agent 主動識別、主動調(diào)用、按步驟執(zhí)行的技能模塊。2.3 Superpowers 的解法把流程變成“技能包”Superpowers 的核心理念就是把軟件開發(fā)中的高頻工作流——頭腦風(fēng)暴、任務(wù)拆解、計劃執(zhí)行、調(diào)試排錯、提交信息規(guī)范——封裝成一個個獨(dú)立的技能文件。每個技能包含完整的操作步驟、指標(biāo)定義、執(zhí)行規(guī)則和自查清單。它的工作機(jī)制是你在對話里用一個特定語法比如 superpowers 或 brainstorming喚起對應(yīng)技能Agent 就會按技能文件里的步驟執(zhí)行。這跟普通 prompt 最大的區(qū)別在于——技能文件是在執(zhí)行時動態(tài)加載的不會占用你寶貴的上下文窗口也不會被后續(xù)對話稀釋。我更愿意把它理解成一套**“工程級的行為規(guī)范系統(tǒng)”**不改變模型的推理能力只約束模型的做事方式。就像圍棋高手不是靠“背規(guī)則”贏棋而是靠“行棋規(guī)范”保證每步棋的質(zhì)量下限。Superpowers 要保證的就是 AI 每次動手寫代碼的“質(zhì)量下限”。2.4 Superpowers 和 OpenSpec 的分工一個管“怎么干活”一個管“干什么活”很多人在了解 Superpowers 時會同時聽到另一個名詞OpenSpec。這兩個工具經(jīng)常被一起推薦但它們的定位完全不同。簡單來說Superpowers 管的是“怎么干活”——怎么分析需求、怎么拆解任務(wù)、怎么按計劃執(zhí)行、怎么系統(tǒng)化調(diào)試。它約束的是 Agent 的行為方式。OpenSpec 管的是“干什么活”——它定義了一套需求描述規(guī)范把需求拆成帶有明確驗(yàn)收標(biāo)準(zhǔn)的 spec 文檔讓 Agent 在動手前先明確“完成”的定義。它約束的是 Agent 的工作對象。打個比方Superpowers 是工作流程手冊O(shè)penSpec 是項(xiàng)目需求清單。有了流程手冊但清單不清晰Agent 會高效地做錯事有了清晰清單但沒有流程約束Agent 會自由發(fā)揮到讓你崩潰。兩者配合使用才是完整方案——這也是“Claude Code OpenSpec Superpowers 三件套”這個詞會流行的原因。3. Superpowers 到底包含哪些技能核心模塊梳理項(xiàng)目本身是一個開源的 skills 集合完整內(nèi)容在 GitHub 上。我建議你拿到手之后先做一個整體瀏覽搞清楚每個 skill 大概負(fù)責(zé)什么場景不然真到實(shí)戰(zhàn)時你都不知道該喚起哪個。3.1 核心工作流技能戰(zhàn)艦版本的“主炮”技能名稱定位核心作用brainstorming需求分析在和 Agent 對話中澄清需求、探索方案、識別風(fēng)險writing-plans計劃制定把需求拆解成有依賴關(guān)系、驗(yàn)收標(biāo)準(zhǔn)的執(zhí)行計劃executing-plans計劃執(zhí)行按計劃逐項(xiàng)實(shí)現(xiàn)每完成一項(xiàng)就檢查一項(xiàng)debugging系統(tǒng)調(diào)試用“提出假設(shè)、驗(yàn)證假設(shè)”的方法定位并修復(fù) bug這四個技能是整套體系的骨架。它們對應(yīng)的是軟件開發(fā)中最基礎(chǔ)的四個階段理解需求、制定方案、執(zhí)行方案、修復(fù)問題。沒有這套流程Agent 的所有輸出都是“即興發(fā)揮”有了這套流程Agent 的每一步都有章可循。3.2 輔助技能讓工程規(guī)范更完整的“零件”除了四大核心技能Superpowers 還附帶了一些輔助技能我實(shí)際使用下來覺得價值也非常高writing-commits約束 Agent 寫規(guī)范的 Git 提交信息避免出現(xiàn)“fix stuff”“update code”這類毫無信息量的提交。checklists讓 Agent 在任務(wù)完成前生成檢查清單并逐項(xiàng)自查相當(dāng)于模擬人工 Code Review 的第一道閘門。TDD測試驅(qū)動開發(fā)相關(guān)技能約束 Agent 按“先寫測試、再寫實(shí)現(xiàn)、最后重構(gòu)”的順序開發(fā)。spec-generation結(jié)合 OpenSpec 使用將需求文檔自動轉(zhuǎn)化為帶驗(yàn)收標(biāo)準(zhǔn)的規(guī)格說明。3.3 skill 和 agent 到底有什么區(qū)別這個關(guān)鍵詞挺熱的經(jīng)常有人混淆。我在使用中總結(jié)了一個最簡單的區(qū)分方式Agent 是“執(zhí)行體”Skill 是“能力包”。Agent 負(fù)責(zé)調(diào)用模型、管理上下文、執(zhí)行動作比如讀寫文件、運(yùn)行命令Skill 是給 Agent 提供的“操作手冊”告訴它某類任務(wù)應(yīng)該按什么步驟來做。類比一下Agent 是廚師本人Skill 是菜譜。沒有廚師菜譜只是一堆紙沒有菜譜廚師只能憑經(jīng)驗(yàn)自由發(fā)揮。Agent 的靈活性和 Skill 的規(guī)范性結(jié)合才能穩(wěn)定地產(chǎn)出高質(zhì)量的代碼。4. 安裝與配置全流程Claude Code / Cursor / Windsurf 一次講清4.1 整體安裝思路三個步驟搞定Superpowers 的安裝邏輯很簡單把技能文件克隆到本地再讓 AI 編程工具能讀取這些文件。不涉及編譯、不涉及復(fù)雜的依賴關(guān)系本質(zhì)上就是“放文件”和“告訴工具去哪找文件”這兩件事。不同工具的讀取方式不太一樣Claude Code通過skills命令直接在 CLI 里添加。Cursor / Windsurf需要在項(xiàng)目根目錄或全局.cursor/skills目錄下放置技能文件。OpenCode 等開源工具按各自約定的 skills 目錄放置即可。我的建議是先從 Claude Code 入手因?yàn)樗?skills 機(jī)制最成熟社區(qū)案例最多。等你熟悉了技能文件的結(jié)構(gòu)再遷移到其他工具就很輕松了。4.2 Claude Code 下的完整安裝步驟Claude Code 的安裝算是三種工具里最順暢的。打開終端執(zhí)行以下命令# 先進(jìn)入 Claude Code 的配置目錄 cd ~/.claude # 查看當(dāng)前可用的 skills 命令 claude skills如果你是第一次安裝需要先初始化 skills 目錄。然后從 GitHub 拉取 Superpowers 項(xiàng)目git clone https://github.com/obra/superpowers.git # 用 Claude Code 自帶的 skills 命令添加技能 claude skills add superpowers這里有個細(xì)節(jié)我要特別強(qiáng)調(diào)不同版本的 Claude Code 命令略有差異。老版本可能沒有skills add子命令需要手動把技能目錄鏈接或復(fù)制到~/.claude/skills/下。我的建議是先跑一下claude --version確認(rèn)版本再對照官方文檔操作。安裝完成后在 Claude Code 里輸入superpowers如果能正常喚起技能列表就說明安裝成功了。4.3 Cursor / Windsurf 下的安裝方式如果你主要在 Cursor 或 Windsurf 里工作安裝思路稍微不同。這兩個工具沒有類似claude skills的命令行入口需要手動放置技能目錄。以 Cursor 為例# 進(jìn)入你的項(xiàng)目目錄 cd your-project # 創(chuàng)建 .cursor/skills 目錄 mkdir -p .cursor/skills # 克隆 Superpowers 到該目錄 git clone https://github.com/obra/superpowers.git .cursor/skills/superpowers克隆完成后你在 Cursor 的對話里用superpowers或直接提到相關(guān)技能名比如 brainstorming它就能讀取到技能內(nèi)容。我在實(shí)際使用中有一個小經(jīng)驗(yàn)Cursor 直接引用子技能的成功率更高。比如我輸入brainstorming往往比輸入superpowers更穩(wěn)定原因是 Cursor 對嵌套目錄里的文件識別可能會有遺漏。所以我會在.cursor/skills/下創(chuàng)建一個SKILL.md索引文件把常用技能的名字和路徑列清楚這樣 Agent 找不到的時候還能看一眼索引。4.4 驗(yàn)證安裝是否成功一個 30 秒自測方法裝完之后別急著開工先做一個快速驗(yàn)證。我在第一次安裝時就踩過“以為自己裝好了結(jié)果根本沒生效”的坑。進(jìn)入你的 AI 編程工具輸入這樣一句話請列出你當(dāng)前可用的所有 skills并簡要說明每個 skill 的用途。如果安裝成功Agent 會列出 superpowers 相關(guān)技能的清單和說明。如果它回答“我沒有 skills”或者答非所問說明技能文件沒有被正確讀取。還有一個更直接的方法直接輸入brainstorming或者writing-plans如果 Agent 開始按技能里的步驟引導(dǎo)你提問說明它已經(jīng)成功加載了技能內(nèi)容。5. 核心技能實(shí)戰(zhàn)拆解Superpowers 是怎么讓 Agent“守規(guī)矩”的5.1 brainstorming讓 Agent先學(xué)會“問”而不是“猜”我最初犯的一個錯誤是給了 Agent 一個需求直接讓它開始寫代碼。結(jié)果它寫了半天我一看方向就不對。后來我才意識到問題的根源是我和 Agent 之間沒有做一個“需求對齊”的環(huán)節(jié)。Superpowers 的 brainstorming 技能就是專門解決這個問題的。它的典型執(zhí)行流程是Agent 會先根據(jù)你的初始描述拆解出它認(rèn)為需要澄清的問題然后一個一個地問你。舉個例子。我讓它開發(fā)一個“用戶積分系統(tǒng)”按照 brainstorming 技能它會先問積分獲取規(guī)則有哪些充值、消費(fèi)、簽到、邀請積分過期策略是什么永久有效還是按年度清零積分可以抵扣的訂單類型有哪幾種積分變動需要記錄明細(xì)嗎是否需要展示給用戶這些問題看著簡單但如果你直接讓 Agent 寫代碼它大概率會“幫”你拍板然后按它自己的理解實(shí)現(xiàn)。等做完了你才發(fā)現(xiàn)“這不是我要的”返工成本極高。實(shí)操心得這個階段不要嫌煩。剛開始我會覺得這些問題耽誤時間但實(shí)測下來多花 5 分鐘做需求澄清往往能省下后面幾個小時的返工時間。而且很多問題你會發(fā)現(xiàn)自己也沒想清楚Agent 幫你提前把坑踩出來這是白賺的。5.2 writing-plans把“寫代碼”變成“做工程”當(dāng)需求澄清到位后Superpowers 會引導(dǎo) Agent 生成一份執(zhí)行計劃。這個步驟對應(yīng)的是軟件開發(fā)里的“概要設(shè)計 詳細(xì)設(shè)計”。我在用 writing-plans 時感受最深的一點(diǎn)是它會要求 Agent 明確每個任務(wù)的驗(yàn)收標(biāo)準(zhǔn)。也就是說不止要寫“實(shí)現(xiàn)用戶注冊接口”這個任務(wù)還要寫清楚“注冊成功返回 200重復(fù)手機(jī)號返回 409請求參數(shù)缺失返回 400”這樣的具體標(biāo)準(zhǔn)。這樣做有兩個明顯收益。第一執(zhí)行階段不走樣。有了明確的驗(yàn)收標(biāo)準(zhǔn)Agent 在寫代碼時會自覺對照標(biāo)準(zhǔn)檢查輸出而不是“寫完了再說”。第二人工 review 有抓手。我只需要看計劃里的驗(yàn)收標(biāo)準(zhǔn)就能快速判斷 Agent 對需求的理解是否正確不需要一行行讀它的代碼。拿“用戶積分系統(tǒng)”舉例一份合格的執(zhí)行計劃大概長這樣任務(wù) 1創(chuàng)建積分流水表 驗(yàn)收標(biāo)準(zhǔn)包含用戶 ID、積分變動數(shù)量、變動類型、關(guān)聯(lián)訂單號、創(chuàng)建時間字段有索引建議。 任務(wù) 2實(shí)現(xiàn)積分變更服務(wù) 驗(yàn)收標(biāo)準(zhǔn)支持增加/扣減/凍結(jié)三種操作變動前后需要記錄余額快照并發(fā)場景下不出現(xiàn)超扣。 任務(wù) 3實(shí)現(xiàn)積分明細(xì)查詢接口 驗(yàn)收標(biāo)準(zhǔn)支持分頁支持按時間范圍過濾返回字段包含變動類型描述和時間。5.3 executing-plans讓每一步都“有據(jù)可查”計劃制定完成后就進(jìn)入了 executing-plans 階段。這個技能的核心任務(wù)是按計劃逐項(xiàng)實(shí)現(xiàn)每完成一項(xiàng)就自查一項(xiàng)。我觀察到的一個常見問題是很多人在計劃制定后會忍不住“推著” Agent 直接開干。但 executing-plans 的意義恰恰在于它讓 Agent 在每個任務(wù)完成后都停下來做一次“完成度檢查”再決定是繼續(xù)下一個任務(wù)還是回頭修復(fù)當(dāng)前任務(wù)。這里有個參數(shù)細(xì)節(jié)值得注意。Superpowers 在 executing-plans 階段默認(rèn)會要求 Agent每一項(xiàng)任務(wù)都要讀取相關(guān)文件而不是憑對話記憶寫代碼確保實(shí)現(xiàn)和當(dāng)前代碼庫的實(shí)際狀態(tài)一致。這個設(shè)計極大減少了“憑空開發(fā)”帶來的兼容性問題。我實(shí)測下來的體感是executing-plans 顯著提高了首次編碼的正確率。以前讓 Agent 寫一個跨模塊功能經(jīng)常出現(xiàn)“接口路徑和現(xiàn)有路由不匹配”“導(dǎo)入的模塊根本不存在”這類低級錯誤現(xiàn)在基本不會發(fā)生了——因?yàn)樗趫?zhí)行計劃第一步就會去讀路由文件和模塊索引。5.4 debugging從“盲猜”到“科學(xué)排查”如果說前面三個技能是“預(yù)防”那 debugging 技能就是“補(bǔ)救”。Agent 寫的代碼不可能永遠(yuǎn)一次通過但關(guān)鍵是出 bug 之后它的排查方式是否科學(xué)。傳統(tǒng)模式下Agent 看到報錯信息第一反應(yīng)是“猜一個可能的原因然后直接改代碼”。它可能試三五次還修不對反而把代碼越改越亂。Superpowers 的 debugging 技能要求 Agent 遵循一套嚴(yán)謹(jǐn)?shù)呐挪榱鞒虖?fù)現(xiàn)問題收集完整的錯誤信息。針對錯誤信息提出多個可能的原因假設(shè)。設(shè)計驗(yàn)證方法比如打日志、寫測試用例逐項(xiàng)驗(yàn)證假設(shè)。找到根因后再動手修復(fù)。修復(fù)后運(yùn)行回歸測試確認(rèn)問題沒有復(fù)發(fā)。我在實(shí)際使用中最能感受到這一套流程價值的地方是它治好了 Agent 的“急于表現(xiàn)”。以前它看到報錯就東改一榔頭西改一棒槌現(xiàn)在它會老老實(shí)實(shí)先復(fù)現(xiàn)、再假設(shè)、再驗(yàn)證每個步驟都有章法debug 效率反而高了很多。6. 一個真實(shí)案例從“自由發(fā)揮”到“規(guī)范交付”的完整變化說了這么多概念我把最近一個實(shí)戰(zhàn)項(xiàng)目拿出來拆解一遍。我最近在給團(tuán)隊(duì)內(nèi)部做一個輕量級的“任務(wù)管理系統(tǒng)”需要對接企業(yè)微信的通知推送。放到以前我可能會直接把需求甩給 Claude讓它放手寫。這次我用了一套完整流程來約束它。6.1 從需求到計劃的完整鏈路我先用 brainstorming 讓 Agent 幫我澄清需求。它問了大概 8 個問題其中最關(guān)鍵的三個是任務(wù)狀態(tài)流轉(zhuǎn)的規(guī)則是什么待辦→進(jìn)行中→已完成還是允許跳過企業(yè)微信推送是每次變更都推還是只在關(guān)鍵狀態(tài)推任務(wù)的優(yōu)先級是固定死還是允許用戶自定義這三個問題直接影響了后面的建表設(shè)計、消息模板設(shè)計和接口設(shè)計。如果我沒做這一步Agent 大概率會按一個“看起來合理”的方案去實(shí)現(xiàn)然后做出來的東西就不符合團(tuán)隊(duì)的運(yùn)營習(xí)慣。需求對齊之后我用 writing-plans 讓 Agent 生成執(zhí)行計劃。它列出了 6 個任務(wù)每個都有明確的驗(yàn)收標(biāo)準(zhǔn)。我逐條 review發(fā)現(xiàn)它對“任務(wù)關(guān)閉后是否允許重新打開”這個業(yè)務(wù)規(guī)則理解有偏差在計劃階段就糾正了避免了一次返工。6.2 執(zhí)行階段的“四步驗(yàn)證法”在 executing-plans 階段我觀察到 Agent 的行為模式發(fā)生了明顯變化。以前它會連續(xù)寫十幾個文件然后告訴你“完成了”這次它每完成一個任務(wù)都會停下來做四件事讀取相關(guān)文件確認(rèn)代碼和現(xiàn)有邏輯兼容。檢查是否有測試可以運(yùn)行來驗(yàn)證改動。對照驗(yàn)收標(biāo)準(zhǔn)逐項(xiàng)自檢。匯報完成情況等待我確認(rèn)后再進(jìn)入下一個任務(wù)。整個過程下來我沒有一次“中途叫停”的經(jīng)歷。這在以前幾乎是不可能的——以前用對話式 AI 寫項(xiàng)目我平均每次都要打斷它兩三次因?yàn)榉较蚱嘶蛘邔?shí)現(xiàn)方式和現(xiàn)有代碼沖突。6.3 實(shí)測下來的量化對比我這里沒有做嚴(yán)格的雙盲實(shí)驗(yàn)但憑實(shí)際操作體感做一個量化對比供參考維度無 Superpowers使用 Superpowers從需求到計劃的耗時10 分鐘25 分鐘在計劃階段發(fā)現(xiàn)的語義錯誤0-1 個3-4 個首輪編碼通過率指邏輯正確約 40%約 80%中途需要人工干預(yù)的次數(shù)3-5 次0-1 次最終代碼 review 需要修的細(xì)節(jié)較多明顯減少數(shù)據(jù)僅供參考。我的核心體感是前期多花的時間非常值因?yàn)樗选胺倒こ杀尽鞭D(zhuǎn)移成了“規(guī)劃成本”而規(guī)劃成本比返工成本低得多。6.4 需要提前準(zhǔn)備的工作把 OpenSpec 加進(jìn)來如果你決定用三件套我的建議是先把 OpenSpec 的 spec 文檔寫好再讓 Superpowers 干活。實(shí)際順序是用 OpenSpec 定義需求文檔和驗(yàn)收標(biāo)準(zhǔn)。在 Claude Code 里加載對應(yīng) spec讓 Agent 明確“完成”的定義。用 Superpowers 的 brainstorming 做需求澄清。用 writing-plans 做計劃拆解。用 executing-plans 按計劃執(zhí)行。每個階段結(jié)束都有產(chǎn)出物不管是一個文檔、一份計劃還是幾個文件方便你 review。這套組合下來AI 編程從一個“黑箱”變成了一個“有中間產(chǎn)物、有檢查點(diǎn)、可 review、可回滾”的工程流程。這才是“工程規(guī)范”的真實(shí)含義。7. 常見問題與避坑實(shí)錄我踩過的坑和解決方案7.1 新項(xiàng)目從零開始 vs 存量項(xiàng)目改造策略不同用 Superpowers 在一個全新項(xiàng)目上開始體感是最好的——因?yàn)闆]有歷史包袱所有流程都能順暢執(zhí)行。但大部分人的實(shí)際情況是手里有一堆存量項(xiàng)目。我的建議是存量項(xiàng)目不要一上來就全流程改造。先挑一個功能模塊做試點(diǎn)用 brainstorming writing-plans 把計劃做出來讓 Agent 按計劃執(zhí)行對比一下和以前“直接讓它寫”的效果差異。等這套流程在新模塊上跑順了再逐步擴(kuò)展到全局。我試過把一個維護(hù)了一年多的老項(xiàng)目直接套三件套結(jié)果 Agent 在建計劃階段就被老項(xiàng)目的復(fù)雜依賴?yán)@暈了產(chǎn)出的計劃質(zhì)量很差。后來改成小步試點(diǎn)情況才好轉(zhuǎn)。7.2 模型選型的差異Claude 和國產(chǎn)模型的表現(xiàn)很多人在問“這種東西在國產(chǎn)模型上能用嗎”我實(shí)測下來的判斷是能跑但體驗(yàn)有差距。Superpowers 本身是純文本技能文件任何支持長上下文和工具調(diào)用的模型都能讀取。但實(shí)際效果取決于模型“遵循指令”的能力。Claude 系模型如 Opus、Sonnet在遵循復(fù)雜多步指令方面表現(xiàn)最穩(wěn)定部分國產(chǎn)模型在簡單的單步任務(wù)上沒問題但在多步驟、多層嵌套的流程執(zhí)行中偶爾會跳步或簡化流程。如果你用的是國產(chǎn)模型我的建議是先跑最核心的 brainstorming 和 writing-plans 兩個技能把需求對齊和計劃拆解這兩步抓好執(zhí)行環(huán)節(jié)可以讓模型自由度高一點(diǎn)。等模型能力迭代了再逐步放開。7.3 token 消耗明顯上升這是正常現(xiàn)象用了這套流程后很多人第一個感受就是“怎么 token 用得這么快”。這很正常。brainstorming 階段要多輪問答writing-plans 階段要生成完整計劃文檔executing-plans 階段每步還要讀文件自查——這些都要消耗 token。我的經(jīng)驗(yàn)是不要因?yàn)?token 消耗大就跳過規(guī)劃階段。你算一筆賬規(guī)劃階段多花的 token 成本通常遠(yuǎn)低于一次錯誤實(shí)現(xiàn)帶來的返工成本。時間才是更貴的資源。如果你真的想省 token可以把 brainstorming 的問題改成語義更緊湊的表述或者限定 Agent“最多問 5 個最核心的問題”。7.4 技能不生效先檢查這五個位置我遇到過一次“技能完全沒生效”的情況排查下來發(fā)現(xiàn)是技能目錄放錯了位置。如果你也遇到技能不生效的問題按這個順序排查技能文件是否放在了工具認(rèn)可的目錄Claude Code 是~/.claude/skills/Cursor 是.cursor/skills/。技能文件名是否為SKILL.md有些工具只識別特定命名。當(dāng)前對話是否有足夠的上下文窗口加載技能文件窗口太小可能會截斷。是否在對話中正確喚起了技能輸入superpowers或?qū)?yīng)的子技能。模型是否拒絕遵循技能文件中的指令某些安全對齊較強(qiáng)的模型會拒絕“按文件執(zhí)行”這類指令。實(shí)操心得如果第 5 條發(fā)生最有效的辦法是換模型或者把技能文件的關(guān)鍵步驟直接粘貼到對話里。我遇到過幾次模型對“多步驟指令文件”有保留的情況直接把核心步驟復(fù)制到對話上下文里就解決了。7.5 別把技能當(dāng)銀彈質(zhì)量上限還是要靠“人”最后說一個容易被忽略的點(diǎn)。Superpowers 解決的問題是“質(zhì)量下限”——它保證 Agent 不會亂來不會跳過關(guān)鍵步驟不會在沒澄清需求之前就動手。但它解決不了“質(zhì)量上限”——Agent 的最終產(chǎn)出質(zhì)量還是受限于模型能力和你的需求描述質(zhì)量。我見過有人用 Superpowers 之后以為可以完全放手了結(jié)果代碼質(zhì)量還是沒有達(dá)到預(yù)期因此跑來吐槽“這套東西沒用”。其實(shí)這里有一個被忽略的事實(shí)工具約束的是流程人提供的是方向。如果你自己都不清楚需求到底要什么再強(qiáng)的技能系統(tǒng)也幫你做不出一個沒想清楚的東西。用 Superpowers 前后我最大的心態(tài)變化是從“寫完代碼再檢查”變成了“寫之前先對齊”。對齊需求、對齊計劃、對齊驗(yàn)收標(biāo)準(zhǔn)——這個過程看著多了幾個步驟實(shí)際上每一分鐘都是花在刀刃上的。8. 擴(kuò)展思路和后續(xù)玩法8.1 自己定制團(tuán)隊(duì)專屬 SkillSuperpowers 是開源的這意味著你可以基于它定制適合自己團(tuán)隊(duì)的技能。比如團(tuán)隊(duì)有統(tǒng)一的代碼風(fēng)格規(guī)范、數(shù)據(jù)庫設(shè)計規(guī)范、接口命名規(guī)范都可以寫成一個新的 SKILL.md 文件讓 Agent 在開發(fā)時自動遵守。我目前就在維護(hù)兩個團(tuán)隊(duì)內(nèi)部技能一個是“數(shù)據(jù)庫遷移規(guī)范”要求 Agent 在涉及數(shù)據(jù)庫改動時先檢查是否有破壞性變更另一個是“接口兼容性檢查”要求在修改接口時自動檢查現(xiàn)有調(diào)用方是否受影響。這兩個技能極大地減少了團(tuán)隊(duì)內(nèi)的低級 review 意見。8.2 與 CI/CD 流程結(jié)合另一個可以玩的方向是把 Superpowers 的產(chǎn)物比如計劃文檔、檢查清單接入 CI/CD 流程。比如要求每次 MR 必須附帶 writing-plans 生成的驗(yàn)收標(biāo)準(zhǔn)清單CI 自動檢查這些清單是否被滿足。這相當(dāng)于把一個“約束 Agent 行為”的機(jī)制升級成了“約束團(tuán)隊(duì)協(xié)作流程”的機(jī)制。老實(shí)講我在這個方向的嘗試還比較淺但我認(rèn)為它對技術(shù)管理的價值潛力很大。畢竟 AI 編程的終局不是“一個人用 AI 寫代碼”而是**“一個團(tuán)隊(duì)用一套標(biāo)準(zhǔn)來使用 AI 寫代碼”**。8.3 多 Agent 協(xié)作場景下的紀(jì)律保證最后提一下多 Agent 協(xié)作。現(xiàn)在 Agent 框架越來越流行一個系統(tǒng)里可能會有多個 Agent 協(xié)同工作。如果沒有統(tǒng)一的技能體系約束每個 Agent 都按自己的偏好發(fā)揮協(xié)調(diào)成本會非常高。Superpowers 這類技能體系的價值在這里會被進(jìn)一步放大——它提供了一種“團(tuán)隊(duì)共同語言”讓不同 Agent 在執(zhí)行同一類任務(wù)時行為模式保持一致。我自己在做 agent 框架方案設(shè)計時已經(jīng)把技能體系作為架構(gòu)的一部分納入了。它不會直接決定 Agent 做什么但它決定了 Agent 做事的“行為基線”而行為基線正是一個團(tuán)隊(duì)能夠協(xié)作的前提。我個人的建議是不要把它當(dāng)成一個“插件”而是當(dāng)成一套“流程資產(chǎn)”來經(jīng)營。前期花一點(diǎn)時間熟悉、定制、沉淀后面每個使用 AI 編程的人都能穩(wěn)定從這套資產(chǎn)里獲益。 用Superpowers為AI編程立規(guī)矩：從自由發(fā)揮到規(guī)范交付
1. AI 寫代碼不缺能力缺的是“邊界感”先講一個我上個月的真實(shí)經(jīng)歷。當(dāng)時我用 Claude 寫一個內(nèi)部工具的后端接口需求很簡單從第三方服務(wù)拉取數(shù)據(jù)、清洗、落庫、給前端返回分頁結(jié)果。我把需求描述得足夠清楚模型也給出了看起來非常合理的實(shí)現(xiàn)。結(jié)果代碼 review 的時候我發(fā)現(xiàn)它在沒有任何提示的情況下自作主張給數(shù)據(jù)庫表加了兩個索引、引入了一個自己覺得“更好”的 ORM 方法、還把分頁參數(shù)從 offset/limit 改成了 cursor 風(fēng)格。單看每一處改動單獨(dú)拎出來可能都算合理優(yōu)化。但放在一個團(tuán)隊(duì)項(xiàng)目里這種“自由發(fā)揮”就是災(zāi)難——你沒有跟別人對齊就動表結(jié)構(gòu)輕則埋坑重則直接影響到上下游服務(wù)的契約。這其實(shí)就是現(xiàn)在 AI 編程最核心的痛點(diǎn)模型本身的能力已經(jīng)不是瓶頸瓶頸是它沒有工程紀(jì)律。它像一個能力很強(qiáng)但沒有受過職業(yè)訓(xùn)練的新人你讓它“寫個模塊”它恨不得把整個架構(gòu)都重構(gòu)了。你讓它“改個 bug”它能順手把旁邊的文件也格式化一遍。后來我開始系統(tǒng)性使用 Superpowers 這套 skills 體系來約束 Agent 行為配合 Claude Code 和 OpenSpec 一起用實(shí)測下來效果非常明顯。這篇文章我就把完整的思路、安裝方法、核心技能拆解和實(shí)戰(zhàn)記錄分享出來希望能幫到在 AI 編程里被“失控感”困擾的人。尤其適合這幾類人參考正在用 Cursor、Windsurf、Claude Code 做全棧項(xiàng)目的開發(fā)者想給團(tuán)隊(duì)引入統(tǒng)一 AI 編碼規(guī)范的技術(shù)負(fù)責(zé)人以及被 Agent 生成的“一次性代碼”搞到不敢合并 PR 的人。2. 先搞懂一個關(guān)鍵問題Agent 為什么總愛“自由發(fā)揮”2.1 失控的根源LLM 天然是“接龍機(jī)器”拋開所有花哨的概念大模型本質(zhì)上是“根據(jù)上文預(yù)測下文”的統(tǒng)計模型。它沒有“項(xiàng)目全局觀”也沒有“穩(wěn)定的長期記憶”。每生成一個 token它都在做同一件事猜測“接下來最應(yīng)該出現(xiàn)的字符是什么”。這就帶來兩個致命問題。第一模型沒有工作流意識。它不知道“先寫測試再寫實(shí)現(xiàn)”和“先寫實(shí)現(xiàn)再補(bǔ)測試”有什么區(qū)別更不知道“先確認(rèn)需求再動手”和“邊寫邊猜”哪個更穩(wěn)妥。它只會根據(jù) prompt 里的信息用最省力的路徑生成內(nèi)容。你讓它“寫一個登錄接口”它就直接開始寫接口代碼完全不會考慮“這個接口跟現(xiàn)有用戶系統(tǒng)的關(guān)系是什么”。第二模型的輸出傾向是“補(bǔ)完”而不是“執(zhí)行”。你給它一個需求它會傾向于生成一個“看起來完整”的方案而不是“執(zhí)行當(dāng)前就需要的部分”。所以你會看到它瘋狂給自己加戲——補(bǔ)你沒提的參數(shù)校驗(yàn)、加它認(rèn)為需要的索引、重構(gòu)它覺得不優(yōu)雅的代碼這些都是“補(bǔ)完傾向”的體現(xiàn)。我用一個生活化的類比來解釋普通對話式 AI 像一個反應(yīng)很快的實(shí)習(xí)生你說什么它都能接上但你不盯著它它就會按自己的喜好干活。Superpowers 的作用是給這個實(shí)習(xí)生發(fā)一本厚厚的工作手冊上面寫清楚接到任務(wù)第一步干什么、第二步干什么、什么情況下需要停下來問人、什么情況下可以自己做主。2.2 傳統(tǒng) prompt 為什么解決不了這個問題很多人嘗試用“超級 prompt”來約束 Agent。我也試過。比如在系統(tǒng)提示詞里寫“你必須遵循以下步驟1. 理解需求 2. 搜索代碼 3. 制定計劃 4. 執(zhí)行計劃 5. 自測”。問題在于Prompt 是靜態(tài)文本而 Agent 的執(zhí)行是動態(tài)過程。你寫了一大段規(guī)則模型在開始階段確實(shí)會遵循但一旦對話輪次變長、上下文變復(fù)雜這些規(guī)則就會被稀釋、遺忘、甚至被后續(xù)內(nèi)容覆蓋。舉個很具體的例子。我在 Cursor 里用過一個很長的系統(tǒng)提示詞要求 AI 每次改動前先讀相關(guān)文件。前兩輪對話它確實(shí)照做了。到了第五輪我問它“順便把這個按鈕的顏色改一下”它直接就改代碼完全跳過了“讀文件”這個步驟。原因很簡單——模型認(rèn)為“改顏色”是個簡單任務(wù)沒必要走完整流程。所以問題不是 prompt 寫得不夠長而是prompt 沒有把“流程”固化成“能力”。你需要的不是一段寫在系統(tǒng)提示詞里的文本而是一套能被 Agent 主動識別、主動調(diào)用、按步驟執(zhí)行的技能模塊。2.3 Superpowers 的解法把流程變成“技能包”Superpowers 的核心理念就是把軟件開發(fā)中的高頻工作流——頭腦風(fēng)暴、任務(wù)拆解、計劃執(zhí)行、調(diào)試排錯、提交信息規(guī)范——封裝成一個個獨(dú)立的技能文件。每個技能包含完整的操作步驟、指標(biāo)定義、執(zhí)行規(guī)則和自查清單。它的工作機(jī)制是你在對話里用一個特定語法比如 superpowers 或 brainstorming喚起對應(yīng)技能Agent 就會按技能文件里的步驟執(zhí)行。這跟普通 prompt 最大的區(qū)別在于——技能文件是在執(zhí)行時動態(tài)加載的不會占用你寶貴的上下文窗口也不會被后續(xù)對話稀釋。我更愿意把它理解成一套**“工程級的行為規(guī)范系統(tǒng)”**不改變模型的推理能力只約束模型的做事方式。就像圍棋高手不是靠“背規(guī)則”贏棋而是靠“行棋規(guī)范”保證每步棋的質(zhì)量下限。Superpowers 要保證的就是 AI 每次動手寫代碼的“質(zhì)量下限”。2.4 Superpowers 和 OpenSpec 的分工一個管“怎么干活”一個管“干什么活”很多人在了解 Superpowers 時會同時聽到另一個名詞OpenSpec。這兩個工具經(jīng)常被一起推薦但它們的定位完全不同。簡單來說Superpowers 管的是“怎么干活”——怎么分析需求、怎么拆解任務(wù)、怎么按計劃執(zhí)行、怎么系統(tǒng)化調(diào)試。它約束的是 Agent 的行為方式。OpenSpec 管的是“干什么活”——它定義了一套需求描述規(guī)范把需求拆成帶有明確驗(yàn)收標(biāo)準(zhǔn)的 spec 文檔讓 Agent 在動手前先明確“完成”的定義。它約束的是 Agent 的工作對象。打個比方Superpowers 是工作流程手冊O(shè)penSpec 是項(xiàng)目需求清單。有了流程手冊但清單不清晰Agent 會高效地做錯事有了清晰清單但沒有流程約束Agent 會自由發(fā)揮到讓你崩潰。兩者配合使用才是完整方案——這也是“Claude Code OpenSpec Superpowers 三件套”這個詞會流行的原因。3. Superpowers 到底包含哪些技能核心模塊梳理項(xiàng)目本身是一個開源的 skills 集合完整內(nèi)容在 GitHub 上。我建議你拿到手之后先做一個整體瀏覽搞清楚每個 skill 大概負(fù)責(zé)什么場景不然真到實(shí)戰(zhàn)時你都不知道該喚起哪個。3.1 核心工作流技能戰(zhàn)艦版本的“主炮”技能名稱定位核心作用brainstorming需求分析在和 Agent 對話中澄清需求、探索方案、識別風(fēng)險writing-plans計劃制定把需求拆解成有依賴關(guān)系、驗(yàn)收標(biāo)準(zhǔn)的執(zhí)行計劃executing-plans計劃執(zhí)行按計劃逐項(xiàng)實(shí)現(xiàn)每完成一項(xiàng)就檢查一項(xiàng)debugging系統(tǒng)調(diào)試用“提出假設(shè)、驗(yàn)證假設(shè)”的方法定位并修復(fù) bug這四個技能是整套體系的骨架。它們對應(yīng)的是軟件開發(fā)中最基礎(chǔ)的四個階段理解需求、制定方案、執(zhí)行方案、修復(fù)問題。沒有這套流程Agent 的所有輸出都是“即興發(fā)揮”有了這套流程Agent 的每一步都有章可循。3.2 輔助技能讓工程規(guī)范更完整的“零件”除了四大核心技能Superpowers 還附帶了一些輔助技能我實(shí)際使用下來覺得價值也非常高writing-commits約束 Agent 寫規(guī)范的 Git 提交信息避免出現(xiàn)“fix stuff”“update code”這類毫無信息量的提交。checklists讓 Agent 在任務(wù)完成前生成檢查清單并逐項(xiàng)自查相當(dāng)于模擬人工 Code Review 的第一道閘門。TDD測試驅(qū)動開發(fā)相關(guān)技能約束 Agent 按“先寫測試、再寫實(shí)現(xiàn)、最后重構(gòu)”的順序開發(fā)。spec-generation結(jié)合 OpenSpec 使用將需求文檔自動轉(zhuǎn)化為帶驗(yàn)收標(biāo)準(zhǔn)的規(guī)格說明。3.3 skill 和 agent 到底有什么區(qū)別這個關(guān)鍵詞挺熱的經(jīng)常有人混淆。我在使用中總結(jié)了一個最簡單的區(qū)分方式Agent 是“執(zhí)行體”Skill 是“能力包”。Agent 負(fù)責(zé)調(diào)用模型、管理上下文、執(zhí)行動作比如讀寫文件、運(yùn)行命令Skill 是給 Agent 提供的“操作手冊”告訴它某類任務(wù)應(yīng)該按什么步驟來做。類比一下Agent 是廚師本人Skill 是菜譜。沒有廚師菜譜只是一堆紙沒有菜譜廚師只能憑經(jīng)驗(yàn)自由發(fā)揮。Agent 的靈活性和 Skill 的規(guī)范性結(jié)合才能穩(wěn)定地產(chǎn)出高質(zhì)量的代碼。4. 安裝與配置全流程Claude Code / Cursor / Windsurf 一次講清4.1 整體安裝思路三個步驟搞定Superpowers 的安裝邏輯很簡單把技能文件克隆到本地再讓 AI 編程工具能讀取這些文件。不涉及編譯、不涉及復(fù)雜的依賴關(guān)系本質(zhì)上就是“放文件”和“告訴工具去哪找文件”這兩件事。不同工具的讀取方式不太一樣Claude Code通過skills命令直接在 CLI 里添加。Cursor / Windsurf需要在項(xiàng)目根目錄或全局.cursor/skills目錄下放置技能文件。OpenCode 等開源工具按各自約定的 skills 目錄放置即可。我的建議是先從 Claude Code 入手因?yàn)樗?skills 機(jī)制最成熟社區(qū)案例最多。等你熟悉了技能文件的結(jié)構(gòu)再遷移到其他工具就很輕松了。4.2 Claude Code 下的完整安裝步驟Claude Code 的安裝算是三種工具里最順暢的。打開終端執(zhí)行以下命令# 先進(jìn)入 Claude Code 的配置目錄 cd ~/.claude # 查看當(dāng)前可用的 skills 命令 claude skills如果你是第一次安裝需要先初始化 skills 目錄。然后從 GitHub 拉取 Superpowers 項(xiàng)目git clone https://github.com/obra/superpowers.git # 用 Claude Code 自帶的 skills 命令添加技能 claude skills add superpowers這里有個細(xì)節(jié)我要特別強(qiáng)調(diào)不同版本的 Claude Code 命令略有差異。老版本可能沒有skills add子命令需要手動把技能目錄鏈接或復(fù)制到~/.claude/skills/下。我的建議是先跑一下claude --version確認(rèn)版本再對照官方文檔操作。安裝完成后在 Claude Code 里輸入superpowers如果能正常喚起技能列表就說明安裝成功了。4.3 Cursor / Windsurf 下的安裝方式如果你主要在 Cursor 或 Windsurf 里工作安裝思路稍微不同。這兩個工具沒有類似claude skills的命令行入口需要手動放置技能目錄。以 Cursor 為例# 進(jìn)入你的項(xiàng)目目錄 cd your-project # 創(chuàng)建 .cursor/skills 目錄 mkdir -p .cursor/skills # 克隆 Superpowers 到該目錄 git clone https://github.com/obra/superpowers.git .cursor/skills/superpowers克隆完成后你在 Cursor 的對話里用superpowers或直接提到相關(guān)技能名比如 brainstorming它就能讀取到技能內(nèi)容。我在實(shí)際使用中有一個小經(jīng)驗(yàn)Cursor 直接引用子技能的成功率更高。比如我輸入brainstorming往往比輸入superpowers更穩(wěn)定原因是 Cursor 對嵌套目錄里的文件識別可能會有遺漏。所以我會在.cursor/skills/下創(chuàng)建一個SKILL.md索引文件把常用技能的名字和路徑列清楚這樣 Agent 找不到的時候還能看一眼索引。4.4 驗(yàn)證安裝是否成功一個 30 秒自測方法裝完之后別急著開工先做一個快速驗(yàn)證。我在第一次安裝時就踩過“以為自己裝好了結(jié)果根本沒生效”的坑。進(jìn)入你的 AI 編程工具輸入這樣一句話請列出你當(dāng)前可用的所有 skills并簡要說明每個 skill 的用途。如果安裝成功Agent 會列出 superpowers 相關(guān)技能的清單和說明。如果它回答“我沒有 skills”或者答非所問說明技能文件沒有被正確讀取。還有一個更直接的方法直接輸入brainstorming或者writing-plans如果 Agent 開始按技能里的步驟引導(dǎo)你提問說明它已經(jīng)成功加載了技能內(nèi)容。5. 核心技能實(shí)戰(zhàn)拆解Superpowers 是怎么讓 Agent“守規(guī)矩”的5.1 brainstorming讓 Agent先學(xué)會“問”而不是“猜”我最初犯的一個錯誤是給了 Agent 一個需求直接讓它開始寫代碼。結(jié)果它寫了半天我一看方向就不對。后來我才意識到問題的根源是我和 Agent 之間沒有做一個“需求對齊”的環(huán)節(jié)。Superpowers 的 brainstorming 技能就是專門解決這個問題的。它的典型執(zhí)行流程是Agent 會先根據(jù)你的初始描述拆解出它認(rèn)為需要澄清的問題然后一個一個地問你。舉個例子。我讓它開發(fā)一個“用戶積分系統(tǒng)”按照 brainstorming 技能它會先問積分獲取規(guī)則有哪些充值、消費(fèi)、簽到、邀請積分過期策略是什么永久有效還是按年度清零積分可以抵扣的訂單類型有哪幾種積分變動需要記錄明細(xì)嗎是否需要展示給用戶這些問題看著簡單但如果你直接讓 Agent 寫代碼它大概率會“幫”你拍板然后按它自己的理解實(shí)現(xiàn)。等做完了你才發(fā)現(xiàn)“這不是我要的”返工成本極高。實(shí)操心得這個階段不要嫌煩。剛開始我會覺得這些問題耽誤時間但實(shí)測下來多花 5 分鐘做需求澄清往往能省下后面幾個小時的返工時間。而且很多問題你會發(fā)現(xiàn)自己也沒想清楚Agent 幫你提前把坑踩出來這是白賺的。5.2 writing-plans把“寫代碼”變成“做工程”當(dāng)需求澄清到位后Superpowers 會引導(dǎo) Agent 生成一份執(zhí)行計劃。這個步驟對應(yīng)的是軟件開發(fā)里的“概要設(shè)計 詳細(xì)設(shè)計”。我在用 writing-plans 時感受最深的一點(diǎn)是它會要求 Agent 明確每個任務(wù)的驗(yàn)收標(biāo)準(zhǔn)。也就是說不止要寫“實(shí)現(xiàn)用戶注冊接口”這個任務(wù)還要寫清楚“注冊成功返回 200重復(fù)手機(jī)號返回 409請求參數(shù)缺失返回 400”這樣的具體標(biāo)準(zhǔn)。這樣做有兩個明顯收益。第一執(zhí)行階段不走樣。有了明確的驗(yàn)收標(biāo)準(zhǔn)Agent 在寫代碼時會自覺對照標(biāo)準(zhǔn)檢查輸出而不是“寫完了再說”。第二人工 review 有抓手。我只需要看計劃里的驗(yàn)收標(biāo)準(zhǔn)就能快速判斷 Agent 對需求的理解是否正確不需要一行行讀它的代碼。拿“用戶積分系統(tǒng)”舉例一份合格的執(zhí)行計劃大概長這樣任務(wù) 1創(chuàng)建積分流水表 驗(yàn)收標(biāo)準(zhǔn)包含用戶 ID、積分變動數(shù)量、變動類型、關(guān)聯(lián)訂單號、創(chuàng)建時間字段有索引建議。 任務(wù) 2實(shí)現(xiàn)積分變更服務(wù) 驗(yàn)收標(biāo)準(zhǔn)支持增加/扣減/凍結(jié)三種操作變動前后需要記錄余額快照并發(fā)場景下不出現(xiàn)超扣。 任務(wù) 3實(shí)現(xiàn)積分明細(xì)查詢接口 驗(yàn)收標(biāo)準(zhǔn)支持分頁支持按時間范圍過濾返回字段包含變動類型描述和時間。5.3 executing-plans讓每一步都“有據(jù)可查”計劃制定完成后就進(jìn)入了 executing-plans 階段。這個技能的核心任務(wù)是按計劃逐項(xiàng)實(shí)現(xiàn)每完成一項(xiàng)就自查一項(xiàng)。我觀察到的一個常見問題是很多人在計劃制定后會忍不住“推著” Agent 直接開干。但 executing-plans 的意義恰恰在于它讓 Agent 在每個任務(wù)完成后都停下來做一次“完成度檢查”再決定是繼續(xù)下一個任務(wù)還是回頭修復(fù)當(dāng)前任務(wù)。這里有個參數(shù)細(xì)節(jié)值得注意。Superpowers 在 executing-plans 階段默認(rèn)會要求 Agent每一項(xiàng)任務(wù)都要讀取相關(guān)文件而不是憑對話記憶寫代碼確保實(shí)現(xiàn)和當(dāng)前代碼庫的實(shí)際狀態(tài)一致。這個設(shè)計極大減少了“憑空開發(fā)”帶來的兼容性問題。我實(shí)測下來的體感是executing-plans 顯著提高了首次編碼的正確率。以前讓 Agent 寫一個跨模塊功能經(jīng)常出現(xiàn)“接口路徑和現(xiàn)有路由不匹配”“導(dǎo)入的模塊根本不存在”這類低級錯誤現(xiàn)在基本不會發(fā)生了——因?yàn)樗趫?zhí)行計劃第一步就會去讀路由文件和模塊索引。5.4 debugging從“盲猜”到“科學(xué)排查”如果說前面三個技能是“預(yù)防”那 debugging 技能就是“補(bǔ)救”。Agent 寫的代碼不可能永遠(yuǎn)一次通過但關(guān)鍵是出 bug 之后它的排查方式是否科學(xué)。傳統(tǒng)模式下Agent 看到報錯信息第一反應(yīng)是“猜一個可能的原因然后直接改代碼”。它可能試三五次還修不對反而把代碼越改越亂。Superpowers 的 debugging 技能要求 Agent 遵循一套嚴(yán)謹(jǐn)?shù)呐挪榱鞒虖?fù)現(xiàn)問題收集完整的錯誤信息。針對錯誤信息提出多個可能的原因假設(shè)。設(shè)計驗(yàn)證方法比如打日志、寫測試用例逐項(xiàng)驗(yàn)證假設(shè)。找到根因后再動手修復(fù)。修復(fù)后運(yùn)行回歸測試確認(rèn)問題沒有復(fù)發(fā)。我在實(shí)際使用中最能感受到這一套流程價值的地方是它治好了 Agent 的“急于表現(xiàn)”。以前它看到報錯就東改一榔頭西改一棒槌現(xiàn)在它會老老實(shí)實(shí)先復(fù)現(xiàn)、再假設(shè)、再驗(yàn)證每個步驟都有章法debug 效率反而高了很多。6. 一個真實(shí)案例從“自由發(fā)揮”到“規(guī)范交付”的完整變化說了這么多概念我把最近一個實(shí)戰(zhàn)項(xiàng)目拿出來拆解一遍。我最近在給團(tuán)隊(duì)內(nèi)部做一個輕量級的“任務(wù)管理系統(tǒng)”需要對接企業(yè)微信的通知推送。放到以前我可能會直接把需求甩給 Claude讓它放手寫。這次我用了一套完整流程來約束它。6.1 從需求到計劃的完整鏈路我先用 brainstorming 讓 Agent 幫我澄清需求。它問了大概 8 個問題其中最關(guān)鍵的三個是任務(wù)狀態(tài)流轉(zhuǎn)的規(guī)則是什么待辦→進(jìn)行中→已完成還是允許跳過企業(yè)微信推送是每次變更都推還是只在關(guān)鍵狀態(tài)推任務(wù)的優(yōu)先級是固定死還是允許用戶自定義這三個問題直接影響了后面的建表設(shè)計、消息模板設(shè)計和接口設(shè)計。如果我沒做這一步Agent 大概率會按一個“看起來合理”的方案去實(shí)現(xiàn)然后做出來的東西就不符合團(tuán)隊(duì)的運(yùn)營習(xí)慣。需求對齊之后我用 writing-plans 讓 Agent 生成執(zhí)行計劃。它列出了 6 個任務(wù)每個都有明確的驗(yàn)收標(biāo)準(zhǔn)。我逐條 review發(fā)現(xiàn)它對“任務(wù)關(guān)閉后是否允許重新打開”這個業(yè)務(wù)規(guī)則理解有偏差在計劃階段就糾正了避免了一次返工。6.2 執(zhí)行階段的“四步驗(yàn)證法”在 executing-plans 階段我觀察到 Agent 的行為模式發(fā)生了明顯變化。以前它會連續(xù)寫十幾個文件然后告訴你“完成了”這次它每完成一個任務(wù)都會停下來做四件事讀取相關(guān)文件確認(rèn)代碼和現(xiàn)有邏輯兼容。檢查是否有測試可以運(yùn)行來驗(yàn)證改動。對照驗(yàn)收標(biāo)準(zhǔn)逐項(xiàng)自檢。匯報完成情況等待我確認(rèn)后再進(jìn)入下一個任務(wù)。整個過程下來我沒有一次“中途叫停”的經(jīng)歷。這在以前幾乎是不可能的——以前用對話式 AI 寫項(xiàng)目我平均每次都要打斷它兩三次因?yàn)榉较蚱嘶蛘邔?shí)現(xiàn)方式和現(xiàn)有代碼沖突。6.3 實(shí)測下來的量化對比我這里沒有做嚴(yán)格的雙盲實(shí)驗(yàn)但憑實(shí)際操作體感做一個量化對比供參考維度無 Superpowers使用 Superpowers從需求到計劃的耗時10 分鐘25 分鐘在計劃階段發(fā)現(xiàn)的語義錯誤0-1 個3-4 個首輪編碼通過率指邏輯正確約 40%約 80%中途需要人工干預(yù)的次數(shù)3-5 次0-1 次最終代碼 review 需要修的細(xì)節(jié)較多明顯減少數(shù)據(jù)僅供參考。我的核心體感是前期多花的時間非常值因?yàn)樗选胺倒こ杀尽鞭D(zhuǎn)移成了“規(guī)劃成本”而規(guī)劃成本比返工成本低得多。6.4 需要提前準(zhǔn)備的工作把 OpenSpec 加進(jìn)來如果你決定用三件套我的建議是先把 OpenSpec 的 spec 文檔寫好再讓 Superpowers 干活。實(shí)際順序是用 OpenSpec 定義需求文檔和驗(yàn)收標(biāo)準(zhǔn)。在 Claude Code 里加載對應(yīng) spec讓 Agent 明確“完成”的定義。用 Superpowers 的 brainstorming 做需求澄清。用 writing-plans 做計劃拆解。用 executing-plans 按計劃執(zhí)行。每個階段結(jié)束都有產(chǎn)出物不管是一個文檔、一份計劃還是幾個文件方便你 review。這套組合下來AI 編程從一個“黑箱”變成了一個“有中間產(chǎn)物、有檢查點(diǎn)、可 review、可回滾”的工程流程。這才是“工程規(guī)范”的真實(shí)含義。7. 常見問題與避坑實(shí)錄我踩過的坑和解決方案7.1 新項(xiàng)目從零開始 vs 存量項(xiàng)目改造策略不同用 Superpowers 在一個全新項(xiàng)目上開始體感是最好的——因?yàn)闆]有歷史包袱所有流程都能順暢執(zhí)行。但大部分人的實(shí)際情況是手里有一堆存量項(xiàng)目。我的建議是存量項(xiàng)目不要一上來就全流程改造。先挑一個功能模塊做試點(diǎn)用 brainstorming writing-plans 把計劃做出來讓 Agent 按計劃執(zhí)行對比一下和以前“直接讓它寫”的效果差異。等這套流程在新模塊上跑順了再逐步擴(kuò)展到全局。我試過把一個維護(hù)了一年多的老項(xiàng)目直接套三件套結(jié)果 Agent 在建計劃階段就被老項(xiàng)目的復(fù)雜依賴?yán)@暈了產(chǎn)出的計劃質(zhì)量很差。后來改成小步試點(diǎn)情況才好轉(zhuǎn)。7.2 模型選型的差異Claude 和國產(chǎn)模型的表現(xiàn)很多人在問“這種東西在國產(chǎn)模型上能用嗎”我實(shí)測下來的判斷是能跑但體驗(yàn)有差距。Superpowers 本身是純文本技能文件任何支持長上下文和工具調(diào)用的模型都能讀取。但實(shí)際效果取決于模型“遵循指令”的能力。Claude 系模型如 Opus、Sonnet在遵循復(fù)雜多步指令方面表現(xiàn)最穩(wěn)定部分國產(chǎn)模型在簡單的單步任務(wù)上沒問題但在多步驟、多層嵌套的流程執(zhí)行中偶爾會跳步或簡化流程。如果你用的是國產(chǎn)模型我的建議是先跑最核心的 brainstorming 和 writing-plans 兩個技能把需求對齊和計劃拆解這兩步抓好執(zhí)行環(huán)節(jié)可以讓模型自由度高一點(diǎn)。等模型能力迭代了再逐步放開。7.3 token 消耗明顯上升這是正常現(xiàn)象用了這套流程后很多人第一個感受就是“怎么 token 用得這么快”。這很正常。brainstorming 階段要多輪問答writing-plans 階段要生成完整計劃文檔executing-plans 階段每步還要讀文件自查——這些都要消耗 token。我的經(jīng)驗(yàn)是不要因?yàn)?token 消耗大就跳過規(guī)劃階段。你算一筆賬規(guī)劃階段多花的 token 成本通常遠(yuǎn)低于一次錯誤實(shí)現(xiàn)帶來的返工成本。時間才是更貴的資源。如果你真的想省 token可以把 brainstorming 的問題改成語義更緊湊的表述或者限定 Agent“最多問 5 個最核心的問題”。7.4 技能不生效先檢查這五個位置我遇到過一次“技能完全沒生效”的情況排查下來發(fā)現(xiàn)是技能目錄放錯了位置。如果你也遇到技能不生效的問題按這個順序排查技能文件是否放在了工具認(rèn)可的目錄Claude Code 是~/.claude/skills/Cursor 是.cursor/skills/。技能文件名是否為SKILL.md有些工具只識別特定命名。當(dāng)前對話是否有足夠的上下文窗口加載技能文件窗口太小可能會截斷。是否在對話中正確喚起了技能輸入superpowers或?qū)?yīng)的子技能。模型是否拒絕遵循技能文件中的指令某些安全對齊較強(qiáng)的模型會拒絕“按文件執(zhí)行”這類指令。實(shí)操心得如果第 5 條發(fā)生最有效的辦法是換模型或者把技能文件的關(guān)鍵步驟直接粘貼到對話里。我遇到過幾次模型對“多步驟指令文件”有保留的情況直接把核心步驟復(fù)制到對話上下文里就解決了。7.5 別把技能當(dāng)銀彈質(zhì)量上限還是要靠“人”最后說一個容易被忽略的點(diǎn)。Superpowers 解決的問題是“質(zhì)量下限”——它保證 Agent 不會亂來不會跳過關(guān)鍵步驟不會在沒澄清需求之前就動手。但它解決不了“質(zhì)量上限”——Agent 的最終產(chǎn)出質(zhì)量還是受限于模型能力和你的需求描述質(zhì)量。我見過有人用 Superpowers 之后以為可以完全放手了結(jié)果代碼質(zhì)量還是沒有達(dá)到預(yù)期因此跑來吐槽“這套東西沒用”。其實(shí)這里有一個被忽略的事實(shí)工具約束的是流程人提供的是方向。如果你自己都不清楚需求到底要什么再強(qiáng)的技能系統(tǒng)也幫你做不出一個沒想清楚的東西。用 Superpowers 前后我最大的心態(tài)變化是從“寫完代碼再檢查”變成了“寫之前先對齊”。對齊需求、對齊計劃、對齊驗(yàn)收標(biāo)準(zhǔn)——這個過程看著多了幾個步驟實(shí)際上每一分鐘都是花在刀刃上的。8. 擴(kuò)展思路和后續(xù)玩法8.1 自己定制團(tuán)隊(duì)專屬 SkillSuperpowers 是開源的這意味著你可以基于它定制適合自己團(tuán)隊(duì)的技能。比如團(tuán)隊(duì)有統(tǒng)一的代碼風(fēng)格規(guī)范、數(shù)據(jù)庫設(shè)計規(guī)范、接口命名規(guī)范都可以寫成一個新的 SKILL.md 文件讓 Agent 在開發(fā)時自動遵守。我目前就在維護(hù)兩個團(tuán)隊(duì)內(nèi)部技能一個是“數(shù)據(jù)庫遷移規(guī)范”要求 Agent 在涉及數(shù)據(jù)庫改動時先檢查是否有破壞性變更另一個是“接口兼容性檢查”要求在修改接口時自動檢查現(xiàn)有調(diào)用方是否受影響。這兩個技能極大地減少了團(tuán)隊(duì)內(nèi)的低級 review 意見。8.2 與 CI/CD 流程結(jié)合另一個可以玩的方向是把 Superpowers 的產(chǎn)物比如計劃文檔、檢查清單接入 CI/CD 流程。比如要求每次 MR 必須附帶 writing-plans 生成的驗(yàn)收標(biāo)準(zhǔn)清單CI 自動檢查這些清單是否被滿足。這相當(dāng)于把一個“約束 Agent 行為”的機(jī)制升級成了“約束團(tuán)隊(duì)協(xié)作流程”的機(jī)制。老實(shí)講我在這個方向的嘗試還比較淺但我認(rèn)為它對技術(shù)管理的價值潛力很大。畢竟 AI 編程的終局不是“一個人用 AI 寫代碼”而是**“一個團(tuán)隊(duì)用一套標(biāo)準(zhǔn)來使用 AI 寫代碼”**。8.3 多 Agent 協(xié)作場景下的紀(jì)律保證最后提一下多 Agent 協(xié)作。現(xiàn)在 Agent 框架越來越流行一個系統(tǒng)里可能會有多個 Agent 協(xié)同工作。如果沒有統(tǒng)一的技能體系約束每個 Agent 都按自己的偏好發(fā)揮協(xié)調(diào)成本會非常高。Superpowers 這類技能體系的價值在這里會被進(jìn)一步放大——它提供了一種“團(tuán)隊(duì)共同語言”讓不同 Agent 在執(zhí)行同一類任務(wù)時行為模式保持一致。我自己在做 agent 框架方案設(shè)計時已經(jīng)把技能體系作為架構(gòu)的一部分納入了。它不會直接決定 Agent 做什么但它決定了 Agent 做事的“行為基線”而行為基線正是一個團(tuán)隊(duì)能夠協(xié)作的前提。我個人的建議是不要把它當(dāng)成一個“插件”而是當(dāng)成一套“流程資產(chǎn)”來經(jīng)營。前期花一點(diǎn)時間熟悉、定制、沉淀后面每個使用 AI 編程的人都能穩(wěn)定從這套資產(chǎn)里獲益。