你僱了一個AI程序員，卻沒給他寫工作手冊
整理版優先睇
畀AI程序員一份工作手冊：以agent-skills項目實踐生產級工程技能
呢篇文章由專注AI Agent實踐嘅作者撰寫，以一個比喻開場：你請咗個AI程序員，但冇畀佢工作手冊，結果佢做嘅登錄功能密碼明文存儲、冇測試。呢個就係而家多數人用AI編程工具嘅真實狀態。文章重點介紹GitHub上超過15,900 Stars嘅開源項目agent-skills，由Google Chrome核心工程師Addy Osmani編寫，包含20個結構化嘅SKILL.md文件，覆蓋軟件開發全生命週期——由定義、規劃、實現、驗證到發佈。每個技能文件都設有Overview、Process、Rationalizations（常見藉口加反駁）同Verification，目的係畀AI代理喺生產環境中遵守高級工程師嘅工作規範。
整體結論係：AI默認走最短路徑，會跳過測試、安全審查等必要步驟，所以需要畀佢哋清晰嘅工作手冊。但呢啲技能文件唔單止係教AI，更重要係倒逼開發團隊將自己對「好代碼」嘅模糊標準，變成可檢驗嘅顯式規範。文章指出多數人只用Prompt或Context，而忽略咗Skill呢個行為級範式，導致AI生產力受限制。
作者最後提出三個可行動建議：做缺技能診斷（檢查測試、安全、向後兼容）、從一個最痛點嘅Skill開始（唔好一次過用20個）、將Verification當作第一公民——用實際證據證明任務完成，而唔係「感覺對了」。呢啲建議適用於任何團隊，唔依賴AI本身嘅能力。文章強調，工作手冊其實係寫畀自己睇嘅，AI嘅出現令我哋冇…
- AI編程代理預設走最短路徑，容易省略測試、安全、文檔等關鍵步驟，需要類似「工作手冊」嘅技能文件引導。
- agent-skills 項目提供20個結構化SKILL.md文件，每個包含Overview、Process、Rationalizations、Verification，涵蓋開發全生命週期。
- Prompt、Context、Skill三種範式疊加使用，目前多數開發者只用咗前兩層，技能層幾乎空白。
- 技能文件嘅核心價值係傳承工程智慧，將團隊隱性編碼標準顯式化，同時迫使開發者釐清自己對「完成」嘅定義。
- 可立即執行嘅三個行動：為AI工作流做缺技能診斷、從一個最痛點技能開始、將驗證（Verification）作為完成任務嘅必要條件。
addyosmani/agent-skills - Production-grade engineering skills for AI coding agents
GitHub開源項目，包含20個結構化SKILL.md文件，覆蓋軟件開發全生命週期。
Software Engineering at Google
由Titus Winters等人合著，探討軟件工程係關於喺時間維度管理代碼，影響咗agent-skills嘅設計。
AI天才與工作手冊嘅悖論
想象一下，你請咗個新程序員，聰明，乜都識，但冇畀佢任何工作手冊。結果佢做得快，但密碼明文存儲、冇輸入校驗、冇測試。你會怪佢定怪自己？呢個就係而家多數人用AI編程工具嘅真實狀態。
AI默認走最短路徑
截至2026年4月，GitHub上一個名為 addyosmani/agent-skills 嘅開源項目以15,900+ Stars衝上熱榜。作者Addy Osmani，Google Chrome核心工程師，將高級工程師嘅工作規範編寫成20個結構化SKILL.md文件，供AI代理直接讀取執行。
生產級工程技能
agent-skills 嘅核心設計
每個SKILL.md結構固定：Overview → When to Use → Process → Rationalizations → Red Flags → Verification。其中Rationalizations模塊預設AI會揾藉口跳過步驟，例如「I'll add tests later」，並配備反駁論據。
Rationalizations模塊
漸進披露
三種範式疊加：Prompt（任務級）→ Context/ Rules（項目級）→ Skill（行為級）。Skill係主動觸發，AI檢測到任務類型自動激活對應技能。
Prompt（任務級）
Context/ Rules（項目級）
Skill（行為級）
你而家可以做嘅三件事
作者提出三個可行動建議，幫助你將概念落地。
- 1 做一次缺技能診斷：揀一個最近用AI完成嘅功能，檢查有冇測試覆蓋、安全考慮（OWASP Top 10）、向後兼容性。如果任何一個「冇諗過」，就係需要補技能文件嘅地方。
- 2 從一個最痛點Skill開始：唔好一次過加20個文件。揀測試覆蓋率就裝test-driven-development；揀安全就裝security-and-hardening。一個被執行嘅Skill，勝過二十個被收藏嘅文檔。
- 3 將驗證當成第一公民：每個技能最後嘅Verification模塊要求實際證據（測試通過截圖、構建輸出）證明任務完成。唔係「感覺對了」，係「有證據證明對了」。呢個習慣唔依賴AI，係工程文化最稀缺嘅誠實。
驗證當成第一公民
缺技能診斷
工作手冊其實係寫畀你自己睇嘅。當你花時間將「咩係好嘅代碼」寫成AI可執行嘅技能文件，你喺強迫自己將模糊嘅「感覺唔對」變成可檢驗嘅標準。呢件事嘅價值，唔依賴AI有幾聰明。
想像一下咁嘅場面。
你啱啱請咗個新程序員，好聰明、學得快，任何語言都寫到，代碼能力勁到嚇親人。第一日返工，你帶佢去位，指住個mon話：「幫我做個用戶登錄功能。」
然後你就走咗。
冇需求文檔、冇代碼規範、冇測試要求、冇安全checklist、冇提交格式說明。乜都冇。
佢梗係做到啦。做得好順暢㗎。但結果嘛——密碼就咁存明文、冇輸入驗證、冇錯誤處理、測試覆蓋率係零、commit message就寫咗「fix」。
你會怪佢咩？
唔會，你應該怪自己。因為你根本冇話俾佢知，「做個登錄功能」喺你度代表咩。
呢個就係我哋大部分人用AI編程工具嘅真實狀態。
第一章：AI天才與工作手冊嘅矛盾
自2026年以嚟，關於AI編程工具嘅討論已經多到數唔曬。大家講模型更強、講上下文窗口更長、講推理能力更深——但有一件事差唔多冇人系統咁討論過：
我哋有冇認真話俾AI知，「喺我度，寫代碼代表咩」？
截至2026年4月，GitHub上一個叫 addyosmani/agent-skills 嘅開源項目，有15,900+ Stars，淨係呢個星期就多咗6,693粒星，衝上咗GitHub周榜第8位。項目嘅作者Addy Osmani，係Google Chrome團隊嘅核心工程師，佢前後用咗幾個月時間，將佢認為一個「高級工程師喺生產環境入面會遵守嘅工作規範」整理成20份結構化嘅SKILL.md文件，俾AI代理直接讀取同執行。
項目的描述得一句說話，但值得重複睇：
“「Production-grade engineering skills for AI coding agents.」
唔係「AI編程技巧」，唔係「提示詞模板」，係生產級工程技能。
呢個分別，比起表面上睇到嘅大得多。
第二章：AI喺靜靜雞省略咗啲咩
如果你用過AI幫手寫代碼，你一定遇到過呢類情況：
AI幫你寫咗個function，行起嚟完全冇問題，但係——冇單元測試、冇錯誤邊界、冇類型註釋、冇日誌輸出、接口設計又同你現有嘅代碼風格格格不入。
你叫佢改，佢改咗。你再叫佢加測試，佢加咗。你叫佢優化接口，佢優化咗。每一步佢都做到，但你要一步一步咁講，佢先會一步一步咁做。
呢個唔係AI能力嘅問題。呢個係流程編碼嘅問題。
agent-skills 嘅README入面有一段話，我覺得係呢個項目最準確嘅自我定位：
“「AI coding agents default to the shortest path — which often means skipping specs, tests, security reviews, and the practices that make software reliable.」
翻譯過嚟就係：AI默認行最短路徑。最短路徑，就係行得通嘅路徑，而唔係正確嘅路徑。
呢個唔係咩深奧嘅見解，但佢講出咗一個好多人逃避嘅現實：AI喺幫你走捷徑，同時亦喺幫你埋雷。
嗰粒雷，可能係安全漏洞（OWASP Top 10入面嘅注入、認證缺陷，喺AI生成嘅代碼入面出現頻率高到嚇人），可能係可維護性問題（半年之後連你自己都睇唔明嘅function嵌套），可能係測試債（你以為AI幫你寫曬，但一次生產故障就證明咗「寫完」同「寫啱」係兩回事）。
第三章：「Skill」到底解決咩問題
agent-skills 嘅核心設計，係將傳統意義上「高級工程師帶新人」嘅經驗，結構化成AI可以直接消費嘅格式。
20份技能文件覆蓋咗軟件開發成個生命週期：
定義階段：idea-refine（將模糊想法收窄成具體提案）、spec-driven-development（寫規格文檔先鬱代碼） 規劃階段：planning-and-task-breakdown（將規格拆成可驗證嘅小任務） 實現階段：incremental-implementation（薄切片，每片都可以驗證）、test-driven-development（紅綠重構，測試金字塔）、context-engineering（正確嘅方法餵正確嘅信息俾AI） 驗證階段：browser-testing-with-devtools（用Chrome DevTools實時數據調試）、debugging-and-error-recovery（五步排查法） 審查階段：code-review-and-quality（五維度評審）、security-and-hardening（OWASP防禦清單） 發佈階段：git-workflow-and-versioning（原子提交，主幹開發）、shipping-and-launch（發佈前清單，分級灰度）
每份SKILL.md嘅結構係固定嘅：Overview → When to Use → Process → Rationalizations（常見藉口+反駁）→ Red Flags → Verification。
留意嗰個「Rationalizations」模塊——呢個係成個設計入面最得意嘅一個設計選擇。
佢喺度預設AI會揾藉口跳過步驟。
例如喺test-driven-development入面，佢預先寫咗呢啲「藉口」：
「I'll add tests later」（我等陣加測試） 「This is too simple to need tests」（呢個邏輯太簡單，唔使測試） 「The type system is the tests」（型別系統就係測試喇）
每一個藉口旁邊，都配咗反駁論據。
呢個就係我覺得 agent-skills 真正有見地嘅地方：佢唔係假設AI會乖乖咁守規則，而係假設AI有人類工程師一樣嘅「偷懶本能」，並提早將呢個本能對應嘅反駁寫入工作手冊。
第四章：Prompt、Context、Skill——三種範式嘅邊界喺邊
呢個係一個容易混淆嘅話題，但邊界其實好清晰。
Prompt，係你臨時話俾AI知「而家做咩」。適合一次性任務，下文消失咗就消失，冇持久性。
Context（包括CLAUDE.md、.cursor/rules等），係你話俾AI知「喺呢個項目入面，有咩背景知識」。適合單項目範圍內嘅規則沉澱，但依然係被動嘅——AI只有當你執行任務時先會讀呢啲資訊。
Skill，係你話俾AI知「面對呢一類任務，你應該跟咩流程」。佢係主動觸發嘅——當AI偵測到你在做API設計時，api-and-interface-design會自動激活；當你改UI時，frontend-ui-engineering會自動介入。唔使你每次都手動提醒「唔好唔記得考慮可訪問性」。
三種範式唔係取代關係，係疊加關係：
Prompt（任務級）
↓
Context/Rules（項目級）
↓
Skill（行為級）
但實際使用中，大多數人只用咗第一層。間中用到第二層。第三層幾乎係空白。
呢個唔係個人嘅選擇，而係工具鏈仲未成熟嘅結果——喺 agent-skills 呢類項目出現之前，「俾AI配備技能」呢件事根本冇一個夠簡單嘅解決方案。你要自己寫一大堆規則文檔，或者就由得佢。
第五章：一個值得唔舒服嘅反思
如果你同我一樣，係「倖存派」嘅信徒——即係相信AI唔會帶來末日亦唔會創造天堂，淨係會令每個人嘅能力上限變得更加明顯——咁你應該感受到呢件事嘅張力。
Skill嘅出現，令AI編程嘅天花板明顯提升咗。但同時，佢亦令一個問題更清晰咁暴露咗出嚟：
你對「好代碼」嘅標準，夠唔夠清晰？
如果你自己都唔清楚一個功能「驗收完成」代表咩，AI再強都幫你唔到。agent-skills 入面嘅每一個技能文件，最後都有一個叫「Verification」嘅模塊，要求用實際證據（測試通過截圖、構建輸出、運行時數據）去證明任務真係完成咗——「睇落啱」唔算完成。
呢個要求，放喺人類工程師身上，都係成立嘅。
換句話講，agent-skills 表面上係話俾AI知應該點樣工作，實際上係逼使用者將自己對「好代碼」嘅隱性認知，顯式咁寫出嚟。呢件係令好多人唔舒服嘅事，因為佢暴露咗一個好多團隊都有但唔肯承認嘅現實：
我哋根本冇共識。
代碼審查標準係模糊嘅，測試覆蓋率要求係口頭講講嘅，安全規範係事後先補嘅，文檔係「得閒先寫」嘅。
AI將呢啲模糊暴露曬出嚟，因為佢比任何新員工都更誠實咁執行咗「你講嘅」而唔係「你想要嘅」。
第六章：「工作手冊」嘅真實價值唔係約束，係傳承
講個題外話。
Google嘅工程文化入面有一本書，叫《Software Engineering at Google》（SWE Book），由Titus Winters、Tom Manshreck同Hyrum Wright合著，2020年由O'Reilly出版。呢本書嘅核心命題之一係：軟件工程唔係關於寫代碼嘅，而係關於喺時間維度上對代碼進行管理嘅。
即係話，好嘅代碼唔止今日行得啱，而係六個月後換咗另一個人嚟維護，依然行得啱。
agent-skills入面有好多設計明顯受咗呢本書嘅影響——例如 git-workflow-and-versioning入面嘅「原子提交」同「變更唔超過約100行」原則嚟自Google嘅Code Review最佳實踐；api-and-interface-design入面嘅「Hyrum定律」（任何可觀測嘅行為最終都會俾人依賴，無論你係咪將佢寫入接口）係Google內部工程師總結嘅真實教訓；test-driven-development入面嘅「Beyoncé Rule」（如果你想保留一個行為，就俾佢寫測試——「If you liked it, you should have put a test on it」）係Google工程文化入面廣為流傳嘅比喻。
Addy Osmani將呢啲嘢塞入SKILL.md，令AI每次寫代碼時，都可以自動調用呢啲積累咗幾十年嘅工程智慧。
呢個就係「技能」嘅真實價值：唔係約束，係傳承。
每一條規範背後，都有一個真實發生過嘅故障、一次真實付出過嘅代價。將呢啲經驗編碼成Skill，本質上係用結構化嘅方式對抗遺忘，對抗「我哋下次會記得」嘅幻覺。
第七章：呢條路上真正難嘅部分
當然，agent-skills唔係銀彈。
我喺項目嘅Issues入面睇過（截至2026年4月，項目共有15個開放Issue，21個開放PR），有幾個爭論我覺得幾有價值：
爭論一：技能文件太長，AI讀完就用曬Token
呢個係真實嘅工程問題。20份技能文件，每份都有幾百行，全部加載入上下文代價好高。項目嘅應對方案係「漸進披露」——SKILL.md係入口，子文檔只喺需要時先加載，降低Token開銷。但呢個需要AI支援工具調用，並唔係所有環境都可以無縫運行。
爭論二：邊個嚟維護呢啲技能文件？
呢個係更根本嘅問題。agent-skills係Google工程文化嘅一種映射，但唔同團隊、唔同語言、唔同業務場景，需要嘅技能文件可以好唔同。你可以直接攞嚟用，但要用得好，你需要喺佢嘅基礎上做定製。而呢個定製過程，需要團隊入面有人願意花時間去做，並持續維護。
爭論三：Skill會唔會限制AI嘅創造力？
呢個係最得意嘅反駁。有聲音認為，過度規範化嘅Skill會令AI太過守規矩，反而冇咗嗰種「意想不到嘅好方案」。
我認為呢個擔憂係真實嘅，但方向搞錯咗。技能文件規範嘅係流程，唔係答案。佢話俾AI知「設計API之前先定義契約」，但冇規定契約要點樣。喺過程約束同答案開放之間保持平衡，先係寫好技能文件嘅核心難點。
第八章：你而家可以做嘅三件事
好，反思到呢度，我嘗試將佢落地成三個可行嘅建議。
第一件事：幫你嘅AI工作流程做一次「缺技能診斷」
揾出你最近用AI輔助完成嘅一個功能，答三個問題：
呢個功能有冇被測試覆蓋？如果冇，係因為AI冇寫，定係你冇叫佢寫？ 呢個功能有冇考慮過安全問題？（OWASP Top 10入面至少檢查注入、認證、敏感數據三項） 呢個功能嘅接口設計，有冇考慮過調用方嘅向後兼容性？
三個問題入面只要有一個答案係「我冇諗過」，咁你就揾到咗一個需要補技能文件嘅地方。
第二件事：由最細嘅一個Skill開始，而唔係全部
唔好一次過將agent-skills嘅20份文件全部加曬。揀一個你同團隊最痛嘅地方——如果係測試覆蓋率，就先裝test-driven-development；如果係安全，就先裝security-and-hardening；如果係代碼越來越難維護，就先裝code-simplification。
一個被執行嘅Skill，好過二十個被收藏嘅文檔。
第三件事：將「驗證」當成第一公民
agent-skills入面每個技能嘅最後一個模塊係Verification——用實際證據證明任務完成咗。呢個係成個項目入面我認為最值得單獨抽岀嚟、當成獨立習慣培養嘅一點。
唔係「感覺啱」，係「有證據證明啱」。
呢個習慣，同你係咪用AI冇關係，同你用咩語言咩框架都冇關係。佢係工程文化入面最稀缺嘅嘢：誠實咁對待「完成」兩個字嘅意思。
尾聲：工作手冊寫俾邊個睇？
講返開頭嗰個問題。
嗰個聰明嘅新程序員，攞到工作手冊之後，會發生咩事？
通常，佢會將手冊讀一次，然後喺心裏面形成一張圖：喺呢個團隊入面，「寫完」代表咩，「做好」代表咩，邊啲嘢唔做會俾人打回頭，邊啲嘢做咗會俾人認可。呢張圖，會喺佢之後每一行代碼入面靜靜雞起作用——唔係每次都要對住手冊，而係內化咗成本能。
AI冇本能。佢只有你俾佢嘅上下文。
所以工作手冊，其實係寫俾你自己睇嘅。
當你花時間將「咩係好嘅代碼」寫成可以俾AI執行嘅技能文件時，你實際上係做緊一件比教AI更重要嘅事：你喺強迫自己將模糊嘅「感覺唔啱」，變成可以檢驗嘅「標準」。
呢件事嘅價值，唔依賴於AI有幾聰明。佢喺一個冇AI嘅團隊入面都成立。
只係AI嘅出現，令我哋再冇理由拖延呢件事。
想象這樣一個場景。
你剛招來一位新程序員，聰明、學得快，什麼語言都能寫，代碼能力強得嚇人。第一天上班，你把他領到工位，指着屏幕說："給我做一個用戶登錄功能。"
然後你走了。
沒有需求文檔，沒有代碼規範，沒有測試要求，沒有安全checklist，沒有提交格式說明。沒有任何東西。
他當然能做出來。做得還挺流暢。但結果嘛——密碼明文存儲，沒有輸入校驗，沒有錯誤處理，測試零覆蓋，commit message寫的是"fix"。
你會怪他嗎？
不，你應該怪自己。因為你根本沒告訴他，"做一個登錄功能"在你這裏意味着什麼。
這就是我們大多數人使用AI編程工具的真實狀態。
第一章：AI天才與工作手冊的悖論
2026年以來，圍繞AI編程工具的討論已經汗牛充棟。大家談模型更強了，談上下文窗口更長了，談推理能力更深了——但有一件事幾乎沒人系統地談過：
我們有沒有認真告訴AI，"在我這裏，寫代碼意味着什麼"？
截至2026年4月，GitHub上一個名為 addyosmani/agent-skills 的開源項目以15,900+ Stars和本週6,693顆新Star的速度衝上了GitHub周榜Top 8。項目的作者Addy Osmani，Google Chrome團隊的核心工程師，前後花了幾個月時間，把他認為一個"高級工程師在生產環境中會遵守的工作規範"編寫成20個結構化的SKILL.md文件，供AI代理直接讀取和執行。
項目描述只有一句話，但值得反覆念：
“"Production-grade engineering skills for AI coding agents."
不是"AI編程技巧"，不是"提示詞模板"，是生產級工程技能。
這個區別，比看起來要大得多。
第二章：AI在默默省略什麼
如果你用過AI輔助寫代碼，你一定遇到過這類情況：
AI給你寫了一個函數，跑起來完全沒問題，但是——沒有單元測試，沒有錯誤邊界，沒有類型註釋，沒有日誌輸出，接口設計也跟你已有的代碼風格格格不入。
你讓他改，他改了。你讓他再加測試，他加了。你讓他優化接口，他優化了。每一步他都能做，但你要一步一步地說，他才會一步一步地做。
這不是AI能力的問題。這是流程編碼的問題。
agent-skills 的README裏有一段話，我覺得是這個項目最準確的自我定位：
“"AI coding agents default to the shortest path — which often means skipping specs, tests, security reviews, and the practices that make software reliable."
翻譯過來就是：AI默認走最短路徑。最短路徑，就是能跑通的路徑，而不是正確的路徑。
這不是什麼深刻洞見，但它說出了一個很多人在迴避的現實：AI在幫你走捷徑，同時也在幫你埋雷。
那個雷，可能是安全漏洞（OWASP Top 10裏的注入、認證缺陷，在AI生成的代碼裏出現頻率高得可怕），可能是可維護性問題（半年後你自己都讀不懂的函數嵌套），可能是測試債（你以為AI幫你寫完了，但一次生產故障就能證明"寫完"和"寫對"是兩件事）。
第三章：「Skill」到底解決什麼問題
agent-skills 的核心設計，是把傳統意義上「高級工程師帶新人」的經驗，結構化成AI能直接消費的格式。
20個技能文件覆蓋了軟件開發全生命週期：
定義階段：idea-refine（把模糊想法收斂成具體提案）、spec-driven-development（寫規格文檔再動代碼） 規劃階段：planning-and-task-breakdown（把規格拆成可驗證的小任務） 實現階段：incremental-implementation（薄切片，每片都能驗證）、test-driven-development（紅綠重構，測試金字塔）、context-engineering（給AI喂正確信息的正確方式） 驗證階段：browser-testing-with-devtools（Chrome DevTools實時數據調試）、debugging-and-error-recovery（五步排查法） 審查階段：code-review-and-quality（五維度評審）、security-and-hardening（OWASP防禦清單） 發佈階段：git-workflow-and-versioning（原子提交，主幹開發）、shipping-and-launch（預發清單，分級灰度）
每個SKILL.md的結構是固定的：Overview → When to Use → Process → Rationalizations（常見藉口+反駁）→ Red Flags → Verification。
注意那個"Rationalizations"模塊——這是整個設計裏最有意思的一個設計選擇。
它在預設AI會找藉口跳過步驟。
比如在test-driven-development裏，它預寫了這些"藉口"：
"I'll add tests later"（我待會兒加測試） "This is too simple to need tests"（這個邏輯太簡單，不需要測試） "The type system is the tests"（類型系統就是測試了）
每一條藉口旁邊，都配了反駁論據。
這就是我覺得 agent-skills 真正有洞見的地方：它不是在假設AI會乖乖遵守規則，而是在假設AI有人類工程師一樣的「偷懶本能」，並提前把這個本能對應的反駁寫進了工作手冊。
第四章：Prompt、Context、Skill——三種範式的邊界在哪裏
這是一個很容易混淆的話題，但邊界其實很清晰。
Prompt，是你臨時告訴AI"現在做什麼"。適合一次性任務，上下文消失了就消失了，沒有持久性。
Context（包括CLAUDE.md、.cursor/rules等），是你告訴AI"在這個項目裏，有哪些背景知識"。適合單項目範圍內的規則沉澱，但依然是被動的——AI只有在你執行任務時才讀這些信息。
Skill，是你告訴AI"面對這一類任務，你應該遵循什麼流程"。它是主動觸發的——當AI檢測到你在做API設計時，api-and-interface-design自動激活；當你在改UI時，frontend-ui-engineering自動介入。不需要你每次都手動提醒"別忘了考慮可訪問性"。
三種範式不是替代關係，是疊加關係：
Prompt（任務級）
↓
Context/Rules（項目級）
↓
Skill（行為級）
但在實際使用中，大多數人只用了第一層。偶爾用第二層。第三層幾乎是空白的。
這不是個人的選擇，而是工具鏈還不成熟的結果——在 agent-skills 這類項目出現之前，"給AI配備技能"這件事根本沒有一個足夠簡潔的解決方案。你要麼自己寫一堆規則文檔，要麼就隨它去。
第五章：一個值得不舒服的反思
如果你跟我一樣，是「倖存派」的信徒——那種相信AI既不會帶來末日也不會創造天堂、只會讓每個人的能力上限變得更明顯的人——那你應該能感受到這件事的張力所在。
Skill的出現，讓AI編程的天花板顯著提升了。但同時，它也讓一個問題更清晰地暴露出來：
你對"好代碼"的標準，足夠清晰嗎？
如果你自己都不清楚一個功能"驗收完成"意味着什麼，AI再強也幫不了你。agent-skills 裏的每一個技能文件，最後都有一個叫"Verification"的模塊，要求用實際證據（測試通過截圖、構建輸出、運行時數據）來證明任務真的完成了——"看起來對了"不算完成。
這個要求，放在人類工程師身上，也是成立的。
換句話說，agent-skills 表面上是在告訴AI該怎麼工作，實際上是在倒逼使用者把自己對"好代碼"的隱性認知，顯式地寫出來。這是一件讓很多人不舒服的事情，因為它暴露了一個很多團隊都有但不願承認的現實：
我們根本沒有共識。
代碼審查標準是模糊的，測試覆蓋率要求是口頭說說的，安全規範是事後補的，文檔是"有空再寫"的。
AI把這些模糊暴露了出來，因為它比任何新員工都更誠實地執行了"你說的"而不是"你想要的"。
第六章：「工作手冊」的真實價值不是約束，是傳承
講個題外話。
Google的工程文化裏有一本書，叫《Software Engineering at Google》（SWE Book），由Titus Winters、Tom Manshreck和Hyrum Wright合著，2020年由O'Reilly出版。這本書的核心命題之一是：軟件工程不是關於寫代碼的，而是關於在時間維度上對代碼進行管理的。
也就是說，好的代碼不只是今天跑得對，而是六個月後換了一個人來維護，依然跑得對。
agent-skills裏有很多設計明顯受到了這本書的影響——比如 git-workflow-and-versioning裏的"原子提交"和"變更不超過約100行"原則來自Google的Code Review最佳實踐；api-and-interface-design裏的"Hyrum定律"（任何可觀測的行為最終都會被人依賴，無論你是否把它寫進接口）是Google內部工程師總結的真實教訓；test-driven-development裏的"Beyoncé Rule"（如果你想保留一個行為，就給它寫測試——"If you liked it, you should have put a test on it"）是Google工程文化裏廣為流傳的比喻。
Addy Osmani把這些東西塞進了SKILL.md，讓AI在每次寫代碼時，都能自動調用這些積累了幾十年的工程智慧。
這就是「技能」的真實價值：不是約束，是傳承。
每一條規範背後，都有一個真實發生過的故障、一次真實付出過的代價。把這些經驗編碼成Skill，本質上是在用結構化的方式對抗遺忘，對抗"我們下次會記得"的幻覺。
第七章：這條路上真正難的部分
當然，agent-skills不是銀彈。
我在項目的Issues裏翻了翻（截至2026年4月，項目共有15個開放Issue，21個開放PR），有幾個爭論讓我覺得挺有價值的：
爭論一：技能文件太重，AI讀完就Token爆了
這是個真實的工程問題。20個技能文件，每個都有幾百行，全部加載進上下文代價高昂。項目的應對方案是"漸進披露"——SKILL.md是入口，子文檔只在需要時加載，降低Token開銷。但這需要AI支持工具調用，並不是所有環境都能無縫運行。
爭論二：誰來維護這些技能文件？
這是個更根本的問題。agent-skills是Google工程文化的一種映射，但不同團隊、不同語言、不同業務場景，需要的技能文件大相徑庭。你能直接拿來用，但要用好，你需要在它的基礎上做定製。而這個定製過程，需要團隊裏有人願意花時間去做，並持續維護。
爭論三：Skill會不會限制AI的創造力？
這是最有意思的反駁。有聲音認為，過度規範化的Skill會讓AI過於守規矩，反而喪失了那種"意想不到的好方案"。
我認為這個擔憂是真實的，但方向搞反了。技能文件規範的是流程，不是答案。它告訴AI"設計API之前先定義契約"，但沒有規定契約長什麼樣。在過程約束和答案開放之間保持平衡，才是寫好技能文件的核心難點。
第八章：你現在可以做的三件事
好，反思到這裏，我嘗試把它落地成三個可操作的建議。
第一件事：給你的AI工作流做一次「缺技能診斷」
找出你最近用AI輔助完成的一個功能，回答三個問題：
這個功能有沒有被測試覆蓋？如果沒有，是因為AI沒寫，還是你沒要求它寫？ 這個功能有沒有通過安全考慮？（OWASP Top 10裏至少檢查注入、認證、敏感數據三項） 這個功能的接口設計，是否考慮了調用方的向後兼容性？
三個問題裏只要有一個答案是"我沒想過"，那你就找到了一個需要補技能文件的地方。
第二件事：從最小的一個Skill開始，而不是全部
不要一次性把agent-skills的20個文件全部加進去。選一個你和團隊最痛的點——如果是測試覆蓋率，就先裝test-driven-development；如果是安全，就先裝security-and-hardening；如果是代碼越來越難維護，就先裝code-simplification。
一個被執行的Skill，勝過二十個被收藏的文檔。
第三件事：把"驗證"當成第一公民
agent-skills裏每個技能的最後一個模塊是Verification——用實際證據證明任務完成了。這是整個項目裏我認為最值得單獨提取出來、作為獨立習慣培養的一點。
不是"感覺對了"，是"有證據證明對了"。
這個習慣，跟你用不用AI沒有關係，跟你是什麼語言什麼框架也沒有關係。它是工程文化裏最稀缺的那種東西：誠實地對待"完成"二字的含義。
尾聲：工作手冊寫給誰看的？
說回開頭那個問題。
那位聰明的新程序員，在拿到工作手冊之後，會發生什麼？
通常，他會把手冊讀一遍，然後心裏形成一張圖：在這個團隊裏，"寫完"意味着什麼，"做好"意味着什麼，哪些事情不做會被打回，哪些事情做了會被認可。這張圖，會在他後續每一行代碼裏悄悄起作用——不是每次都需要對照手冊，而是內化成了本能。
AI沒有本能。它只有你給它的上下文。
所以工作手冊，其實是寫給你自己看的。
當你花時間把"什麼是好的代碼"寫成能讓AI執行的技能文件時，你實際上是在做一件比教AI更重要的事：你在強迫自己把模糊的"感覺不對"，變成可以檢驗的"標準"。
這件事的價值，不依賴於AI有多聰明。它在一個沒有AI的團隊裏也成立。
只是AI的出現，讓我們再也沒有理由拖延這件事了。