情境
使用者最常給 AI 的需求，往往是這種話：「幫我加個搜尋功能」。
這句話對 AI 來說資訊量太少。什麼東西要被搜尋？搜尋結果要怎麼顯示？要不要 debounce？要不要 highlight 符合的字？這些全部不講清楚的話，AI 會自己腦補，然後你可能拿到一個「能跑但完全不是你要的」實作。
這個範例示範 writing-plans skill 怎麼把這種模糊需求，拆成有階段、有驗收標準（definition of done）的計畫——v6.4.2 之後，計畫只記錄實作需要的決策（檔案、介面簽名、測試斷言），不再抄程式碼或寫時間估算。
不用 skill 的話會發生什麼事？
如果你直接跟 AI 說「幫我加個搜尋功能」，多半會這樣：
你：幫我加個搜尋功能
AI：好的，我來建立搜尋輸入框、filter 邏輯、UI 呈現...
（開始改 5 個檔案，你只能事後看 diff）問題不在 AI 寫得好不好。問題在於你根本沒機會說「階段 1 先做欄位就好，debounce 之後再說」。AI 一次把所有東西做完，你想中途喊停都很難。
第 1 步：觸發 writing-plans skill
把那句模糊需求，原封不動丟給 writing-plans。這個 skill 的工作就是「把模糊變具體」。
觸發：
使用 writing-plans skill，把「幫我加個搜尋功能」拆成實作計畫AI 回應摘要：
## 搜尋功能實作計畫
### 階段 1：清單加搜尋欄位
- 檔案：src/components/ItemList.tsx
- 介面：`<ItemList items={Item[]} query={string} />`（query 預設 ''）
- 測試：`item-list filters by query`
- 斷言：搜尋 "abc" 時只渲染 title 含 "abc" 的項目；query 為空字串時渲染全部
### 階段 2：對輸入做 debounce
- 檔案：src/hooks/useDebounced.ts
- 介面：`useDebounced<T>(value: T, delayMs: number): T`
- 測試：`useDebounced returns latest value after 300ms`
- 斷言：連續輸入三次，300ms 後只回傳最後一次的值；delayMs 固定 300
### 階段 3：標示符合字串
- 檔案：src/components/Highlight.tsx
- 介面：`<Highlight text={string} query={string} />`
- 測試：`highlight marks case-insensitive matches`
- 斷言：搜尋 "abc" 時，`<mark>` 包住 "ABC" 與 "abc"；大小寫不敏感
### 跨階段共通
- 每階段結束跑測試
- 每階段獨立 commit第 2 步：檢查計畫，決定要不要調整
拿到計畫之後別急著實作，先看一遍。常見的調整方向：
- 階段 3 的 highlight 其實不急，可以之後再說，那就把它標成「之後做」。
- 階段 1 的驗收標準不夠細，例如沒提到「搜尋空白會怎樣」，可以補上。
- 順序不對，例如你想先做 debounce 再做基本 filter（少見，但有可能）。
這個「先檢查再實作」的動作，是 writing-plans 跟「直接辦」最大的價值。你拿到的是一份可以改的計畫，不是一份不能回頭的 diff。
為什麼這份計畫有價值？
關鍵不在於「列了三個階段」。關鍵在於每個階段都有可檢查的結果：精確的介面、測試名稱與斷言。
| 模糊需求 | writing-plans 拆出來的計畫 |
|---|---|
| 「加個搜尋功能」 | 三個明確階段，每階段獨立可交付 |
| 不知道何時算做完 | 每階段有 definition of done |
| 一次改完才能看 | 階段 1 做完就能 demo 給人看 |
| 出問題難回頭 | 每階段獨立 commit，可逐階回滾 |
驗收標準最大的好處，是你跟 AI 都知道「這階段什麼時候算做完」。沒有這個共識，AI 會一直加東西、一直改，你也不知道什麼時候該喊停。
v6.4.2 起，writing-plans 對計畫的要求更精煉：只記錄實作需要的決策（檔案、介面簽名、測試斷言、規格給定的值），不把程式碼抄進計畫、也不用時間估算——上面的計畫就是這個格式。
第 3 步：把計畫交給執行型 skill
writing-plans 只負責「產出計畫」。計畫要落地，要靠執行型 skill：
- 小計畫 → 用
test-driven-development一個階段一個階段做，紅綠重構 - 多階段複雜計畫 → 用
executing-plans按計畫 todo 推進 - 想把整個流程串起來 → 用
quick-flowworkflow（brainstorming → writing-plans → TDD → verification）
下一個範例（011）會走完一遍 quick-flow，看這四個 skill 怎麼串起來交付一個完整的小功能。
常見疑問
問：計畫寫完就定案了嗎？
不用。做到一半發現遺漏（例如忘了考慮空字串），可以再觸發一次 writing-plans 補上。計畫是活的。
問：階段一定要切這麼細嗎？ 看任務大小。這個範例只有三個階段是因為搜尋功能本身就小。更大的功能可能切到七、八個階段，但每個階段的「驗收標準不能省」這個原則不變。
問：debounce 為什麼不放在階段 1 一起做？ 因為階段 1 的目標是「能 filter」。debounce 是優化，不是核心功能。分開的好處是階段 1 做完就能 demo，不用等優化一起來。
關鍵學習點
- 模糊需求不是 AI 的問題，是輸入的問題。
writing-plansskill 把「加個搜尋功能」這種話，逼成具體階段。 - 驗收標準（definition of done）比清單本身重要。沒有驗收標準，AI 不會知道什麼時候停。
- 階段切小，每階段獨立 commit。出問題時可以只回滾一階，不用整個重來。
- 計畫不是寫完就定案，做到一半發現遺漏，再觸發一次
writing-plans補上就好。