智慧體技能：讓AI編碼智慧體遵循優秀工程實踐

以下文章最初發表於Addy Osmani的部落格，經作者許可在此轉載。

任何AI編碼智慧體的預設行為都是採取通往“完成”的最短路徑。要求一個功能，它就編寫該功能。它不會詢問你是否有一個規範，不會在實現之前編寫測試，不會考慮更改是否跨越信任邊界，也不會檢查PR在審查者眼中會是什麼樣子。它產生程式碼，宣佈勝利，然後繼續前進。

這是每位高階工程師整個職業生涯都在學習避免的相同失敗模式。任何任務的高階版本都包括不出現在差異中的工作：揭示假設、編寫規範、將工作分解為可審查的塊、選擇無聊的設計、留下結果正確的證據、調整更改的大小以便人類可以實際審查。這些步驟正是區分能夠大規模釋出可靠軟體的工程師與那些推送會出問題的程式碼的人的大部分因素。

智慧體跳過這些步驟的原因與任何初級工程師相同。它們是不可見的。獎勵訊號指向“任務完成”，而不是“任務完成並且設計文件存在”。因此，我們必須重新加上高階工程師的腳手架。

Agent Skills是我對這種腳手架的嘗試。它剛剛突破了27,000顆星，顯然我不是唯一想要它的人。這篇文章是README沒有完全涵蓋的部分：每個設計選擇存在的原因，它們如何對映到標準SDLC和谷歌已釋出的工程實踐，以及即使你從未安裝單個技能，也應該從該專案中借鑑什麼。

技能究竟是什麼

“技能”這個詞在Claude Code/Anthropic的詞彙表中承擔了大量工作，需要精確理解。技能是一個帶有前置後設資料的Markdown檔案，當情況需要時會被注入到智慧體的上下文中。它介於系統提示片段和執行手冊之間。

技能不是參考文件。它不是“你應該知道的關於測試的一切”。它是一個工作流：智慧體遵循的一系列步驟，帶有產生證據的檢查點，並以定義的退出標準結束。

這個區別就是整個遊戲的關鍵。如果你將一篇2000字的關於測試最佳實踐的文章放入智慧體的上下文，智慧體閱讀它，生成看似合理的文本，然後跳過實際測試。如果你將一個工作流放在那裡（先編寫失敗的測試，執行它，看到它失敗，編寫最少程式碼透過，看到它透過，重構），智慧體就有事情可做，而你也有事情可驗證。

流程重於散文。工作流重於參考。帶有退出標準的步驟重於沒有它們的文章。這一個區別將有用的技能與漂亮的Markdown檔案區分開來。它也解釋了為什麼如此多的“AI規則”倉庫在實踐中最終無所作為。規則就是文章。

技能編碼的SDLC

倉庫中的20個技能組織在六個生命週期階段周圍，上面有七個斜槓命令。定義（/spec）是你決定實際構建什麼的地方。計劃（/plan）分解工作。構建（/build）用垂直切片實現它。驗證（/test）證明它有效。審查（/review）捕獲遺漏的東西。釋出（/ship）安全地將其交付給使用者。/code-simplify貫穿整個過程的基礎。

這不是巧合。這是每個正常運作的工程組織執行的相同SDLC，只是詞彙不同。谷歌稱之為設計文件→審查→實現→可讀性審查→啟動清單。亞馬遜稱之為反向工作備忘錄和提升門檻者。每個健康的團隊都有這個迴圈的某種版本。

AI編碼智慧體的新問題是，大多數智慧體預設跳過了這些階段中的大多數。你要求一個功能，你得到一個實現，而規範、計劃、測試、審查和啟動清單都沒有發生。技能推動智慧體經歷高階工程師強迫自己經歷的相同階段，因為沒有它們就釋出程式碼是產生事故的方式。

一個複雜功能可能依次啟用11個技能。一個小錯誤修復可能使用三個。路由器（using-agent-skills）決定哪些適用。關鍵是工作流根據實際範圍縮放，而不是根據假設的範圍。

起作用的五個原則

專案中的五個設計決策是承重牆。系統的其餘部分跟隨它們。

**1. 流程重於散文**

已經涵蓋。工作流是智慧體可操作的；文章則不是。對人類團隊也是如此。如果你的團隊手冊有200頁，在時間壓力下沒人會讀。如果它是一小組帶有檢查點的工作流，人們實際執行它們。

**2. 反合理化表格**

這是專案中最獨特的設計決策，也是我最希望其他團隊借鑑的。

每個技能包含一個常見藉口的表格，智慧體（或疲憊的工程師）可能用這些藉口來跳過工作流，並配以書面的反駁。接近原文的一些例子：

• “這個任務太簡單，不需要規範。” → 驗收標準仍然適用。五行就可以了。零行不行。
• “我稍後寫測試。” → “稍後”是承重詞。沒有稍後。先編寫失敗的測試。
• “測試透過了，釋出吧。” → 透過的測試是證據，不是證明。你檢查了執行時嗎？你驗證了使用者可見的行為嗎？人類閱讀了差異嗎？

這樣做的原因是LLM非常擅長合理化。它們會生成一段看似合理的段落，解釋為什麼這個特定任務不需要規範，或者為什麼這個特定更改無需審查就可以合併。反合理化表格是對智慧體尚未說出的謊言的預寫反駁。

這個模式對人類團隊同樣有效。大多數工程衰減不是有人選擇做壞工作，而是人們接受看似合理的理由來跳過他們不想做的部分。一個寫下其反合理化的團隊是一個擁有更少合理化的團隊。

**3. 驗證不可協商**

每個技能終止於具體證據。測試透過。構建輸出乾淨。執行時跟蹤顯示預期行為。審查者簽字。“看起來正確”永遠不夠。

這是使Anthropic的harness從失敗中恢復、使Cursor的planner/worker/judge分裂實際捕獲錯誤、使任何長時間執行的智慧體可恢復的相同原則。智慧體是生成器。你需要一個獨立的訊號表明工作已完成。技能將那個訊號烘焙到每個工作流中。

**4. 漸進式披露**

不要在會話開始時將所有20個技能載入到上下文中。根據階段啟用它們。一個小型元技能（using-agent-skills）充當路由器，決定哪個技能適用於當前任務。

這是應用於技能粒度的harness工程課。載入到上下文中的每個令牌都會在某個地方降低效能，所以你載入相關的內容，將其他內容留在磁碟上。漸進式披露是你如何將20個技能的庫放入5K令牌的槽中而不汙染井。

**5. 範圍紀律**

元技能編碼了一個不可協商的要求，如果可能我會將其釘在每個智慧體上：“只修改你被要求修改的內容。”不要重構相鄰系統。不要刪除你不完全理解的程式碼。不要因為碰到TODO就決定重寫檔案。

這聽起來顯而易見，直到你看到智慧體決定修復一個錯誤需要現代化三個不相關的檔案。範圍紀律是決定智慧體的PR是可合併還是必須撤銷的最大單一因素。它也是最乾淨地對映到谷歌程式碼審查規範的原則，因為審查者會阻止執行多個操作的PR。

谷歌DNA

這些技能充滿了來自《谷歌的軟體工程》和谷歌公開工程文化的實踐。這是刻意的。使谷歌規模軟體工作的大部分內容都是文件化和公開的，而正是智慧體最可能跳過的部分。

部分技能編碼的實踐對映：

• Hyrum定律在api-and-interface-design中。API的每個可觀察行為最終都會被某人依賴，所以設計時要考慮到這一點。
• 測試金字塔（~80/15/5）和Beyoncé規則在test-driven-development中。“如果你喜歡它，你應該為它寫個測試。”基礎設施更改不會捕獲錯誤；測試才會。
• 測試中的DAMP over DRY。谷歌的測試哲學明確表示測試程式碼應該讀起來像規範，即使以一些重複為代價。過度抽象的測試是已知的反模式。
• 約100行的PR大小，在code-review-and-quality中使用Critical/Nit/Optional/FYI嚴重級別標籤。直接來自谷歌的程式碼審查規範。大的PR不會被審查；它們會被橡皮圖章式批准。
• Chesterton's柵欄在code-simplification中。不要刪除你不理解為什麼存在的東西。
• 主幹開發和原子提交在git-workflow-and-versioning中。
• 左移和功能標誌在ci-cd-and-automation中。儘早捕獲問題，將部署與釋出解耦。
• 程式碼即負債在deprecation-and-migration中。你保留的每一行都需要永遠維護，所以偏好更小的表面。

這些都不是新想法。關鍵是它們都不是智慧體的預設行為。前沿模型在訓練資料中讀過“Hyrum定律”這個短語，但它在凌晨3點設計你的API時並不會應用Hyrum定律。技能就是確保它應用的方式。

實際使用方法

三種模式，按承諾程度遞增。

模式1：透過市場安裝。如果你使用Claude Code：

/plugin marketplace add addyosmani/agent-skills /plugin install agent-skills@addy-agent-skills

你將獲得斜槓命令（/spec, /plan, /build, /test, /review, /ship, /code-simplify），智慧體根據上下文自動啟用相關技能。這是我推薦大多數人開始的路徑。

模式2：將Markdown放入你選擇的工具中。這些技能是帶有前置後設資料的純Markdown。Cursor使用者將它們放在.cursor/rules/中。Gemini CLI有自己的安裝路徑。Codex、Aider、Windsurf、OpenCode以及任何接受系統提示的工具都可以讀取它們。工具不重要，底層的工作流才是關鍵。

模式3：作為規範閱讀。即使你從未安裝任何東西，這些技能也是關於AI智慧體良好工程實踐的文件化描述。閱讀code-review-and-quality.md，將五軸框架應用到團隊的審查流程中。閱讀test-driven-development.md，用它來解決與初級工程師關於“是否需要先編寫測試”的下一次爭論。閱讀元技能，將五個不可協商的要求偷用到你自己的AGENTS.md中。

這是我真的會開始的模式。選擇最接近你當前痛點的四或五個技能。決定要強制執行哪些工作流。然後安裝執行時，或自己編寫一個來執行。

即使不安裝也要借鑑的模式

專案中一些模式，無論你是否使用AI編碼智慧體，我都建議借鑑：

將反合理化作為團隊實踐。寫下你的團隊對自己說的謊言。“我們會在釋出後修復測試。”“這個變更太小，不需要設計文件。”“沒關係，我們有監控。”為每個謊言配上反駁。把它放在你的AGENTS.md或工程維基中。它將為你節省爭論，並抓住下一個疲倦的週五下午的捷徑。

內部編寫的任何內容都採用流程重於散文。如果你發現自己正在寫一篇2000字的名為“我們如何做X”的文件，你寫的是參考材料。將其轉換為帶有檢查點的工作流。文件會縮至400字，人們實際上會執行它。這一點同樣適用於入職指南和執行手冊，以及智慧體技能。

將驗證作為硬性退出標準。使“產生證據”成為每個任務的退出步驟。對於智慧體、工程師、你自己。證據是任何證明工作已完成的東西：一個綠色的測試執行、一個螢幕截圖、一個審查者的批准。如果不產生證據，任務就沒有完成。

這些模式正是Agent Skills專案所提供的，即使你從未安裝它。