mattpocock/skills 系列(4):AI 開工寫程式前,先決定要看哪一種訊號
工作單準備好後,AI 會同時寫程式與測試。本文說明 implement、tdd、diagnosing-bugs 與 prototype 各自靠什麼判斷做對了,並用按席次計費的例子實際跑一輪從紅燈到綠燈的測試。
在上一篇的推演裡,to-tickets 把按席次計費切成三張工作單,每張都貼上了 ready-for-agent,表示資訊已經齊全,可以交給 AI 接手。現在要開一個新的對話,讓 AI 實作其中一張「停用成員並釋放席次」。它會自己改程式、自己寫測試,最後回報「測試全部通過」。
可是這些測試也是 AI 寫的,它可能只是在替自己剛寫的程式背書,根本沒對照需求。程式和測試都由 AI 寫,你要看什麼才知道它做對了?
mattpocock/skills 把這一段交給四個 skill:implement、tdd、diagnosing-bugs 與 prototype。每個 skill 判斷「做對了」所看的訊號都不一樣。
mattpocock/skills 系列|第 4 篇
- 上一篇(第 3 篇):先找出缺口,再決定要寫規格還是拆工作單
- 下一篇(第 5 篇):程式寫完之後,誰來看結構、審修改、解衝突
- 系列導讀:這套 skill 是什麼、六篇該怎麼讀
按席次計費的 skill 呼叫流程是我依原始指令推演的;文中的紅燈與綠燈測試輸出,則是我實際執行的結果。
版本提醒(2026-10-19 查證):這篇以
1.2.3版為準。mattpocock/skills已在 2026-10-04 發布1.3.0和1.3.1,本文介紹的四個 skill 都還在,但有三點不同:
- 原本還在試驗中的
implement-spec移入官方 plugin。它會一次實作整份規格,用 worktree(同一個 repo 的多個工作目錄)平行處理多張工作單,是逐張使用implement之外的另一種做法。- 同樣移入官方 plugin 的
retro是主線最後一步,在code-review之後回顧這次工作。tdd、diagnosing-bugs讀的詞彙表從CONTEXT.md改名為GLOSSARY.md。另外,
1.3.1起ask-matt會在修完 bug 後建議執行retro。這個系列之後我會依新版全面更新。
先認識幾個詞
下面幾個詞會反覆出現:
| 本文用詞 | 原文 | 意思 |
|---|---|---|
| 紅燈、綠燈 | red、green | 測試失敗顯示紅色,通過顯示綠色。先寫一個會失敗的測試,再寫剛好讓它通過的程式,這一來一回就是一輪 |
| 測試接點 | seam | 從外面觀察程式行為的公開入口,例如一個對外提供的函式。測試只從這裡進去,不碰內部細節 |
| 回饋迴路 | feedback loop | 一條可以反覆執行、立刻告訴你「對」或「錯」的指令,例如一次測試或一個腳本 |
| 原型 | prototype | 只為了回答一個設計問題而寫、之後不會直接上線的程式 |
四個 skill 各看一種回饋訊號
這四個 skill 都放在 repo 的 skills/engineering/ 底下,套件授權是 MIT。它們在 ask-matt 路線圖上的位置不同:
flowchart LR
G[grill-with-docs 談需求] -->|對話談不定| P[prototype]
P -->|帶回答案| G
G --> T[to-spec、to-tickets]
T --> I["implement + tdd"]
I --> R[code-review]
B[東西壞了] --> D[diagnosing-bugs]
圖中的位置出自 ask-matt 的主流程、專門處理「東西壞了」的入口,以及只靠對話談不定設計問題時才走的岔路。implement 實作每張工作單時都搭配 tdd,完成後再跑 code-review。code-review 負責審查這次修改的程式,第 5 篇我會介紹。
四個 skill 判斷做對了的依據各不相同:
| skill | 靠什麼判斷做對了 |
|---|---|
implement | 型別檢查、測試,以及最後的 code-review |
tdd | 事先確認的測試接點上,一個先紅後綠的測試 |
diagnosing-bugs | 一條已經對這個 bug 亮過紅燈的指令 |
prototype | 由人實際點過或看過之後的反應 |
implement 把工作單交給測試與審查
implement 是四個 skill 裡最短的一個。扣掉檔案開頭的 front matter 設定區塊,整份指令只有五行:
1
2
3
4
5
6
7
8
9
Implement the work described by the user in the spec or tickets.
Use /tdd where possible, at pre-agreed seams.
Run typechecking regularly, single test files regularly, and the full test suite once at the end.
Once done, use /code-review to review the work.
Commit your work to the current branch.
逐行看下來,AI 會做下面五件事:
- 讀你指定的規格或工作單,依照內容實作。
- 能用
tdd的地方就用,而且只在事先談好的測試接點上寫測試。 - 過程中經常跑型別檢查與單一測試檔,整套測試只在最後跑一次。
- 做完後呼叫
code-review審查這次的修改。 - 把成果 commit 到目前的分支。
第 3 點要留意:整套測試只在最後跑一次,所以這張工作單沒有動到的測試檔,要到最後才會執行。如果這次修改不小心弄壞了別處的功能,也要到那時才會發現。
implement 不會自己啟動,要由你明確呼叫,AI 不會因為聊到「開始寫吧」就自行執行它。這是因為它有兩個設定:
- front matter 設定了
disable-model-invocation: true。 agents/openai.yaml寫了allow_implicit_invocation: false。
功能要分好幾次對話才做得完時,ask-matt 建議每張工作單各跑一次 implement,兩張之間清空對話內容。因為每張工作單已經寫明所需資訊,上一張的對話不必保留。
tdd 先約定在哪裡測,再一次只做一小段
implement 的第二行把測試交給 tdd。tdd 先處理「在哪裡測」,再處理「怎麼測」。
它的規則要求 AI 在寫任何測試之前,先列出準備測試的接點,並請你確認。原文的理由是不可能每個地方都測,先談好接點,測試才會集中在最重要的流程與最複雜的邏輯上。
AI 開始探索程式時,若專案裡有 CONTEXT.md 就先讀,讓測試名稱沿用專案的共用詞彙。這份詞彙表就是第 2 篇用 grill-with-docs 留下的那一份。
接點確認後,才進入紅綠循環:
flowchart TD
A[列出測試接點] --> B{你確認了?}
B -->|否| A
B -->|是| C[寫一個測試,看它亮紅燈]
C --> D[寫剛好讓它通過的程式]
D --> E{還有要測的行為?}
E -->|有,接點已確認| C
E -->|需要新的接點| A
E -->|沒有| F["重構留到 code-review"]
循環規則有三條:
- 先紅後綠。 只寫剛好讓這個測試通過的程式,不替後面還沒寫的測試預先做準備。
- 一次一小段。 每一輪只處理一個接點、一個測試與一份最小實作。
- 重構不在循環裡。 重構是指不改變程式行為、只整理寫法,這件事留到
code-review階段再做。
tdd 另外點名三種反模式:
| 反模式 | 長什麼樣子 | 會出什麼問題 |
|---|---|---|
| 綁死實作細節 | 模擬自己的內部模組、測試私有方法,或繞過介面直接查資料庫 | 程式行為沒變、只是整理了寫法,測試卻壞了 |
| 同義反覆 | 預期值用和程式一模一樣的算法重算一遍 | 測試怎樣都會通過,永遠不會和程式唱反調 |
| 水平切分 | 先把所有測試寫完,再一次寫完所有實作 | 測到的是想像中的行為;還沒動手實作,測試的架構就先定死了 |
第三種的解法是垂直切分:一個測試配一份實作,再進下一輪,每一輪都根據上一輪學到的東西調整。上一篇 to-tickets 切工作單用的 tracer bullet 概念,在這裡又出現一次,只是尺度縮小到單一測試。
要模擬的對象也有限制。mocking.md 只允許在系統邊界使用替身,替身是用假的物件頂替程式原本依賴的東西。系統邊界是程式與外界接觸的地方,例如付款或寄信等外部服務、時間與亂數;自己寫的模組與內部元件不用替身。
diagnosing-bugs 先做出會亮紅燈的指令
tdd 處理「還沒寫的程式」,diagnosing-bugs 處理「已經壞掉的程式」。它的第一階段直接寫著「This is the skill」,意思是整個 skill 的重點就在這一步。在做出一條會對這個 bug 亮紅燈的指令之前,AI 不准開始推測原因。
有了這條指令,才進入後面五個階段:
flowchart TD
A[做出會亮紅燈的指令] --> B{做得出來?}
B -->|否| S[停下來向你要環境或紀錄]
B -->|是| C[重現並縮小]
C --> D[提出 3 到 5 個假設]
D --> E[加觀察點逐一驗證]
E --> F{找得到測試接點?}
F -->|是| G[先寫回歸測試再修正]
F -->|否| H[improve-codebase-architecture]
G --> I[清理]
原文列出十種做法,大致依序嘗試。排在最前面的幾種是:
- 一個會失敗的測試
- 對開發伺服器送請求的腳本
- 帶固定輸入的 CLI 指令
- 操作瀏覽器的腳本
排在最後的是 scripts/hitl-loop.template.sh,只有在一定要人動手點畫面時才用。這個範本提供兩個函式:step 顯示一步操作並等你按 Enter,capture 把你輸入的觀察結果記下來。最後它把結果印成 KEY=VALUE,交回給 AI。
第一階段有四項完成條件。AI 必須提出一條已經實際跑過的指令並貼出執行結果,而這條指令要做到:
- 會走到出錯的程式路徑,並檢查使用者回報的那個症狀。
- 每次執行的結果都一樣。
- 幾秒內跑完。
- AI 可以自己執行,不必等人在旁邊操作。
偶爾才出現的 bug 不求每次重現,目標是把重現率拉高。原文舉例,重現率 50% 的 bug 還追得下去,1% 就追不了。
真的做不出迴路時,AI 要停下來列出試過的方法,再向你要以下其中一項:
- 能重現問題的環境
- 去除機密後的紀錄檔
- 在正式環境暫時加上監測的許可
有了迴路之後,其餘五個階段各有要做到的事:
- 重現並縮小。 確認亮紅燈的是使用者回報的那個症狀,再每次拿掉一項輸入或步驟,直到剩下的每一項都缺一不可。
- 提出假設。 一次列出 3 到 5 個排過優先順序的假設,每個都寫明它預測會發生什麼,並先給你看。你不在時,AI 照自己的排序繼續。
- 加入觀察點。 觀察點是在程式裡印出中間值等除錯輸出。每個觀察點對應一個假設,一次只改一個變因。除錯用的輸出一律加上像
[DEBUG-a4f2]這樣的前綴,結束時搜尋一次就能全部刪掉。 - 修正並補回歸測試。 回歸測試用來確認同一個 bug 不會再出現,要先寫一個會失敗的回歸測試,再修正。前提是找得到正確的測試接點。如果找不到,也說明了一件事:現在的程式結構沒辦法用測試擋住這個 bug 再次出現。這時
ask-matt把後續交給improve-codebase-architecture,下一篇我會介紹。 - 清理。 重跑原本的迴路、確認回歸測試通過、刪掉
[DEBUG-開頭的輸出,並把最後證實的假設寫進 commit 或 PR 訊息。
第 2 步的假設要寫成「如果原因是 X,那麼改變 Y 會讓 bug 消失」,寫不出預測的假設要丟掉或改寫。套在席次上,我會寫成「如果原因是停用時沒有把成員移出已指派名單,那麼在停用流程補上移除動作,可用席次就會正確增加」。
prototype 用拋棄式程式回答一個設計問題
前三個 skill 都能靠指令判斷對錯,但有些設計問題得讓人親手試過,才會發現哪裡不對。例如:成員被停用後又要重新啟用,工作區卻剛好沒有可用席次了,這時該怎麼處理?
prototype 一開頭就寫明,原型是回答一個問題的拋棄式程式,要回答什麼問題,就決定原型做成什麼樣子。它分成兩條路:
| 要回答的問題 | 產物 | 怎麼使用 |
|---|---|---|
| 這套邏輯或狀態模型對不對 | 一個獨立的 HTML 檔,連按兩下就能開 | 按按鈕推動狀態,看每一步後的完整狀態 |
| 這個畫面該長什麼樣子 | 同一個網址路徑上的數個版本,用 ?variant= 切換 | 用畫面底部的浮動列左右切換版本 |
邏輯原型要寫給不寫程式的人使用。LOGIC.md 要求按鈕與狀態都用領域語言標示,畫面分成三塊:
- 目前狀態
- 可以自由操作的按鈕
- 分成數個分頁的引導情境
每個情境都從同一個初始狀態開始,整組情境要涵蓋順利的流程、棘手的邊界情況,以及一個應該被拒絕的操作。用來回答問題的那段邏輯,要寫成一個不碰網頁元素的獨立模組,問題解決後可以直接搬進正式程式。
畫面原型預設做 3 個版本,最多 5 個。版本之間要有結構上的差異,例如版面、資訊層次或主要操作方式不同。
UI.md 說,三個只稍微調整過的卡片格線不是原型,只是桌布:看起來各有花色,卻沒有回答任何設計問題。它也建議把版本直接放進既有頁面,因為頁面周圍的真實資料與導覽列才能暴露設計問題。
版本之間要在版面與操作方式上有所不同,只換顏色看不出設計差異。
兩條路共用六條規則:
- 原型從第一天就標明是拋棄式。
- 一個指令或連按兩下就能啟動。
- 預設不存資料。
- 不寫測試與錯誤處理。
- 每次操作後都把完整狀態顯示出來。
- 收尾時,驗證過的決定寫進正式程式。原型本身則 commit 到主線以外的拋棄式分支,並在實作工作單上留下指向該分支的說明。
ask-matt 把這個分支命名為 prototype/<name>。主線只留下驗證過的結論。
測試由 AI 自己寫,靠兩條規則才算數
開頭問過:AI 自己寫程式也自己寫測試,測試會不會只是在替程式背書?tdd 靠兩條規則防止這種情況。
第一條是測試位置由你確認。 前面提過,AI 列出的接點要經過你同意,才能在那裡寫測試。我建議趁這一步,把「停用成員後可用席次增加」這類需求裡寫明的行為,指定為一定要驗證的項目。
第二條是預期值要有獨立來源。 tdd 在說明同義反覆這個反模式時,要求預期值來自程式以外的依據,例如已知正確的數值、手算過的例子或規格。tests.md 用同一個加總函式示範了兩種寫法:
1
2
3
4
5
6
7
8
9
10
11
// BAD: Expected value is recomputed the way the code computes it
test("calculateTotal sums line items", () => {
const items = [{ price: 10 }, { price: 5 }];
const expected = items.reduce((sum, i) => sum + i.price, 0);
expect(calculateTotal(items)).toBe(expected);
});
// GOOD: Expected value is an independent, known literal
test("calculateTotal sums line items", () => {
expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
});
第一種寫法的 expected 用 reduce 重算一次。程式怎麼算,測試就怎麼算,所以它永遠會通過。第二種寫法直接寫 15,這個數字可以拿規格或手算核對,所以程式算錯時測試就會失敗。
不過,這兩條規則都只是寫在 Markdown 裡的指令,沒有程式強制執行。我看過 tdd 資料夾,裡面沒有任何檢查腳本。整個資料夾只有 SKILL.md、tests.md、mocking.md 與一份 agents/openai.yaml。
AI 列出接點時,你若沒細看就按同意,第一條規則等於沒有作用。所以我認為,測試算不算數,要你自己看兩樣東西:你確認過的接點清單,以及每個預期值能不能在規格裡找到出處。
哪些地方要花你的時間
這四個 skill 讓你不必再憑感覺判斷做完了沒。但照我的整理,下面這些環節都要有人付出心力,多半落在你身上:
| 環節 | 由誰付出 | 付出什麼 |
|---|---|---|
呼叫 implement | 你 | 每張工作單手動呼叫一次,兩張之間清空對話 |
tdd 寫測試前 | 你 | 逐一檢查 AI 列出的測試接點 |
implement 收尾 | AI 與你 | 跑完整套測試與 code-review,你要看審查結果 |
diagnosing-bugs 第一階段 | AI,必要時是你 | 原文要求在這裡投入不成比例的心力;做不出迴路時,要由你提供環境或紀錄 |
diagnosing-bugs 提出假設 | 你 | 看一遍假設排序,補上你知道的背景 |
prototype 交付後 | 你或領域專家 | 實際點過每個情境或每個版本,並說出哪裡不對 |
prototype 收尾 | 團隊 | 維護 prototype/<name> 分支,並在工作單上留下指向它的說明 |
在我看來,最花時間的是 diagnosing-bugs 的第一階段。原文認為迴路做對了,bug 就等於修好了九成,所以時間都花在這裡。
什麼情況用哪一個
我建議照你手上的狀況挑:
| 你手上的狀況 | 使用的 skill | 不適用的時候 |
|---|---|---|
有貼上 ready-for-agent 的規格或工作單 | implement | 還沒有規格或工作單時,先回到 to-spec,或單獨用 tdd |
| 沒有規格,只想先寫測試、再做出一個具體功能 | tdd | 連公開介面該長什麼樣都還沒定,就先用 codebase-design 的詞彙討論介面 |
| 功能報錯、結果錯誤或變慢,第一眼找不到原因 | diagnosing-bugs | 做不出會亮紅燈的指令時,AI 會停下來向你要環境或紀錄,不會直接猜 |
| 狀態模型或畫面,只靠對話判斷不了 | prototype | 問題能在對話中談定時,留在 grill-with-docs 繼續問 |
模擬情境:實作「停用成員並釋放席次」
以下流程是我依 1.2.3 版的原始指令推演的。其中的紅燈與綠燈測試,我在 Node.js v25.2.1 上實際跑過;程式是我為這篇寫的最小範例,並非取自 mattpocock/skills。
假設前兩張工作單「顯示工作區已購買與可用席次」與「把可用席次指派給成員」都已完成。你開一個新的對話,附上第三張工作單:
1
$implement <停用成員並釋放席次的工作單連結>
AI 讀完工作單與 CONTEXT.md 後,會依 tdd 的規則先列出測試接點。例如「工作區對外提供的 deactivateMember() 與 availableSeats()」。你要確認兩件事:
- 這兩個函式是不是其他程式實際會呼叫的入口。
- 驗收條件裡的「可用席次增加一席」能不能從這裡觀察到。
你同意後,AI 寫下第一個測試。預期值的依據是規格裡的「測試決定」欄位:停用成員後,可用席次要增加一席。以買了 5 席、指派 2 席為例,停用其中一人後,可用席次要是 4。
把下面內容存成 seats.test.js:
1
2
3
4
5
6
7
8
9
10
11
12
13
import { test } from "node:test";
import assert from "node:assert/strict";
import { createWorkspace, assignSeat, deactivateMember, availableSeats } from "./seats.js";
test("停用成員後,可用席次增加一席", () => {
const workspace = createWorkspace({ purchasedSeats: 5 });
assignSeat(workspace, "alice");
assignSeat(workspace, "bob");
deactivateMember(workspace, "alice");
assert.equal(availableSeats(workspace), 4);
});
此時的 seats.js 只有前兩張工作單完成的部分,deactivateMember() 還是空的:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
export function createWorkspace({ purchasedSeats }) {
return { purchasedSeats, assigned: new Set() };
}
export function assignSeat(workspace, memberId) {
workspace.assigned.add(memberId);
}
export function deactivateMember(workspace, memberId) {
// 尚未實作
}
export function availableSeats(workspace) {
return workspace.purchasedSeats - workspace.assigned.size;
}
在同一個資料夾放一份內容為 { "type": "module" } 的 package.json,接著執行單一測試檔:
1
node --test seats.test.js
結果亮紅燈,實際可用席次是 3,預期是 4:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
✖ 停用成員後,可用席次增加一席 (0.92075ms)
ℹ tests 1
ℹ suites 0
ℹ pass 0
ℹ fail 1
...
✖ failing tests:
test at seats.test.js:5:1
✖ 停用成員後,可用席次增加一席 (0.92075ms)
AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
3 !== 4
at TestContext.<anonymous> (file:///<已遮蔽路徑>/seat-tdd/seats.test.js:12:10)
...
紅燈代表這個測試抓得到「停用後沒有釋放席次」的問題。接著只寫剛好讓它通過的程式,也就是把 // 尚未實作 換成一行:
1
2
3
export function deactivateMember(workspace, memberId) {
workspace.assigned.delete(memberId);
}
再跑一次同一條指令,結果轉成綠燈:
1
2
3
4
5
6
7
8
9
✔ 停用成員後,可用席次增加一席 (0.343958ms)
ℹ tests 1
ℹ suites 0
ℹ pass 1
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 43.76225
這只完成了一輪。工作單的驗收條件還包括「計費系統收到新的席次數量」,但它不在剛才確認的接點清單裡。所以 AI 要先把計費系統這個接點補進清單、請你確認,再繼續下一輪,每輪一個測試。
全部完成後,implement 跑完整套測試、呼叫 code-review,再 commit 到目前的分支。你要看的是審查結果,以及每個測試的預期值能不能對回規格。
如果之後收到「停用成員後,可用席次沒有增加」的回報,上面那條 node --test 就是 diagnosing-bugs 第一階段要的迴路。它對這個症狀亮過紅燈,而且從上面的 duration_ms 看,不到 50 毫秒就跑完,符合「幾秒內跑完」的條件。
implement 的品質取決於工作單
這一節是我自己的看法,原始資料沒有直接這樣說。
implement 沒有說工作單寫得模糊時該停下來問誰,也沒有規定驗收條件不完整時怎麼處理。它只把「在事先談好的接點上測試」交給 tdd。而那些接點與預期值,大多早在 to-spec 確認檢查點、to-tickets 寫下驗收條件時就決定了。
所以我不會期待 implement 補救一張切得不好的工作單。AI 列出的接點若對不上驗收條件,或預期值在規格裡找不到,我會暫停實作,回到 grill-with-docs 或 to-spec 把缺的內容補齊。
這個看法只適用於照這套流程先寫規格、再切工作單的專案。單獨用 tdd 做一個小功能時,接點與預期值是在當下的對話裡直接談定的,沒有事先寫好的規格或工作單可以回頭補。
接下來
判斷 AI 做對了沒,要看它自己改不了的東西。換到你自己的專案,可以開一個新的對話,照模擬情境的指令,對一張已貼上 ready-for-agent、沒有前置工作的工作單執行 implement。AI 列出測試接點時逐一確認;它寫出測試後,再核對每個預期值都能在規格裡找到。
下一篇介紹程式寫完之後的四個 skill:
codebase-design與improve-codebase-architecture:看程式結構。code-review:審查這次的修改。resolving-merge-conflicts:解決合併衝突。
延伸閱讀
implement:五行指令全文。tdd:接點確認規則、三種反模式與紅綠循環。tdd/tests.md:好測試與壞測試的對照範例。diagnosing-bugs:十種建立迴路的方法與各階段的完成條件。prototype:邏輯原型與畫面原型怎麼分流、做完要保留什麼。


