智能體技能：讓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項目所提供的，即使你從未安裝它。