「依 X 篩選」這類指令、寫之前必須澄清三件事：

1. 篩選的定義域是「已載入的子集」還是「全部結果」？
2. 資料源是一次性給完整 dataset 還是分批 / 限額？
3. 「沒命中」與「還沒抓到」要不要在 UI 上區分？

三問沒跑完就直接寫、必然寫成視覺層 post-filter（最容易實作的版本）、撞上 #55 Filter 與 Source 的層錯位。

這是 #16-23 第三輪指令澄清 的第 5 類：篩選類指令。

跟前四類的差別：

• 空間 / 位置 / 隔離類（#16-#18）— 缺的是幾何資訊（數字、layout、邊界）
• 決定權類（#21）— 缺的是誰拍板（visible 三問）
• 篩選類（本卡）— 缺的是操作的層級（filter 的 stream 範圍 = 哪一層的「一筆」）

前四類的澄清能避免實作走錯方向、第 5 類能避免架構上錯層（#55 層錯位）。

為什麼篩選指令需要獨立的澄清協議

「依 X 篩選」的指令在使用者口中是一個簡單訴求、在實作上有兩個獨立決策：

• 語意決策：filter 的定義域是哪一層？
• UX 決策：邊界 state（loading / empty / partial）怎麼呈現？

兩個決策不澄清、執行者預設選最簡單版本（view 層 + silent fail）— 但這版本對應的使用者意圖通常不是使用者真的要的。

三問模板

問 1：定義域

1「依 X 篩選」是指：
2
3(a) 在已載入的結果裡找 X 符合的（filter 範圍 = 已抓的子集）
4(b) 在所有結果裡找 X 符合的（filter 範圍 = 完整 dataset）
5(c) 重新搜尋、把 X 當成 query 條件（filter ≡ 改 query）
6
7通常 (b) 是使用者預期、但實作成本看 (c) 是不是 source 支援的。哪一個？

回答決定 filter 該寫在哪一層（見 #55）。

問 2：資料源型態

1資料源是：
2
3(a) 一次性給完整 dataset（靜態陣列、一次 fetch 到底）
4(b) 分批 / 限額（pagefind、paginated API、infinite scroll）
5(c) Streaming（SSE / WebSocket、來多少看多少）
6(d) Cached + revalidate（先 cache 後 fresh）
7
8(a) 沒有層錯位風險、直接寫 view 層 filter；
9(b)(c)(d) 必須跟 source 對齊或加自動續抓 / 誠實 UX。

問 1 跟問 2 的組合決定實作模式：

問 3：空狀態區分

1當 filter 後 0 筆顯示、要不要區分：
2
3(a) 「沒命中」（已抓完、確定 0）
4(b) 「還沒抓到」（已載入子集裡 0、source 還有）
5(c) 「載入中」（fetch 還在跑）
6(d) 「載入失敗」
7
8通常 (a)(b)(c)(d) 都該區分（見 #57 三狀態）、但實作上能忍受多少混為一談？

回答決定 UX 要做到多細（見 #57 Loading / Empty / End 三狀態的區分）。

多面向：篩選指令的不同形式

形式 1：Boolean 篩選

「只看標記為 favorite 的」「只看 type = post」 — 屬性匹配、二元。

通常推到 query 層（formula: type = post）、不在 view 層 hide。

形式 2：Substring / regex 篩選

「title 含 X」「內文匹配某 pattern」 — 字串搜尋、可能跨欄位。

如果 source 有 full-text index、推到 query；沒有 → 自動續抓 + 應用 regex。

形式 3：範圍篩選

「日期在 X-Y 之間」「分數 > 80」 — 連續值區間。

通常 source 支援（SQL BETWEEN、API 的 ?from=&to=）、推到 query。

形式 4：Facet（多選交集）

「type=post AND tag=js AND date>2024」 — 多條件組合。

實作通常是 source 支援多 filter 參數、UI 提供 facet 介面。每個 facet 獨立澄清三問。

形式 5：客製計算後篩選

「閱讀時間 > 5 分鐘」「distance < 1 km」 — 需要計算、source 通常不會直接支援。

要嘛預先計算後存到 source（推到 query）、要嘛接受「在已載入子集裡計算」的語意縮小。

設計取捨：澄清的時機與形式

A：寫第一行 code 前澄清三問

• 機制：使用者下指令、執行者立刻列三問、給三問的選項、讓使用者選
• 選 A 的理由：避免錯實作、避免層錯位
• 代價：對話成本中（三問 + 選項）

B：邊寫邊發現邊問

• 機制：先寫 view 層、發現邊界 case 不對再回問
• 跟 A 的取捨：B 對話成本看起來低、但累積的重做成本高（架構已選錯方向）
• B 才合理的情境：原型 / 探索期、選錯架構成本低

C：執行者自己選一個版本、commit、看使用者驗收

• 跟 A 的取捨：C 把分析丟給使用者驗收、把使用者意圖跟實作不匹配的成本後置
• C 才合理的情境：執行者跟使用者是同一人、或預期會多輪迭代

D：忽略澄清、直接寫 view 層 silent post-filter（反模式）

• 為什麼是反模式：寫出的版本對應的不是使用者意圖、撞上 #55 層錯位、ship 後 silent 失敗
• 看起來吸引人的原因：對話成本看起來最低（不用問三問）、5 行 forEach 解決
• 實際發生的代價：使用者誤以為「沒命中」、放棄使用、得不到回報（silent 失敗最隱蔽）

判讀徵兆

核心原則：篩選指令的「簡單表面」掩蓋了三個獨立決策。澄清三問是必要、不是過度溝通 — 跳過任一問就會寫成「能用但跟意圖有縫」的版本。

適用：空間 / 尺寸（「padding 加大」「對齊」）、相對位置（「在 X 旁邊」「靠近 Y」）、隔離（「不要動 X」「跟 Y 分開」）、決定權（「breakpoint 設多少」）、篩選（「依 X 篩選」「只看 Y」）。 不適用：內部技術選擇（grid / flex、observer 種類）— 那些自決即可、見「可決定 vs 該確認」段落。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋五類模糊指令的澄清模板與「自決 vs 確認」的判準。

何時參閱本文件

為什麼模糊指令需要獨立的澄清協議

模糊指令的核心問題是指令的資訊量不足以唯一決定實作。執行者若直接寫死、結果可能跟使用者預期不符；使用者只能在看到結果後才能說「不對」、然後重做。

把澄清拉到實作前 = 用對話成本（給選項 + 推薦）換掉重做成本。但所有事都確認 = 對話爆炸。協議的價值在於分辨「該攤的」與「該自決的」。

「visible 三問」：自決還是確認

任一個答「是」 → 該確認；全「否」 → 可自決。

確認時的格式：給選項 + 推薦 + 開放修改。

較差：「Breakpoint 應該設多少？」（開放問題、把分析丟給使用者）

較好：「Breakpoint 我預估三個選項：1280px / 1400px / 1564px。我會選 1400px、有 120px 餘裕、平衡安全與緊湊。OK 嗎？或要其他？」

四類模糊指令的澄清模板

類型 1：空間 / 尺寸類（缺數字）

徵兆：「padding 加大」「對齊」「靠近一點」「再窄一些」

協議：

1. 列計算過程：「Filter sidebar 寬 = main padding + sidebar 寬度 + gap = 16 + 320 + 24 = 360px」
2. 列假設來源：「H1 高度從 design token 讀（48px）；form 高度量測（72px）；gap 16px 取自 base unit」
3. 給三檔選項（緊 / 中 / 鬆）+ 推薦

反例：直接寫 padding: 24px、沒交代為什麼是 24。使用者只能視覺驗收、不對就重做。

類型 2：相對位置類（「在 X 旁 / 上 / 下 / 之間」）

徵兆：「scope 放在搜尋框跟結果之間」「filter 在 sidebar」「按鈕靠右」

協議：

1. 用文字 ASCII 畫 layout 草圖、列出 stacking 與 viewport 行為
2. 標出錨點是誰（誰決定其他元素的位置）
3. 給選項對應「不同 layout 邏輯」、不只是位置

範例草圖：

 1方案 A：grid 縱向排
 2┌─────────────┐
 3│  H1         │
 4│  Form       │
 5│  Scope      │  ← 在 form 與 results 之間
 6│  Results    │
 7└─────────────┘
 8
 9方案 B：absolute 疊在 form 下方
10┌─────────────┐
11│  H1         │
12│  Form ──┐   │
13│  [scope abs]│  ← 跳出 flow、Form 給 margin-bottom
14│  Results    │
15└─────────────┘

兩個方案 layout 邏輯不同、後續維護成本不同 — 給使用者選、不替使用者選。

類型 3：隔離類（「不要動」「分開」）

徵兆：「不要動 framework 的 DOM」「跟 X 分開」「隔離 Y」

協議：先確認「隔離」的邊界類型 — 同一句話可能是四種不同意思：

確認模板：「您說的『不要動』是哪一層？是不能動 DOM 結構、不能影響 layout、還是不能進 framework 子樹？」

類型 4：決定權類（「應該設多少」）

徵兆：使用者用問句回拋、或留下沒明說的數值

協議：使用者沒明示 → 你先給三個選項 + 推薦、再讓使用者選。使用者已明示數值 → 直接用、不要再問。

差別判斷：訊息裡有數字（即使粗略）→ 已明示；訊息裡只有概念形容（「再大一點」）→ 沒明示。

類型 5：篩選類（「依 X 篩選」「只看 Y」）

徵兆：「依 X 篩選」「只看 type=post 的」「過濾掉 Y」「title-only 搜尋」

跟前四類的差別：前四類缺幾何 / 邊界 / 拍板資訊（單一維度）、篩選類缺操作的層級（filter 該在 view / 渲染 / 資料 / source 哪一層）。沒澄清就寫 = 必然寫成最便利的 view 層 post-filter、撞上資料層分批時的層錯位。

協議：跑篩選三問。

問 1：定義域

1「依 X 篩選」是指：
2
3(a) 在已載入的結果裡找 X 符合的（filter 範圍 = 已抓的子集）
4(b) 在所有結果裡找 X 符合的（filter 範圍 = 完整 dataset）
5(c) 重新搜尋、把 X 當成 query 條件（filter ≡ 改 query）
6
7通常 (b) 是使用者預期、但實作成本看 (c) 是不是 source 支援的。哪一個？

問 2：資料源型態

1資料源是：
2
3(a) 一次性給完整 dataset（靜態陣列、一次 fetch 到底）
4(b) 分批 / 限額（pagefind、paginated API、infinite scroll）
5(c) Streaming（SSE / WebSocket、來多少看多少）
6(d) Cached + revalidate（先 cache 後 fresh）
7
8(a) 沒有層錯位風險、直接寫 view 層 filter；
9(b)(c)(d) 必須跟 source 對齊或加自動續抓 / 誠實 UX。

問 3：空狀態區分

1當 filter 後 0 筆顯示、要不要區分：
2
3(a) 「沒命中」（已抓完、確定 0）
4(b) 「還沒抓到」（已載入子集裡 0、source 還有）
5(c) 「載入中」（fetch 還在跑）
6(d) 「載入失敗」
7
8通常都該區分、但實作上能忍受多少混為一談？

三問的詳細展開（含 5 種篩選形式 / 跨情境範例 / 後端 + 演算法）見 #58 篩選類指令的澄清時機；解法策略見 #59 Filter × Source 合成策略五選一。

Wrong vs Right 對照

範例 1：缺數字的指令

使用者：「filter sidebar 太窄了、加寬一些」

錯：直接改 width: 400px、commit、等使用者驗收。

對：

1目前 sidebar 是 320px、main padding 是 16px。我列三個選項：
2
3- 360px：+40、適合多 1 個 facet column
4- 400px：+80、舒展、跟 main 1:2.5 比例
5- 440px：+120、最寬、main 會被擠到 580px 以下
6
7推薦 400px。OK 嗎？或要其他寬度？

範例 2：相對位置

使用者：「scope 放在搜尋框旁邊」

錯：腦補「旁邊 = 右邊」、用 flex row 排出來。

對：

1「旁邊」我想到三種佈局：
2
3A. Form 右側、跟 input 同一列   → flex row、會擠壓 input 寬度
4B. Form 上方                     → absolute、不影響 input
5C. Form 下方、結果之上           → grid row 排序、跟 results 共生
6
7推薦 C。或您想的是哪一種？

範例 3：隔離指令

使用者：「客製 UI 不要動到 pagefind 的 DOM」

錯：理解成「不要 querySelector 它」、結果 inject 到 framework 子樹。

對：

1確認一下「不要動」的邊界 — 是：
2
3(a) 不能 querySelector 也不能 mutate？
4(b) 可以查、不能改 attribute / textContent？
5(c) 整節點 reparent 也不行？
6
7通常 (b) + (c) 是底線（reparent 安全、attribute 改容易被 reconcile 清掉）。
8您的需求是哪一層？

自檢清單（dogfooding：清單本身遵守它教的規則）

寫完澄清訊息、回頭檢查：

• 訊息含數字或具體 layout 結構、不只有形容詞
• 給了 ≥ 2 個選項、含推薦
• 選項之間的差異是「使用者體驗 / 維護成本」、不只是「實作細節」
• 沒有把分析負擔丟回給使用者（沒寫「您覺得呢？」這種開放問）
• 純技術細節沒攤給使用者煩（grid / flex、selector 寫法）

如果 ≥ 2 項打勾失敗、訊息回到草稿重寫。

延伸閱讀

對應的事後檢討（在 content/report/ 目錄下）：

• spatial-instruction-clarification — 空間 / 尺寸類
• relative-position-instruction-clarification — 相對位置類
• isolation-instruction-clarification — 隔離類
• decide-vs-confirm-boundary — 可決定 vs 該確認的完整判準

Last Updated: 2026-04-26 Version: 0.1.0

requirement-protocol 是一套對話協議 skill，原生位置在 .claude/skills/requirement-protocol/ 供 Claude runtime 呼叫；這份是同內容的文章版本，讓人類讀者也能直接在 blog 閱讀。

把「使用者下指令 → 執行者實作」之間的溝通流程結構化、避免反覆失敗、避免做出使用者沒要的東西、避免在錯誤方向上累積沉沒成本。源頭是 content/report/ 累積的 50+ 篇事後檢討、由本 skill 的五份 reference 萃取對應五個情境的協議步驟。

閱讀順序

場景 1：第一次接觸

場景 2：已熟悉協議、想直接解決當前任務

直接依觸發情境跳對應 reference：

每份 reference 自包含：讀任一份不需要回頭讀其他 reference。

與 blog 專案其他資料的關係

Last Updated

2026-04-26 — 初版：v0.1.0 同步、五份 references 對應「模糊指令 / 失敗轉折 / 成本與 checkpoint / 漸進驗證 / 工具切換」五個情境。