打造 AI Agent Skills 框架 — TDD for Documentation

怎麼知道你寫的 AI Skill 是有效的？

這個問題困擾了我一整天。直覺反應是「寫一些指引，讓 AI 試試看，不對再改」。但這跟軟體開發裡的「寫 code，跑一下，不對再改」一樣——沒有系統性，改了 A 不知道會不會壞了 B。

最後我借用了 TDD 的框架。不是寫測試程式碼的那種 TDD，而是把同樣的思維用在文件指引的設計上。

RED Phase：先看 AI 怎麼失敗

TDD 的第一步是寫失敗的測試。對應到 Skills 設計，就是先不寫任何指引，記錄 AI 在裸奔狀態下的行為。

我讓 AI 在完全沒有 Skill 指導的情況下，嘗試在企業表單系統裡開發頁面。不給任何提示，只給 codebase access。然後仔細觀察它在哪裡犯錯。

歸納出 6 類失敗：

#	失敗類型	具體表現
1	版型選擇錯誤	分不清 Master Layout 和 Master-Detail Layout 的適用場景
2	必要元素遺漏	忘了加程式碼編號、欄位定義陣列、按鈕類型、生命週期 hooks
3	事件時機不明	不知道什麼時候該掛上什麼事件處理器
4	遠端查詢機制不明	不知道怎麼正確呼叫遠端查詢事件
5	元件對應錯誤	欄位的資料型態和文件註記對應到錯誤的 UI 元件
6	按鈕代碼錯誤	按鈕的行為代碼不正確

這 6 類失敗有一個有趣的特性：它們都是「知識缺口」而非「推理錯誤」。

AI 的邏輯推理沒問題。它知道一個表單頁面需要版型、需要欄位、需要事件。問題是它不知道這個系統的版型長什麼樣、欄位怎麼定義、事件怎麼串接。

這意味著 Skill 不需要教 AI 怎麼思考——只需要填補知識缺口。

GREEN Phase：最小化的 Skill

TDD 的第二步：寫最少的 code 讓測試通過。

對應到 Skills 設計，就是針對每個失敗類型，寫最小量的指引來修正它。不多寫一行。

我建了 5 個 Skill 骨架：

developing-views：頁面開發的主要流程和決策樹
using-layouts：5 種版型的識別和使用指引
using-components：17 種元件的 Props 和注意事項
understanding-api：API 模式和遠端查詢機制
debugging-frontend：除錯工作流

每個 Skill 針對一到兩類失敗點。例如 using-layouts 針對「版型選擇錯誤」，裡面列出了 5 種版型的識別特徵和適用場景——一張速查表，不需要長篇大論。

然後測試。

72 分的 MVP

用這 5 個初版 Skill，讓 AI 生成一個發票管理頁面。

結果：72/100。

比裸奔好多了——基本結構正確、版型選對了、大部分元件也用對了。但三個嚴重幻覺依然存在：遠端查詢事件的用途搞混了、欄位間的連動邏輯被跳過了、還自創了一個不存在的事件。

72 分的診斷結果很明確：Skill 的方向對了，但粒度不夠。 版型選擇這種粗粒度的知識，一張速查表就能解決。但事件系統的細微差異、元件 Props 的具體格式，需要更精細的指引。

REFACTOR：643 行的教訓

於是我開始補強。加了更多細節、更多案例、更多注意事項。

然後 Skill 膨脹了。

最核心的那個版型指引——Master Layout 的 Skill 檔案——膨脹到了 643 行。

643 行的 Markdown。AI 讀到後半段的時候，前半段的規則已經模糊了。上下文窗口是有限的，塞太多資訊反而適得其反。

graph LR
    A[RED Phase<br/>觀察 6 類失敗] --> B[GREEN Phase<br/>5 個最小化 Skill]
    B --> C[MVP 測試<br/>72/100]
    C --> D[補強細節<br/>643 行膨脹]
    D --> E[REFACTOR<br/>302 行 + 子檔案]
    E --> F[回歸測試<br/>驗證無退化]
    F -->|發現退化| E

TDD 的第三步——REFACTOR。

我把 643 行拆成這樣的結構：

主檔案（302 行）：決策樹、邊界條件、關鍵注意事項——AI 一開始就需要的東西
事件子檔案（377 行）：事件系統的完整規格——只在需要處理事件時才載入
範例子檔案（403 行）：完整的參考頁面範例——只在需要對照時才載入

精簡了 53%。核心觀念是：不是所有資訊在所有時候都需要。

AI 開始一個頁面開發任務時，它需要知道怎麼選版型、哪些元素不能漏。但 377 行的事件規格？等它選完版型、確認了事件需求，再載入也不遲。

這個拆分日後演化成了更系統化的「漸進式披露」架構——下一篇會詳細說。

回歸測試：改了 A，B 壞了

REFACTOR 之後，自然要驗證：精簡過的 Skill 還能正確指引 AI 嗎？

這時候 TDD 的價值真正體現了。

我為每種版型建立了獨立的回歸測試基線——用當前版本的 Skill 生成一個標準頁面，逐行檢查，確認品質，存檔作為 baseline。之後每次修改 Skill，都重新生成同一個頁面，和 baseline 比對。

第一輪回歸就出事了。

修了 Master Layout 的 Skill 之後，Master-Detail Layout 的生成品質退化了。原因是兩種版型共用了一些元件定義，改了 A 版型的描述方式，影響了 B 版型對同一元件的理解。

接下來四輪回歸，每輪都暴露新的問題。baseline 重新生成了好幾次，每次都發現新的不一致。

輪次	測試範圍	結果
Sub-mission 5a	Master Layout	通過，Layer 1 修正驗證成功
Sub-mission 5b	Master-Detail Layout	發現退化，修正後通過
Sub-mission 5c	Query Layout	11/11 驗證項全部通過
Sub-mission 5d	Report Layout	通過

四輪下來，一個重要的認知形成了：Skills 不是文件，是程式碼。

它們有相依性、有副作用、修改後需要回歸測試。用管理程式碼的心態來管理 Skills，才能確保品質。

你可以帶走的方法論

整個流程回頭看，其實很簡單：

觀察失敗——不寫任何指引，記錄 AI 的自然行為和失敗模式
最小修正——針對每類失敗寫最少量的指引，不多寫一行
測試驗證——讓 AI 用這些指引工作，量化結果
精簡重構——膨脹了就拆，但每次拆完都要回歸測試
迭代循環——新的失敗模式出現，回到步驟 1

不需要一次寫出完美的 Skill。從失敗觀察開始，逐步補強，持續驗證。

這個方法論最反直覺的地方在於步驟 1：忍住不寫指引，先讓 AI 自由發揮。大多數人（包括我自己）的第一反應是「我知道 AI 會在哪裡犯錯，直接寫指引不就好了」。

但你以為 AI 會犯的錯，和它實際犯的錯，往往不一樣。我原本以為最大的問題是版型選擇，結果版型選擇反而是最容易修正的——真正棘手的是事件系統的隱含語意和元件 Props 的細微差異。

先觀察，再行動。這是軟體工程裡老生常談的道理，用在 AI Skills 設計上依然成立。

本文是「打造 AI Agent Skills 框架」系列的第 2/13 篇

← 上一篇：當 AI 遇上 400+ 頁面的企業系統 → 下一篇：漸進式披露

📚 回到系列目錄