mattpocock/skills 系列（3）：先找出缺口，再決定要寫規格還是拆工作單

上一篇已經把按席次計費的需求談完。CONTEXT.md 寫下了「計費席次」與「成員」的差別，對話中也確認了成員停用後怎麼處理。接下來要把這些結論變成可以開工的工作，眼前卻有五個看起來都跟「規劃」有關的 skill：to-spec、to-tickets、triage、wayfinder 與 to-questionnaire。

這五個 skill 都會產出文件，補的卻是不同的缺口。選錯了，AI 一樣會把指令執行完，你卻只多了一份暫時沒人用得上的文件。

mattpocock/skills 系列｜第 3 篇

• 上一篇（第 2 篇）：把模糊需求問清楚，留下共用詞彙

本文資料以 1.2.3 版為準。文中的按席次計費流程依原始指令推演，不是實測輸出。

先認識幾個詞

這五個 skill 都圍繞著團隊的工作追蹤工具運作。下面幾個詞會反覆出現：

本文用詞	原文	意思
工作追蹤工具	issue tracker	團隊記錄待辦事項的地方，例如 GitHub Issues。每件事是一張卡片，可以貼標籤、留言，也能標示先後順序
規格	spec	說明一整項功能要做成什麼樣子的文件
工作單	ticket	從規格切出來、可以單獨完成的一小項工作
一次對話	session	與 AI 從開始到結束的一段工作過程。AI 在一次對話中能處理的內容有上限，內容累積太多時，判斷就會變得不夠精準

五個 skill 各自補不同的缺口

一般的功能開發有一條主線：先透過訪談釐清需求，再開始實作。功能小到一次對話就能做完時，談完直接實作即可。要分成好幾次對話才做得完時，才會在中間加入 to-spec 與 to-tickets。前者把談定的內容整理成規格，後者再把規格切成一張張工作單。ask-matt 的主流程也要求這兩步接在需求訪談之後，並留在同一段對話裡進行，讓 AI 記得前面談過的內容。

另外三個 skill 不在主線上。triage 處理別人送進來的工作，wayfinder 處理大到一次談不完的工作，兩者整理完後都會接回主線。to-questionnaire 則負責去找握有答案的人。

眼前缺少什麼	使用的 skill	留下什麼
需求已經談清楚，但還沒寫成正式規格	to-spec	工作追蹤工具裡的一份規格
規格還沒切成可以分開完成的工作	to-tickets	一組標明先後順序的工作單
別人送來的回報還沒查證與分類	triage	分類、處理狀態，以及給 AI 的交接說明
工作大到連該做哪些決定都列不完整	wayfinder	一張「地圖」與多張待決定的「決策單」
關鍵答案在另一個人手上	to-questionnaire	一份交給對方填寫的問卷

五個名稱放在同一張清單裡，不代表每次都要全部執行。

to-spec 只整理已經談過的內容

to-spec 依據的是目前的對話內容，以及 AI 對現有程式的了解。它的第一條規則明確要求不要再訪談你，只整理已經討論過的內容。因此，需求裡若還有沒談定的問題，這時呼叫它也得不到答案，那些空白只會原封不動地留在規格裡。

整理之前，AI 會先了解專案現況、沿用詞彙表裡的名稱，並遵守過去留下的決策紀錄（ADR，上一篇介紹過）。接著它要決定「之後從哪裡檢查這個功能有沒有做對」。原始規則偏好越接近使用者實際操作的位置越好，檢查點也越少越好，最理想的情況是只有一個。這一步需要人工確認，AI 會先問你這些檢查點是否符合預期。

你確認後，to-spec 才把規格發佈到工作追蹤工具，並貼上 ready-for-agent 標籤，意思是「資訊已經齊全，可以交給 AI 接手」。規格有固定的欄位：要解決的問題、解法、使用者故事、實作決定、測試決定、這次不處理的範圍，以及補充說明。其中「使用者故事」是一種描述需求的固定句型：「身為某種角色，我希望能做某件事，以便得到某種好處。」

規格裡不寫具體的檔案位置或程式碼，因為程式一改，這些細節很快就會過時。唯一的例外是：先前做過的試作裡，若有一小段內容比文字更能精確表達某項決定，才節錄其中最關鍵的部分。

短小的工作不一定需要規格。如果整項功能能在這次對話裡做完，主流程會直接進入實作。

to-spec 範例

假設團隊已經確認兩件事：成員停用時，立即收回他的席次；本期帳單不因此退費，減少的席次從下一期帳單開始計算。to-spec 可以把對話整理成下面這段規格（節錄）：

## 問題

工作區管理者不清楚停用成員後，席次何時會釋放出來，因此容易算錯可用席次與帳單金額。

## 使用者故事

1. 身為工作區管理者，我希望停用成員後立即看到可用席次增加，以便把席次改指派給其他成員。

## 實作決定

- 停用成員時，立即收回他的席次。
- 本期帳單不退費，減少的席次從下個計費週期開始反映在帳單上。

## 測試決定

- 模擬管理者停用一位成員，確認可用席次增加一席。
- 確認計費系統收到新的席次數量，並標註從下個計費週期生效。

## 不處理的範圍

- 本次不處理按使用天數比例退費。

這份規格只收錄已確認的答案。如果「從下一期帳單開始計算」還沒經過財務確認，to-spec 就不應該自行替團隊寫進去。這時要先用後面介紹的 to-questionnaire，把答案問回來。

to-tickets 讓每張工作單都是一小段完整功能

to-tickets 可以接手一份規格、一份計畫、一張既有的工作卡片，或直接使用目前的對話。它讀完所有內容後，把工作切成一張張工作單。

切法有一個重點：每張工作單都要是「從頭到尾都能運作」的一小段功能，而不是「只做其中一層」。軟體功能通常分成好幾層，例如保存資料的地方、處理規則的程式、使用者看到的畫面，以及檢查功能的測試。原始規則把這種切法稱為 tracer bullet，也就是曳光彈。夜間射擊時，曳光彈會發光，讓射手看清彈道並即時修正。同樣地，先讓一小段功能完整打通每一層，團隊就能立刻看到方向對不對。只改資料或只改畫面的工作單，都不符合這項規則。

同一項功能要切成能獨立完成的小段，而不是依技術層拆成互相等待的工作單。

原始規則替每張工作單設了兩個可以檢查的條件：第一，完成後能單獨展示或驗證；第二，份量要能在一次全新的對話裡做完。每張工作單也要列出「前置工作」，也就是開始前必須先完成的其他工作單；沒有前置工作的工作單可以立刻開始。切分規則與前置關係都寫在 to-tickets/SKILL.md。

AI 不會直接把第一版切法寫出去。它會先列出每張工作單的標題、前置工作，以及完成後能做到什麼，再請你檢查：切得太粗還是太細？前置關係是否真的必要？有沒有哪幾張該合併或再拆開？你同意後，它才依專案的設定，把工作單寫成專案資料夾裡的檔案，或建立在工作追蹤工具中。發佈規則也禁止它順手關閉或修改原本那張總需求卡片。

有一種工作是例外：牽連整個專案的機械式修改，例如替一個到處都在使用的欄位改名。這種修改一動就會影響整個專案，沒辦法切成一段段能獨立運作的功能。原始規則改用「先擴充、再收斂」（expand-contract）的做法：先讓新舊寫法同時存在，確保不會壞掉；再分批把各處換成新寫法；最後確認沒有地方還在用舊寫法，才把它刪除。

to-tickets 範例

同一份席次規格不會拆成「改資料」、「改程式」和「改畫面」三張工作單。其中一張可以寫成：

# 管理者可以把可用席次指派給成員

前置工作：顯示工作區已購買與可用席次

## 完成後能做到什麼

管理者在成員頁面選擇一個未使用的席次並完成指派後，該成員就能使用付費功能，頁面上的可用席次也少一席。

## 驗收條件

- [ ] 完成指派後，可用席次顯示少一席。
- [ ] 被指派的成員立即能使用付費功能。
- [ ] 沒有可用席次時，系統拒絕指派並說明原因。

這張工作單從資料保存到畫面都要修改，但完成後就能單獨展示。之後的「停用成員並釋放席次」會把它列為前置工作，因為系統要先能指派席次，才能驗證收回席次的行為。

triage 接手別人送進來的工作

triage 原本是急診的「檢傷分類」，這裡指整理不是你親手建立的工作：使用者回報的問題、別人提出的功能需求；若專案有設定，也包括外部人士直接送來的程式修改（PR）。to-tickets 產生的工作單已經貼上可以交給 AI 的標籤，不需要再送去分類。

每個項目都會貼上一個分類和一個狀態。分類只有兩種：bug 代表有東西壞了，enhancement 代表新功能或改進。狀態則有五種：

狀態	意思
needs-triage	等待維護者評估
needs-info	等待回報者補充資訊
ready-for-agent	資訊齊全，可以交給 AI 處理
ready-for-human	需要由人處理
wontfix	決定不處理

如果同一個項目出現互相矛盾的狀態，triage 的狀態規則要求先提出來詢問維護者，再做其他事。

分類不能只看回報的文字。AI 會先讀完整串討論，確認程式裡是否早已有同樣的功能，並查看過去被拒絕過的類似需求。接著它提出分類與狀態的建議，然後停下來等維護者指示。之後它會依照回報的步驟重現問題、確認回報屬實，必要時再追問細節。最後依結果處理：可以交給 AI 的，留下一份交接說明；需要人處理的，用同樣格式寫，並註明為什麼不能交給 AI；資訊不足的，列出已確認的事項和還需要回報者補充的問題；功能其實早就存在的，就指出它在哪裡，然後關閉。完整處理順序把查證、追問與更新狀態分成不同步驟。

triage 範例

假設有使用者送來一則回報，內容只有一句「停用成員後，可用席次沒有增加」。AI 讀完回報、查過現有程式後，先向維護者提出分類建議。維護者同意後，它再依照回報的描述操作，確認問題存在。整理後的結果可能如下：

欄位	內容
分類	bug
狀態	ready-for-agent
查證結果	停用成員後，該成員已無法使用付費功能，但席次仍記在他名下；重新整理頁面後，可用席次依然沒有增加
比對既有規則	席次規格要求停用後立即釋放席次，專案中也沒有推翻這條規則的決策紀錄
交接說明	找出停用成員時漏掉收回席次的環節並修正；完成後，停用一位成員，可用席次應增加一席

如果查證後發現系統其實已經釋放席次，只是畫面沒有更新，交接說明就應把範圍縮小到畫面顯示。如果回報沒有說明使用哪一種方案、做了哪些操作，狀態就應先改成 needs-info，請回報者補充，而不是猜測原因。

wayfinder 先處理還列不完整的決策

有些工作大到一次對話看不清全貌，連「需要做哪些決定」都還列不出來。wayfinder 的字面意思是「找路的人」。它會先在工作追蹤工具裡建立一張「地圖」，記下終點是什麼、已經做了哪些決定、哪些地方還看不清楚，以及哪些事不在這次的範圍內。已經能清楚說出來的問題，則各自開成一張「決策單」。

決策單完成時產出的是一項決定，不是做好的功能。wayfinder 的規則要求它預設只做規劃，不動手實作。每次對話最多只解決一張決策單；唯一的例外是單純查資料的決策單，可以同時交給多個 AI 分頭查。答案寫在該張決策單的留言裡。決策單關閉後，地圖上只加一行摘要與連結，細節仍留在決策單裡。如果某個答案讓原本看不清楚的地方變得明確，就再開一張新的決策單。

如果第一輪盤點就發現所有問題都很清楚，整件事也能在一次對話中談完，就不需要地圖，AI 會停下來問你打算怎麼進行。等地圖上的決定全部完成，流程會回到 to-spec，把分散在各張決策單的答案整理成一份規格，再交給 to-tickets。

wayfinder 範例

假設要把既有的「依成員人數計費」改成「依指派席次計費」，團隊一開始可能還不知道要做哪些決定。這時可以先把目前看得見的部分寫成地圖：

# 席次計費轉換地圖

## 終點

所有既有工作區改用席次計費，轉換期間不重複收費，也不中斷付費功能。

## 備註

- 新工作區直接採用席次計費。
- 既有合約在續約前維持原價。

## 已做的決定

（目前還沒有。每關閉一張決策單，就在這裡加一行摘要與連結。）

## 還看不清楚的地方

- 既有成員要如何轉換成席次指派。
- 轉換失敗時，如何恢復原本的帳單與使用權限。

## 不在這次範圍內

- 不重新設計價格方案。

地圖本身不列出還沒解決的決策單，它們另外開在工作追蹤工具裡，歸在這張地圖底下。這次可以先開出兩張：「既有工作區要分幾批轉換，出問題時何時暫停」，以及「新舊計費並行期間，帳單要以哪一套數字為準」。

第一張決策單解決後，原本列在「還看不清楚的地方」的「轉換失敗時如何恢復」，可能變得能寫成明確的問題，例如「單一工作區轉換失敗時，在什麼條件下要退回舊的計費方式」。這時 wayfinder 才把它開成新的決策單，並從「還看不清楚的地方」移除。它不會一開始就假裝已經列出所有問題。

決策單另外開在地圖底下；一張決策單的答案，可能讓下一個問題變得能具體提出。

to-questionnaire 去找握有答案的人

有些問題查不到，也不該由正在對話的人決定。換個情況來看：假設財務負責人還沒確認席次增減後要從哪一期開始計費。to-questionnaire 會把這類問題整理成一份問卷，讓對方有空時填寫，或在會議中一起填。

它只問你兩件事：問卷要交給誰（對方的角色、專長，以及和你的關係），以及你需要帶回哪些答案。它不會要求你代替對方回答專業問題。問完後，它會在目前的資料夾產生一份依主題命名的問卷檔案，例如 to-questionnaire-seat-billing.md。

問卷會交代目的、背景與回答方式。問題依重要性排序，因為對方可能只會填一次；每題只問一件事，最後再留一題「還有什麼我們沒問到、但應該知道的？」答案收回來之後，才成為 grill-with-docs 或 to-spec 的素材，ask-matt 也把這兩個流程列為問卷的後續去向。問卷本身不替專案做決定。

to-questionnaire 範例

若答案在財務負責人手上，產生的 to-questionnaire-seat-billing.md 可以包含：

# 席次異動的計費規則

**目的：** 確認席次增減從哪一期帳單開始生效，讓產品與計費系統採用同一套規則。

**寄件人：** 產品負責人　**收件人：** 財務負責人

## 回答方式

請於本週五前回覆，約需 10 分鐘。每題選一個選項；選「其他」時，請補上生效時間與計算方式。不確定的題目請直接註明「不確定」，不必跳過。

## 月繳方案

1. 新增席次後，何時開始收費？
   - 指派當下起，按剩餘天數比例收費
   - 從下個計費週期開始收費
   - 其他：

2. 釋放席次後，何時停止收費？
   - 釋放當下起，按剩餘天數比例退費
   - 本期不退費，從下個計費週期停止收費
   - 其他：

## 年繳方案

3. 年繳合約的席次增減，有哪些規則與月繳不同？若完全相同，請填「相同」。

## 其他

4. 還有什麼我們沒問到、但應該知道的？

收件人填回答案後，團隊才能把「本期不退費」這類結論寫進規格。問卷列出選項只是為了方便回答，不代表團隊已經傾向其中哪一個。

都會留下文件，但用途不同

五個 skill 都會留下文字。看產物接下來要交給誰，就能分辨它們的差別。

產物	內容	接下來交給誰
規格	整項功能已確認的需求與決定	to-tickets，或直接開始實作
工作單	一次對話做得完的一小段完整功能	實作（implement）
交接說明	外部回報的查證結果，以及接手所需的資訊	AI 或負責處理的人
決策單	一個待決定的問題，以及最後的結論	後續的決策單，或 to-spec
問卷	專案缺少、需由特定對象補上的答案	grill-with-docs 或 to-spec

規格與工作單都可能貼上 ready-for-agent，但份量不同：規格涵蓋一整項功能，工作單只是其中一小段。功能大到一次對話做不完，才需要再切成工作單。

規劃多一層，也多一輪人工確認

這套流程沒有省掉人工確認，而是把確認放在文件寫出去之前。

使用 to-spec 時，你要確認檢查點；使用 to-tickets 時，你要確認切分的粗細與前置關係。triage 會先提出建議，再等維護者指示；to-questionnaire 則需要你說明收件人是誰、要帶回什麼答案。

wayfinder 花費的人力最多。它把一次談不完的工作拆成許多決策單，而且每次對話通常只解決一張，這些時間都由參與決策的人付出。若問題本來就能在一次對話裡列清楚，建立地圖只會讓工作追蹤工具多出一堆需要維護的項目。

先看資訊缺在哪裡

選擇時，先看眼前的狀況：

目前狀況	下一步	可以跳過什麼
需求已談清楚，但要分好幾次對話才做得完	to-spec，接著 to-tickets	不需要 wayfinder
需求已談清楚，一次對話就做得完	直接實作	to-spec 與 to-tickets 都可跳過
收到別人送來、還沒查證的回報	triage	不必先寫新規格
連該做哪些決定都列不出來	wayfinder	先不急著切工作單
某項決定需要特定的人提供答案	to-questionnaire	不讓 AI 猜答案

這張表只決定現在從哪裡開始。wayfinder 完成後會回到 to-spec；問卷收回後，答案也能帶回需求討論。主線以外的 skill 負責補齊缺口，補完之後再回到主線。

模擬情境：把按席次計費切成可開工的工作

以下沒有實際執行這些 skill，因為它們會寫入專案的工作追蹤工具或目前的資料夾。內容依 1.2.3 版的原始規則推演，實際結果會隨專案內容、既有的決策紀錄與對話內容而不同。

延續上一篇的情境：CONTEXT.md 已定義計費席次、成員與席次指派，停用、指派與計費時點也都在對話中確認了。團隊判斷這項功能要分好幾次對話才做得完，所以在同一段對話裡呼叫：

$to-spec

AI 會先查看現有程式，再提出檢查點。假設團隊確認，最能一次檢查整個功能的位置是「席次異動完成後，計費系統收到正確的席次數量」。AI 便把談過的問題、解法、使用者故事、實作與測試決定整理成規格，經你確認後發佈。

規格建立後，仍在同一段對話裡附上規格連結：

$to-tickets <規格連結>

AI 會先列出切分草案，例如：

工作單	完成後能做到什麼	前置工作
顯示工作區已購買與可用席次	管理者能看到席次總數與剩餘數量	無
把可用席次指派給成員	管理者完成指派後，成員能使用付費功能	顯示工作區已購買與可用席次
停用成員並釋放席次	停用後收回席次，計費系統收到新的席次數量	把可用席次指派給成員

這時要檢查三件事：每張工作單能否單獨驗證、是否一次全新的對話就做得完，以及前置關係是否真的必要。例如，「指派席次」的驗收條件要看到可用席次少一席，所以確實得等「顯示席次」先完成。你同意後，AI 才把工作單寫進工作追蹤工具。這些工作單已經貼上 ready-for-agent，不必再經過 triage。實作時，每張工作單各自開一次新的對話；工作單已寫明所需資訊，不必依賴先前的對話內容。

如果財務還沒確認席次增減何時反映在帳單上，就先用 to-questionnaire 向負責人取得答案，再回來完成規格。如果連轉換期間要做哪些決定都無法一次列清楚，則改用 wayfinder 建立地圖。缺口不同，起點就不同。

我會先找缺口，不會把五個都跑一遍

前面介紹的輸入、產物與使用時機，都能在原始指令裡查到。以下則是我的個人判斷，原始資料並不能證明這套做法一定能節省時間。

我會先問自己：現在缺的是規格、可以開工的工作、對外部回報的判斷、大型工作的決策，還是另一個人才知道的答案？確定之後，再選一個 skill。

把五個 skill 全跑一遍，文件會變多，問題卻不一定更清楚。triage 不需要處理自己剛切好的工作單；已經能列清楚問題的工作，也不需要 wayfinder。每次只補眼前的缺口，產出的文件才有明確的下一位使用者。

這項判斷適用於透過工作追蹤工具交接工作，而且工作會跨好幾次對話的團隊專案。如果只是想在這次對話裡完成一個小修改，直接實作即可。

先決定下一份文件要交給誰

需求談完後，該從哪個 skill 開始？先看下一份文件要交給誰，以及目前缺的是哪一種資訊。

需要一份完整的需求說明交給後續規劃，就用 to-spec；需要讓好幾次新的對話各自開工，再接著用 to-tickets。別人送來的回報交給 triage，列不完整的大型決策交給 wayfinder，只有別人知道的答案則用 to-questionnaire 去問。

回到按席次計費的情境，最小的下一步是留在同一段對話裡執行 to-spec，確認檢查點，再依工作量決定要不要切成工作單。

延伸閱讀

• to-spec：查看規格的固定欄位、檢查點的確認方式與發佈規則。
• to-tickets：核對工作單的切分規則、前置關係，以及兩種工作單格式。
• triage：了解別人送來的回報如何經過分類、查證與狀態轉換。
• wayfinder：查看地圖、決策單、前置關係與逐張解決的流程。
• to-questionnaire：了解問卷如何依收件人與所需答案安排問題。