不只 Vibe Coding：mattpocock/skills 完整教學，建立可靠的 AI 編程工作流

你是否也有這種經驗：告訴 AI「幫我做一個會員系統」，它幾秒鐘就交出大量程式碼，但翻開一看，權限設計、錯誤處理、資料模型全都偏離你的預期。再問它修，改幾輪後程式碼愈來愈亂，最後只能重來。

這不是模型不夠強，而是工作流出了問題。AI 寫程式的速度愈快，沒說清楚的需求、缺乏測試的回饋、失控的架構，被放大的速度也愈快。

mattpocock/skills 的設計理念正是為了解決這個問題。它是 TypeScript 社群知名開發者 Matt Pocock 開源的一套 AI 工程化工作流。根據 GitHub API 在 2026 年 7 月 12 日的資料，這個 repo 已累積約 16.6 萬顆星、1.43 萬個 Fork。官方將它定位為「real engineering, not vibe coding」：讓 AI 工具依照可重複的工程流程工作，而不是漫無目的地自由發揮。

mattpocock/skills 是什麼？

它不是 Agent 框架，而是一套可組合的工程技能

這個 repo 的設計刻意保持小而可組合（small and composable）。它不是 BMAD、GSD、Spec-Kit 那種試圖「接管整個開發流程」的大型框架，也沒有自己的語法、插件 API 或運行時。

它的核心是一組 SKILL.md 格式的 Agent 工作流，分成兩類：

• User-invoked skills：開發者主動輸入指令啟動，例如 /grill-me、/to-spec、/to-tickets
• Model-invoked skills：開發者可以主動使用，也可由 Agent 依任務情境自動採用，例如 tdd、diagnose、code-review

它可以搭配 Claude Code、Codex、OpenCode，以及其他支援 Agent Skills 格式的工具使用。實際可用的 skill 與名稱仍可能隨 repo 更新，使用前應以官方 README 與 skills.sh 頁面為準。

它解決 AI Coding 的四種核心失敗

Matt Pocock 在 README 中明確指出四類反覆出現的 AI 編程失敗模式：

這四個問題的共通點是：它們都不是「模型能力不足」的問題，而是工作流斷層的問題。

安裝與初始化設定

安裝指令（30 秒完成）

安裝方式透過官方 skills.sh 安裝程式完成：

npx skills@latest add mattpocock/skills

安裝時，選擇你需要的 skills，並務必勾選 /setup-matt-pocock-skills。

為什麼一定要先跑 setup？

/setup-matt-pocock-skills 不是多餘的步驟。它會詢問三件關鍵事情，並將設定寫入 CLAUDE.md 或 AGENTS.md：

1. Issue Tracker 選擇：預設支援 GitHub、GitLab、本地 Markdown，也能記錄 Jira、Linear 等其他工作方式
2. Triage 標籤：之後 /triage 技能會用到，例如 needs-triage、ready-for-agent
3. 文件存放位置：CONTEXT.md、ADR（架構決策記錄）的路徑

後續的 PRD、issue 拆解、TDD、除錯與架構審查等 skill，都會參照這些設定。沒有 setup，Agent 仍可能繼續工作，但更容易產生模糊輸出或套用錯誤預設值。

三塊必要的基礎設施

在真正使用技能之前，建議先建立三塊基礎：

① CONTEXT.md：共享領域語言
這不是專案說明書，而是一份術語表。當你的專案把「使用者」稱為 customer、把「訂單」稱為 transaction，Agent 就會繼承這套叫法，讓命名、文件與測試都保持一致。Matt Pocock 舉例：有了共享語言，可以把「a lesson inside a section of a course is made 'real' (i.e. given a spot in the file system)」濃縮成「materialization cascade」一個詞。

② docs/adr/：架構決策記錄
只記錄難以逆轉、缺少上下文會令人困惑、且是真實權衡後的決策。例如「為什麼用 GitOps 管理告警規則，而不是直接存進資料庫」，這就值得一筆 ADR。

③ 執行一次 /setup-matt-pocock-skills
每個 repo 執行一次，確認 issue tracker、標籤與文件路徑設定正確。

技能總覽：一張地圖看清全貌

開始使用前，先理解整體流程，才不會「指令叫了，但不知道放在哪個步驟」：

v1.1 的主流程：先釐清需求，再形成規格、拆成 tickets、逐步實作，最後進行 code review。

新需求/功能想法
      ↓
/grill-with-docs（需求訪談 + 建立領域語言）
      ↓
/to-spec（整理成正式產品需求文件）
      ↓
/to-tickets（切成垂直切片的獨立 Issue）
      ↓
prototype（原型驗證不確定的設計）
      ↓
tdd（測試驅動開發，一次一個切片）
      ↓
code-review（雙軸品質審查）
      ↓
diagnose（系統化除錯）
      ↓
/improve-codebase-architecture（定期架構審查）

工程類技能完整列表：

完整流程實戰：從需求到可交付功能

以下用「AI 內容選題與排程工具」作為示範案例，帶你跑完一個中型功能的完整流程。

Step 1：用 /grill-with-docs 先問清楚，再動手

許多人習慣一開始就叫 AI「幫我做 XX 功能」。grill-with-docs 的邏輯完全相反——它讓 Agent 成為審稿人，在寫任何程式碼之前，先對你的計劃進行深度追問。

/grill-with-docs
我要做一個 AI 內容選題工具：
根據我設定的主題標籤，每天自動從 RSS 與 X/Twitter 
抓取熱門話題，讓我勾選後排程發布到各平台。

它應該追問你的事情：

• 「主題標籤」和「發布平台」在這個專案裡要怎麼命名？
• 來源資料從哪裡來？RSS API、X API 還是人工匯入？
• 「熱門」的定義是什麼？以互動量、閱讀數還是時效性排序？
• 一篇內容失效（過期、已發布過）怎麼處理？
• 排程失敗要怎麼通知？通知到哪裡？
• 草稿與已排程的狀態流是什麼？

這些問題的答案，會被沉澱進 CONTEXT.md 與 ADR，讓後續每個 session 的 Agent 都能沿用一致的術語。這通常能減少重複解釋與冗長描述，但實際節省多少 token 會受到專案規模、文件品質與模型行為影響，不宜用固定百分比概括。

Step 2：用 /to-spec 把討論轉成正式規格

/to-spec 的前身是 /to-prd。它不負責再次訪談你，而是把前面已經討論清楚的內容整合成正式規格。所以順序很重要：先 grill，再 to-spec。若你看到舊教學使用 /to-prd，那是 v1.1 之前的名稱。

一份完整的 PRD 應該包含：

• 背景與目標
• 使用者角色與核心流程
• 功能與非功能需求
• 不做什麼（Out of Scope）——這一欄非常關鍵
• 驗收標準（Acceptance Criteria）
• 風險與未決策事項

PRD 會被發布到你設定的 Issue Tracker，後續的 issue 拆解與 code review 都會參照它。

Step 3：用 /to-tickets 切成垂直切片

任務拆解最常見的錯誤是水平切片——先做資料庫、再做 API、再做前端、最後補測試。這樣的問題是長時間沒有可驗證的交付。

/to-tickets 的前身是 /to-issues。它強調垂直切片：每個 ticket 都走完 schema → API → UI → tests 一條完整的窄路徑。

以內容選題工具為例，拆法如下：

1. Issue #1：建立資料模型（Topic、Source、ContentItem），加上 CSV 匯入
2. Issue #2：顯示今日熱門清單，支援主題篩選
3. Issue #3：勾選內容、設定排程時間，建立 scheduled_posts 表
4. Issue #4：排程失敗的重試機制與通知
5. Issue #5：草稿狀態管理與過期內容自動歸檔

每個 Issue 都小而獨立，適合由 Agent 自主取用執行，也適合多人並行開發。

大型計畫先用 wayfinder 找出路線

當任務橫跨多個模組、現有文件與架構決策時，直接拆 tickets 容易漏掉依賴關係。v1.1 新增的 wayfinder 會先研究 codebase、領域文件與既有決策，整理出可執行的 milestones，再交給後續流程實作。它適合「知道目標，但還不知道該從哪裡切入」的大型變更。

Wayfinder 的價值不是代替實作，而是在動手前先盤點路線、依賴與里程碑。

Step 4：設計不確定時，先用 prototype 驗證

prototype 專門用來回答設計問題，而不是正式實作。它能快速跑出幾個差異很大的版本供你選擇：

• 排程介面要用日曆視圖、清單視圖，還是拖拉式時間軸？
• 「草稿」→「已排程」→「已發布」的狀態流直觀嗎？
• 多平台同時發布的授權設定，放在哪個層級比較好？

prototype 是可拋棄的：UI 問題做成單一路由中幾個互相切換的界面版本；邏輯問題做成可執行的 terminal 程式。選好方向後，原型就丟掉，進入正式 TDD 流程。

Step 5：用 tdd 一次只完成一件可驗證的事先寫出會失敗的行為測試，再完成最小實作，最後重構並進入下一個行為。

tdd 的核心是**紅-綠-重構（red-green-refactor）**循環，每次只針對一個行為：

範例：為「排程去重」寫 TDD

/tdd
為以下行為寫測試：
當同一篇 ContentItem 在 24 小時內已被排程發布過，
系統不可再次建立相同平台的排程，應回傳錯誤訊息。

流程：

1. 寫一個會失敗的測試（Red）
2. 寫剛好讓測試通過的最小實作（Green）
3. 重構，讓程式碼更清晰
4. 繼續下一個行為

關鍵是「一次一個行為」，不是先寫所有測試再一次實作所有功能。TDD 的價值在於每一步都有可驗證的回饋，讓 Agent 不會盲目批量生成程式碼。

測試應該驗證行為（behavior），不驗證實作細節（implementation detail）。這樣後續重構模組時，測試不會因為內部結構改變而大面積失效。

Step 6：Bug 不要直接叫 AI「修一下」，改用 diagnose

對比兩種 prompt 的差別：

❌ 排程重複發布了，幫我修一下

✅ /diagnose
部分 ContentItem 在重新觸發排程後出現重複發布。
請先建立穩定的重現步驟，最小化問題場景，
提出假設並加上觀測，確認根因後才修正，
最後補上回歸測試防止再次出現。

diagnose 的標準流程：

1. Reproduce：建立穩定的重現步驟
2. Minimise：縮小到最小復現場景
3. Hypothesise：提出可證偽的假設（「如果 X 是原因，改變 Y 應讓 bug 消失」）
4. Instrument：加上觀測日誌（建議加前綴，例如 [DEBUG-1234]，修完後方便搜尋刪除）
5. Fix：確認根因後才動手修改
6. Regression test：補上測試，防止問題重新出現

這套流程特別適合處理：難以定位的間歇性 bug、效能回歸、以及涉及多個模組的複雜問題。

Step 7：定期跑 /improve-codebase-architecture 防止架構腐化

這個技能不是「讓 AI 自動大重構」，而是讓它掃描程式庫，用可視化 HTML 報告提出架構深化的機會，由你決定要不要深入改。

Matt Pocock 建議的執行時機：

• 完成一個中型功能後
• 連續完成 3-5 個 issue 後
• 發現測試越來越難寫時
• 相同邏輯在多個地方重複出現時

它的分析重點是將「淺模組（shallow module）」深化成「深模組（deep module）」——接口簡單、複雜度封裝在內部、呼叫者不需要知道太多細節。

技能快速選擇指南

這張表可以幫你在實際開發中快速選到對的技能：

不同規模專案的推薦組合

快速 MVP / 個人小工具

/grill-me → prototype → tdd

先問清楚目標，快速做原型驗證，用 TDD 穩住核心邏輯。

中型功能（推薦預設流程）

/grill-with-docs → /to-spec → /to-tickets → prototype → tdd → code-review

適合中後台系統、AI 工具、SaaS 功能開發。

大型系統 / 長期維護

/grill-with-docs → /to-spec → /to-tickets → prototype → tdd
→ /triage → diagnose → /improve-codebase-architecture → /handoff

企業級系統不要追求「一個指令解決全部」。真正有效的是在不同階段調用不同 skill，讓人始終參與關鍵決策。

code-review：雙軸審查確保品質

code-review 是一個雙軸並行的 model-invoked skill：

• 軸一：Standards——是否符合 repo 的 coding standards，以及 Fowler 的程式碼壞味（code smells）基準？
• 軸二：Spec——目前的 diff 是否忠實實現了原始的 issue 或 PRD？

兩個維度由平行 sub-agent 執行，互相不干擾，確保品質檢查與規格符合度的判斷都是獨立的。

導入前的三個心態調整

1. 它不會自動讓模糊需求變清楚

Skills 可以讓 Agent 問出更好的問題，但「商業取捨、優先順序、驗收門檻」仍要由人做決定。Agent 是工程流程的加速器，不是產品判斷的替代者。

2. 小專案不必每一步全跑

如果只是快速修一個小 bug：

diagnose → tdd（補回歸測試）

如果只是探索一個新概念：

/grill-me → prototype

不需要為了「完整」而跑所有 skills。

3. 真正的成本是「遵守流程的紀律」

這套方法短期看起來較慢——它要求先問、先寫、先測、先確認。但它的設計用意正是減少 AI 快速生成錯誤功能後帶來的返工、除錯與架構債。

Matt Pocock 在 README 中引用 Kent Beck 的話：「Invest in the design of the system every day.」 這不是在講架構的宏大理想，而是在說：每一天，每一個任務，都值得做出正確的工程選擇。

與其他 AI 開發方法的差異

最根本的差異在於：mattpocock/skills 把軟體工程幾十年積累的最佳實踐——需求澄清、領域語言、TDD、系統化除錯、架構持續改善——封裝成 Agent 可遵守的工作節點，而不是把這些事情交給 AI 自行決定。

實戰建議：從哪裡開始？

如果你現在正在用 Claude Code 或 Codex，這是推薦的導入順序：

1. 第一週：安裝後只用 tdd 和 diagnose，感受有回饋循環和沒有的差別
2. 第二週：在每個新功能前加上 /grill-with-docs，開始建立 CONTEXT.md
3. 第三週：加入 /to-spec 和 /to-tickets，讓任務拆解也進入工作流
4. 每隔幾天：跑一次 /improve-codebase-architecture，讓架構不要悄悄腐化

不要一開始就試圖跑完所有技能。從最讓你痛苦的環節開始。如果問題是需求總是對不齊，就先導入 grill-with-docs；如果 bug 修完後反覆出現，就從 diagnose 開始。

結語

mattpocock/skills 最值得學的不是那幾個斜線指令的名稱，而是它背後的核心主張：

AI coding 的品質，不取決於你能不能叫 AI 一次生成更多程式碼；而取決於你能否讓它在清楚的脈絡、可驗證的回饋與可維護的架構中工作。

會寫程式的人會越來越多。真正拉開差距的，是誰能把 AI 放進可維護、可驗證、可長期演進的工程體系裡。

這個 repo 目前包含從需求訪談、PRD、issue 拆解、TDD、除錯、code review 到架構改善的完整工程能力。你可以先選最痛的一個環節導入，不必強迫自己一次接受整套流程。

GitHub：github.com/mattpocock/skills（MIT License；星數與 skill 清單會持續變動）

References

: mattpocock/skills：官方 GitHub Repository
: mattpocock/skills：skills.sh 安裝頁與 skill 清單
: setup-matt-pocock-skills：官方 SKILL.md
: diagnose：官方 SKILL.md
: tdd：官方 SKILL.md
: grill-with-docs：官方 SKILL.md
: improve-codebase-architecture：官方 SKILL.md
: Matt Pocock：New Skills! v1.1 brings /wayfinder, /research, /implement, /to-spec, /to-tickets