適用：空間 / 尺寸（「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

適用：

• 客製需求要對抗多層（vendor CSS、framework reconciliation、browser default、UA stylesheet）
• 收到「先還原」「先重來」「換個方向」「我們重新開始」這類指令

不適用：純 greenfield 開發（沒有舊代碼要對抗、沒有探索成果要保留）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋成本告知模板、checkpoint 命名慣例、reset 前的確認協議。

何時參閱本文件

為什麼成本要攤開、為什麼 revert 要 checkpoint

成本攤開的價值

當客製要對抗多層、執行者沉默地堆疊 !important + specificity hack + polyfill — 結果使用者：

1. 看到「能用」的成果、以為成本低
2. 升級 vendor / 換 browser 後壞掉、驚訝於維護負擔
3. 不知道有沒有更便宜的替代方案（換 vendor、放棄該客製、改設計）

把成本攤開 = 使用者在執行前就決定值不值、不在事後後悔。

Revert 含 checkpoint 的價值

探索的成果即使沒採用、仍然是「為什麼不採用」的證據。直接清空：

1. 下次遇到類似需求、可能再走一遍同樣的死路
2. 失去 A 跟 B 兩條路的對比基礎
3. 部分技術選擇（命名、結構）可能仍有用、被連帶丟掉

Checkpoint 把「探索」與「採用」分開記錄、保留比較與恢復的可能。

成本告知協議

步驟 1：列出對抗的層

寫第一條規則前、列出將打到哪幾層：

步驟 2：估規則數量與風險

 1這個客製需要打到：
 2- Vendor CSS（pagefind 主題色）：寫 3-4 條規則覆蓋預設色
 3- Framework reconciliation（drawer 內容會被重渲染）：把客製 UI 放邊界外
 4- 升級風險：pagefind 升級 minor 版本、選擇器改名 → 客製樣式失效
 5
 6建議方案：
 7A. 完整客製（如上）— 工時 1 hr、升級時要重檢
 8B. 只改 CSS variable（如果 vendor 提供）— 工時 5 min、升級安全
 9C. 放棄客製、用 vendor 預設 — 工時 0、視覺差異使用者要接受
10
11推薦 B（如果 vendor 有提供 var）、否則 A。哪一個？

步驟 3：使用者選擇後再開始

不管選 A / B / C、選擇本身已經被攤開。使用者後續看到維護負擔、不會驚訝。

Revert / Checkpoint 協議

步驟 1：確認還原目標

使用者說「先還原」時、回問：

1「還原」是指：
2
3(a) 丟掉所有未 commit 的修改、回到 HEAD
4(b) 回到某個特定 commit（哪一個？）
5(c) 部分還原（哪些檔案 / 哪些功能）
6(d) 換思路、但保留結構（命名、檔案組織保留、實作換掉）
7
8我建議先做 commit 把當前進度保存、再 reset — 您是哪一種？

步驟 2：commit 當前進度當 checkpoint

不管是哪種還原、先 commit：

1git add -A
2git commit -m "checkpoint: explored [方向 X], not adopted
3
4- 嘗試了 [做法 A]、結果 [現象]
5- 假設 [Z] 驗證後不成立
6- 保留供未來對比、不採用為最終解
7"

Checkpoint commit 的特徵：

• 主題明確含「checkpoint」「explored」「not adopted」字樣
• body 寫「為什麼不採用」、不只寫「做了什麼」
• 在後續 main branch 上不會被 merge 進去（用 branch 隔離或日後 rebase 丟）

步驟 3：執行 reset

確認 checkpoint commit 完成後、執行使用者要的還原：

1# 視類型而定
2git reset --hard <target>      # 完全還原
3git checkout <commit> -- <file> # 部分還原
4git revert <commit>             # 保留歷史的還原

危險動作（git reset --hard、git checkout .、git clean -fd）執行前再次跟使用者確認 — 即使有 checkpoint commit、也要避免把 checkpoint 自己 reset 掉。

Wrong vs Right 對照

範例 1：覆寫成本

使用者：「pagefind 搜尋框的顏色改成我們的品牌色」

錯（直接做、沒攤成本）：

1.pagefind-ui__form { background: var(--brand) !important; }
2.pagefind-ui__search-input { background: var(--brand) !important; color: white !important; }
3.pagefind-ui__button { background: var(--brand-dark) !important; }
4/* ... 8 條 !important 後、終於看起來對 */

兩週後 pagefind 升級、class 名稱改了一個 — 全壞。使用者驚訝。

對（先報成本）：

1顏色客製有兩條路：
2
3A. Pagefind 提供的 CSS variables（看了 docs：--pagefind-ui-primary、--pagefind-ui-text 等）
4   → 改 4 個 var、升級安全、5 min
5
6B. 直接覆寫 class 規則（要 8 條 !important）
7   → 升級可能壞、需要追蹤 vendor changelog、1 hr
8
9推薦 A、除非您要的視覺超出 var 能控制的範圍。哪個？

範例 2：「先還原」處理

使用者：「等等先還原、這個方向不對」

錯：

1git checkout .  # 直接清空、丟掉 30 分鐘探索成果
2# 之後想對比「為什麼方向 A 不行」時、什麼都沒留下

對：

1我把當前進度先 commit 成 checkpoint、再還原 — 還原的目標是：
2
3(a) 回到開始這個方向之前的 commit（HEAD~3）
4(b) 回到 main 最新
5(c) 換個 branch、保留這個 branch 供以後參考
6
7通常 (c) 最安全、(a) 最常見。您要哪個？

確認後：

1git add -A
2git commit -m "checkpoint: explored grid-row layout, not adopted (drawer is form's child, grid invalid)"
3git reset --hard HEAD~4  # 或使用者指定的 target

Checkpoint commit 的命名慣例

checkpoint: 是本文件主推 — 比 wip: 多了「不採用」的明確標記、未來 grep git log --grep=checkpoint 能快速找到「曾經試過但放棄的方向」。

自檢清單（dogfooding）

收到客製需求或 revert 指令時：

• 寫第一條覆寫規則前、有沒有列出「對抗哪幾層、規則數量、升級風險」？
• 有沒有給使用者 ≥ 2 個選項（含「不做」或「降級客製」）？
• revert 前有沒有確認還原目標的精確意圖？
• revert 前有沒有 commit 一個 checkpoint？
• checkpoint 的 commit message 有沒有寫「為什麼不採用」、不只寫「做了什麼」？

成本沒攤、checkpoint 沒 commit → 退回去補。

延伸閱讀

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

• override-depth-cost-report — 覆寫深度的成本告知
• revert-instruction-handling — 「先還原」「先重來」類退出指令的處理

Last Updated: 2026-04-26 Version: 0.1.0

本 reference 自包含、不需讀其他 reference。把 #74-#79 系列翻譯成可直接套用的協議步驟與模板。

核心命題

對話中要使用者決策時、有五個獨立維度可以選擇 — 不該預設 collapse 到單一格子：

預設都選窄格 = 用最少自由度的問題塞使用者。每個維度該選哪邊、依情境 reason about、不是無腦套預設。

五步判讀（依序檢查）

步驟 1：選項類型 — 是執行還是反省？

判準：「這次 output 該收斂到一個答案、還是攤開多面向？」

反例：把「我們可以做卡片 / 測試 / 改流程 / 寫文章哪個？」當單選 — 強迫使用者排序、結果只有第一個被做。

修法：列全 + 標「都該做、優先 1+2、3-4 下輪」、把「全做」「跳過某幾個」「調順序」三種回應全列為合法。

步驟 2：時間軸 — 現在能決嗎？

判準：「我（agent）有沒有提供能讓使用者下決定的全部資訊？」

反例：使用者說「我再想想」、agent 加壓「那你決定了嗎？」— 把延後當失敗。

修法：決策表加最後一欄「延後（補 X 再決）」、寫具體條件（補完 X / 等到 Y / 跑完 Z 觀測）— 延後不是逃避、是有 next step 的另一種決策。

步驟 3：策略數 — 單選還是疊加？

判準：策略間 (1) 解不同層、(2) 沒副作用衝突、(3) 增量成本可接受 → 三條全滿足 = 該疊加。

反例：「五策略選一」當預設、推薦時只列一個策略。

修法：呈現選項時主動標「也可以加 X」「先 D 後 B/C」、把疊加組合列為合法回應。

步驟 4：批次邊界 — 一次還是分批？

三軸切分：

先 ship 甜蜜點：高可見 + 低風險 + 低驗證 — 例：UX hint、empty state 訊息、明顯 UI 修正。

反例：「等所有結構性修法都做完才 ship」— 把重要程度誤當成 ship 順序。

修法：明示「ship 順序 ≠ 重要程度」、可見性高 + 風險低的部分先 ship。

步驟 5：呈現格式 — 開放還是結構？

判準：「我能不能列選項 + 適配性 + 推薦？」

反例：「你想怎麼做？」— 把整個問題空間丟回去。

修法：

 1## 選項
 2
 3| 選項 | 適配性 | 取捨 |
 4|---|---|---|
 5| A ⋯⋯ | ⋯⋯ | ⋯⋯ |
 6| B ⋯⋯ | ⋯⋯ | ⋯⋯ |
 7| 延後（補 X 再決） | 等 Y | 條件：⋯⋯ |
 8
 9## 推薦
10
11我推薦 **A**、因為 ⋯⋯。想改成 B 或補充延後條件、跟我說。
12
13## 你的選擇空間
14
15- 同意（A）
16- 改（B、原因 ⋯⋯）
17- 加 / 減 / 疊加組合
18- 延後
19- 任意組合可複選（除非互斥）

完整套用範本

把五維檢查全做完後的決策呈現：

 1## 我看到的選項
 2
 3| 選項 | 適配性 | 取捨 |
 4|---|---|---|
 5| A 結構性修法 | 解根因 | 風險高、要驗證 |
 6| B UX 補強 | 立即可見 | 不解根因 |
 7| C 不做 | 0 成本 | 使用者繼續手動 |
 8| **延後（補 telemetry 再決）** | 等 context | 條件：跑完 1 週觀測 |
 9
10## 推薦組合
11
12**B 先 ship、A 下輪**（疊加 + 分批）— B 解眼前痛、A 在 telemetry 證實後再投入結構修法。C 不選因為使用者會抱怨。
13
14## 你的選擇空間
15
16- 同意（B 現在、A 下輪）
17- 改順序（A 先、B 下輪）
18- 加 / 減：把 C 加進來、或拿掉 B
19- 延後：先補 telemetry 再決
20- **任意組合可複選**（除非說明互斥）

Self-check checklist

呈現決策前用以下 checklist 檢查（每條問自己「這維度該選窄格還是鬆綁？」）：

• 選項類型：這是執行（單選）還是反省（複選）題？反省題我有沒有明示「互不衝突」？
• 時間軸：context 夠嗎？不夠的話我有沒有列「延後（補 X 再決）」選項？
• 策略數：選項間能不能疊加？三條判準（不同層 / 無衝突 / 成本可接受）滿足的話有沒有提組合？
• 批次邊界：先 ship 哪部分？有沒有把「先 X 後 Y」明示為合法回應？
• 呈現格式：用了結構表 + 推薦嗎？還是丟一句「你想怎麼做」？

任一條沒做、退一步補上、再呈現決策。

反模式快速辨識

每個變種都是「五個維度都選窄格」的展現 — 看到任一個出現在自己 draft、立刻退回五步判讀。

特別注意 Yes/No 二選（#80）— 「需要 X 嗎？」「OK 嗎？」「要繼續嗎？」這類最常見、最隱形的 collapse、把多選空間壓成 1 bit。修法是把 yes/no 翻成「現在做 X / 改 Y / 延後到 Z / 疊加 X+Y」的多選表。

真實 dogfood 例子（從本 skill 設計過程蒐集）

寫這份 reference 的對話本身、agent 多次出現 collapse 反模式。記下作為將來 self-check 的具體素材：

例 1：commit 後的「下一步」變 yes/no

Bad：「下一步依你之前的決策是 ship D（UX hint），需要我繼續嗎？」

collapse：呈現格式（單一推薦無選項）+ 選項類型（yes/no）+ 策略（單一 D）+ 批次（無選項）+ 時間（隱含立刻）= 五維全 collapse + binary。

Good：列「立刻 ship D / 寫 case study / 反省迭代 / 延後」四選 + 推薦 + 「可複選」。

例 2：列候選用無適配欄的 bullet

Bad：

1下一層迭代候選（多選）：
21. dogfood 檢驗
32. L3 trigger
43. case study
54. 倒過來補卡
65. 檢驗 #75 對 #46-#50

collapse：呈現格式（沒適配性欄）+ 沒明示「互不衝突可全做」+ 沒推薦組合 + 沒延後選項。

Good：把選項排成「| 選項 | 適配性 | 取捨 |」表 + 標「都不衝突可全做」+ 推薦「先 1+3、4-5 下輪」+ 加「延後（明天再決）」欄。

例 3：執行類決策列點未含推薦

Bad：列出 ABC 三選但騎牆「我推薦 A、不過 B 也行」。

collapse：呈現格式 layer 3「推薦不夠明確」變種、把選擇權騎牆推回給使用者。

Good：「我推薦 A、因為 X。改成 B 的條件是 Y（如果 Y 成立、改 B）。想直接改告訴我。」

例 4：反省題壓單選

Bad：「這次最該做的反省是 1（補卡片）— 要做嗎？」

collapse：反省題用 radio + 推薦 + yes/no。漏掉「全做」「跳過 1 做 2」「延後反省」三種合法回應。

Good：列五個反省方向、明示「互不衝突」、推薦優先順序、「全做」「跳過某幾個」「調順序」全列為合法。

每個 Bad 例都是 #79 五維度 collapse 的具體實例 — 寫的當下覺得「夠精簡」、實際藏掉 N 個合法選項。將來看到自己寫類似格式、立刻退回多選展開。

對應抽象層原則

• #74 決策呈現格式 — 步驟 5 的詳細展開
• #75 主策略 + 補強疊加 — 步驟 3 的詳細展開
• #76 分批 ship 準則 — 步驟 4 的詳細展開
• #77 「現在不決定」是合法選項 — 步驟 2 的詳細展開
• #78 反省任務預設複選 — 步驟 1 的詳細展開
• #79 決策對話的五維度 — 上層 meta-原則
• #67 寫作便利度跟意圖對齊反相關 — 為什麼窄格是預設（容易寫）
• #72 高 ROI 無觸發 — 為什麼鬆綁需要協議結構（不靠紀律）
• #80 Yes/No 二選是隱式 collapse — 五維 collapse 的極致形態、最常見最隱形
• #81 卡片系統的迭代浮現 — 本 reference 的成型過程（spiral 而非線性）
• #82 字面攔截 vs 行為精煉 — 為什麼用 hook 防 collapse 行不通、本 reference 是 multi-pass 設計（self-check 是第二輪、dogfood 是第三輪）

適用：debug 反覆失敗、CSS 規則不生效、JS 改完元素還原、layout 怎麼調都不對。 不適用：第 1 次失敗（修細節即可）；不同方向各自失敗 1 次（不算同方向累積）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋失敗計數、假設驗證、換方向決策、對外回報模板。

何時參閱本文件

為什麼第 2 次是轉折點

第 1 次失敗常是執行細節（typo、cache、syntax）— 修了再試通常會過。

第 2 次失敗、用同樣的方法但更小心、還是失敗 — 訊號的重量遠大於兩次相加。它說的是：「我以為的問題不在這層、根本問題在別處」。

第 3 次以上、沉沒成本綁住、加碼產生的副作用會超過解決的問題：

第 2 次是還能優雅切換方向的最後機會。

失敗計數的協議

關鍵動作是第 2 次的「停」 — 把行動從「執行更努力」切換到「驗證假設」。

假設驗證的具體方法

方法 1：用工具讀真實狀態

方法 2：反問「如果假設錯了會怎樣」

這個反思能在沒有工具的情況下測試假設。

「如果錯了會發生什麼」的答案 = 你正在看的失敗現象 → 假設可能錯。

方法 3：對外回報模板

1我嘗試了 [方向 X]：
2- 第 1 次：[做法 A] → [現象]
3- 第 2 次：[做法 B] → [一樣的現象]
4
5我的底層假設是「[假設 Z]」、但 [方法 1 / 方法 2 的驗證] 顯示 Z 似乎不成立。
6
7要不要換 [方向 W]、或您看到我沒看到的訊息嗎？

對外回報 = 把卡關放到使用者視野、避免繼續單方面加碼。

假設錯了之後：換方向 ≠ 全部重寫

換方向不是「之前的全部丟掉」、是「對抗錯假設的部分丟掉、其他保留」。

範例：search scope UI 放在「form 與 results 之間」。

• 嘗試 1-4：基於假設「drawer 是 form 的 sibling」、用 grid + display:contents + grid-row 排序 → 全失敗
• 第 5 次（用 playwright 驗證）：drawer 是 form 的 child、跟 form 共用 grid cell
• 換方向：不用 grid-row 控制位置（被假設綁住的部分）、改用 absolute + drawer margin-top（不被假設綁住）→ 一次成功

換方向後保留：CSS variable 命名、scope 命名、HTML 結構。丟掉：grid-row 規則。只丟跟錯假設綁定的代碼、不丟所有東西。

Wrong vs Right 對照

範例 1：specificity 戰

錯：

1/* 第 1 次：規則沒生效 */
2.target { color: red; }
3/* 第 2 次：加 specificity */
4.parent .target { color: red; }
5/* 第 3 次：再加 */
6.parent .container .target { color: red; }
7/* 第 4 次：放大絕招 */
8.parent .container .target { color: red !important; }

四次同方向加碼、根本問題（vendor CSS 用了更高 specificity 或更晚 cascade）沒解。

對：

 1/* 第 1 次：規則沒生效 */
 2.target { color: red; }
 3
 4/* 第 2 次失敗 → 停下來驗證假設 */
 5/* DevTools Computed → 看到 vendor 的 .pagefind .target { color: blue } 贏了 */
 6/* 假設「我的規則該贏」錯 → 換方向：CSS layers */
 7
 8@layer vendor { /* @import vendor css here */ }
 9/* 我的規則 unlayered → 自動贏所有 layered 規則 */
10.target { color: red; }

範例 2：JS 改完元素被還原

錯：

1// 第 1 次：改完被還原
2el.textContent = 'custom';
3// 第 2 次：加保護
4setTimeout(() => { el.textContent = 'custom'; }, 100);
5// 第 3 次：再加
6setInterval(() => { el.textContent = 'custom'; }, 50);  // CPU 100%

對：

 1// 第 1 次：改完被還原
 2el.textContent = 'custom';
 3
 4// 第 2 次失敗 → 停、驗證假設
 5// playwright: 看到 framework 每次 state change 重渲染整個子樹
 6// 假設「我的修改會 stick」錯 → 換方向：把客製 UI 放到 framework 邊界外
 7
 8const customEl = document.createElement('div');
 9customEl.textContent = 'custom';
10container.appendChild(customEl);  // 不在 framework 子樹內、不會被 reconcile

自檢清單（dogfooding）

第 2 次失敗時、用這份清單檢查：

• 我有沒有列出「底層假設是什麼」？
• 我有沒有用工具或反問驗證假設？
• 如果假設錯了、有沒有列出替代方向？
• 對外回報訊息有沒有寫「驗證 X、似乎不成立、要不要換 W」這種句式？
• 我有沒有避免「再試一次更小心」這種同方向加碼的衝動？

任一項打勾失敗 → 停下來補上、再決定下一步。

延伸閱讀

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

• failure-direction-pivot-point — 同方向反覆失敗的轉折點
• two-occurrence-threshold — 2 次門檻的抽象原則（跨工具 / 測試 / 思路 / 溝通四面向）
• verification-method-timing — 驗證方法的選擇時機

Last Updated: 2026-04-26 Version: 0.1.0

適用：UI layout debug、對齊問題、selector / MutationObserver root / JS 操作邊界的設計。 不適用：純內部演算法（沒有視覺、沒有範圍選擇）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋 placeholder 漸進、measurement 完整性、最小必要範圍三個共生原則。

Test-First 補充：當「漸進」的方式是「寫測試固化」時、必須走 RED → GREEN 兩個訊號才算驗證 — 詳見 #69 Test-First：先看到 RED 才相信 GREEN。沒看過 RED 的測試 = 未驗證的訊號、不能信任。

何時參閱本文件

為什麼這三個原則合併在一份 reference

三個原則服務同一個讀者群體（正在開始一個新工作、還沒卡關）、回答同一類問題（該從多大的範圍 / 多少變數起步）。

• Placeholder 漸進 = 視覺面的「一次一個變數」
• Measurement 完整性 = 對齊問題的「方程組必須完整」
• Minimum scope = JS / CSS 範圍的「窄起來再放寬」

共同精神：先窄後寬、有證據再擴張。「先寬後縮」的問題是分不出哪個寬度是刻意的；「先窄後寬」每次擴張都有原因可追。

原則 1：Placeholder 漸進除錯

UI debug 從色塊起步、加東西一次加一個。

起步：純色塊

1<div style="width: 200px; height: 100px; background: red; border: 2px solid black;"></div>

沒文字、沒樣式、沒互動。唯一目的：確認位置、尺寸、grid / flex / absolute 的定位邏輯對。

階段順序

每階段只引入一個變數、發現問題能立刻定位。跳階段 = 失敗時不知道是哪個變數錯。

典型反例

1<!-- 第 1 步直接寫真實內容 + 完整樣式 -->
2<div class="card">
3  <h3>Search results</h3>
4  <p>Showing {{count}} matches for "{{query}}"</p>
5  <ul>...</ul>
6</div>

CSS 寫了 30 條、結果 .card 沒在預期位置。是 grid 錯？font-size 影響？margin-collapse？line-height？無法定位。

原則 2：Measurement 完整性

對齊問題的本質是線性方程組：

1target_y = anchor_y + offset
2total_height = h1_height + form_height + gap + scope_height + ...

每個變數都要有明確來源 — 任一個未知 → 整組無解。

變數來源的三種類型

反例：靠估值補方程式

1/* 假設 form 大概 60px、加 gap 20px、總共 80px */
2.scope { top: 80px; }

實際 form 高度是 72px（隨字型 / line-height 變動）→ scope 跑位 8px。

對例：每個變數有來源

1const formHeight = form.getBoundingClientRect().height;  // measured
2const gap = parseFloat(getComputedStyle(form).marginBottom);  // measured
3scope.style.top = `${formHeight + gap}px`;

或全部用 design token：

1.scope { top: calc(var(--form-height) + var(--gap)); }
2/* var 在某處有單一定義、不是分散估值 */

混搭策略要全選同一邊：對齊基準上要嘛全寫死、要嘛全量測、不要 hardcoded + 估值混用。

原則 3：Minimum Necessary Scope

Selector / MutationObserver / JS 操作的範圍從最小起、擴張要有證據。

Selector 範圍

預設用最小、有證據（多個地方確實要 match）再擴張。

MutationObserver 範圍

三個維度：root、options、頻率。

1// 過寬
2observer.observe(document.body, { childList: true, subtree: true, attributes: true });
3// → 監聽整個 page、每個 attribute 變動都觸發、CPU 100%
4
5// 最小
6observer.observe(searchForm, { childList: true });
7// → 只監聽 form 直接子節點變動

JS 操作邊界

改一個元素的範圍從小到大：

從「改 inline style」起步、不行才升級。

三個原則的共同精神

從最小可驗證單位起步、有證據再擴張：

• Placeholder：色塊 → 文字 → 樣式（一次加一層）
• Measurement：每個變數先確認來源、再寫對齊規則
• Scope：最窄的 selector / observer / JS 邊界、要擴張要有具體 case

「先寬後縮」的反模式：寫一個包山包海的 selector、之後試著加 :not(...) 排除 → 永遠不知道哪些 match 是刻意的。

Wrong vs Right 對照

範例 1：UI debug 起步

任務：把搜尋結果卡片做成兩欄 grid

錯：

 1<!-- 直接寫完整版本 -->
 2<div class="results-grid">
 3  <article class="result-card">
 4    <h3><a href="...">Title</a></h3>
 5    <p class="excerpt">{{excerpt}}</p>
 6    <div class="meta"><span class="tag">tag</span> · <time>date</time></div>
 7  </article>
 8</div>
 9
10<style>
11.results-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 24px; }
12.result-card { padding: 16px; border: 1px solid; }
13.result-card h3 { font-size: 18px; margin-bottom: 8px; }
14/* ... */
15</style>

跑出來、卡片高度不一致、grid-auto-rows 沒設、第二欄擠到第一欄底下。debug 困難 — 是 grid 設定錯？卡片內容差異？margin-collapse？

對：

1<!-- 階段 1：純色塊驗證 grid -->
2<div class="results-grid">
3  <div style="height: 100px; background: red;"></div>
4  <div style="height: 100px; background: blue;"></div>
5  <div style="height: 100px; background: green;"></div>
6  <div style="height: 100px; background: yellow;"></div>
7</div>

確認 grid 兩欄正常後、再進階段 2（加占位文字）。

範例 2：MutationObserver root

任務：當 search results 出現時、注入客製 UI

錯：

1new MutationObserver(...).observe(document.body, { subtree: true, childList: true });
2// 整個 page 任何變動都觸發、callback 跑 1000+ 次/秒

對：

1const container = document.querySelector('.pagefind-ui__results-area');
2new MutationObserver(...).observe(container, { childList: true });
3// 只監聽 results area 的直接子節點變動

如果之後發現 .pagefind-ui__results-area 內部 nested 變動也要監聽 → 那時再加 subtree: true、加之前能說出「為什麼需要」。

自檢清單（dogfooding）

開始一個新工作前：

• UI debug：第 1 階段是不是純色塊（沒文字、沒樣式）？
• 對齊規則寫之前：是不是每個變數都列出來源（hardcoded / hook / measured）？
• Selector：起步是不是最精準的版本？
• MutationObserver：root / options 是不是最窄的？
• JS 改元素：是不是從「改 inline style」起、不行才升級？

任一項打勾失敗 → 退回最小、重新起步。

延伸閱讀

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

• placeholder-driven-ui-debug — 從色塊 placeholder 開始的漸進式 UI 除錯
• measurement-completeness — 量測值缺一不可
• minimum-necessary-scope-is-sanity-defense — 最小必要範圍是 sanity 防線

Last Updated: 2026-04-26 Version: 0.1.0

協議的核心命題：對話成本與重做風險之間有最佳化空間。全自決對話成本最低、但容易做錯；全確認重做風險最低、但對話爆炸。協議定的是「哪些該攤、哪些自決」、以及「卡住時該怎麼轉彎」。

Core Pillars（支柱）

Principles（原則速查）

讀者在本區塊能完成大方向判斷；具體情境的展開（步驟 / 模板 / 反例）依下方「觸發路由」進對應 reference。

1. 可決定 vs 該確認的邊界

純技術實作（grid / flex、ResizeObserver / setInterval、selector 寫法）可自決；使用者會看到的決定（breakpoint、預設尺寸、filter 順序、UI 文字、配色）先列選項給使用者點頭。

判準三問：UI 上會不會產生使用者感知的差異？選不同會不會影響體驗？寫進 commit 後改動成本高不高？ 任一個「是」 → 該確認。確認時給「選項 + 推薦 + 開放修改」、不要開放問。

2. 同方向失敗 2 次 = 停下驗證假設

第 1 次失敗多半是執行細節（typo、cache、syntax）— 修了再試。第 2 次同方向失敗、不要再試一次更小心、用工具驗證底層假設（DOM tree、computed style、framework 行為）。

驗證後分兩條路：假設對 → 繼續修；假設錯 → 換方向、不為前面的努力買單。第 3 次同方向加碼（更複雜的 selector、加 !important、再寫一層 polyfill）會放大原本的問題、產生脆弱的 patchwork。

3. 推理失敗 2 次切到量測工具

靜態 CSS 推理 + 視覺截圖溝通的迴圈在第 1 次假設錯了之後成本就爆炸。第 2 次失敗主動提：起 server、用 playwright browser_evaluate 讀 live DOM。

工具切換 ROI 在第 1 次失敗後就轉正、不要等到第 5 次。簡單一次性確認用 DevTools、複雜或反覆 debug 用 playwright（可重跑、可寫成測試）。

4. 覆寫成本攤開、不偷偷對抗

當客製需求看似簡單但會對抗多層（UA stylesheet、framework CSS、browser default）— 在開始寫之前先報成本：「會打到哪幾層、要寫幾條規則、剩下什麼風險（升級會壞？瀏覽器差異？）」、讓使用者決定值不值。

不在使用者不知情的情況下堆 !important / specificity 戰 / 多層 polyfill — 沉默對抗會讓使用者驚訝於後續的維護負擔。

5. Revert 含 checkpoint、不直接清空

收到「先還原」「先重來」「換個方向」時、先確認：還原到哪個狀態？要不要先 commit 當前進度當 checkpoint（標「explored, not adopted」）？ 再執行 reset。

探索的成果即使沒採用、也是「為什麼不採用」的證據 — 直接清空會丟掉「下次別再走這條路」的判斷依據。

6. 漸進驗證、最小必要範圍

UI debug 從色塊 placeholder 起步（沒文字、沒樣式、單純色塊）→ 確認位置 / 尺寸 / grid 對 → 再加文字 → 再加樣式 → 再加互動。每階段只引入一個變數。

Selector / MutationObserver root / JS 操作邊界：從最小開始、有證據再擴張。「先寬後縮」分不出哪個寬度是刻意的；「先窄後寬」每次擴張都有原因。

7. Multi-pass Refinement：第 1 輪不追求完美、設計第 2 / 3 輪用不同 frame

第 1 輪實作預期會有未發現問題、不要追求 perfect — 跑得到結尾、看實際結果比寫得漂亮重要。第 2 輪用「對需求 / 邊界 case」frame、第 3 輪用「dogfood / 反向自查」frame、第 N 輪換「上層原則」frame。每輪不同 frame 才能 catch 上一輪 miss 的東西。

呈現決策時的「五維度展開」（references/decision-dialogue.md）就是 multi-pass 在「決策呈現」場景的具體實現：每維度等於一輪 self-check。「再仔細一次」≠ multi-pass — 同 frame 重看 catch 不到不同層的錯。L4 review / pair / dogfood 才是行為錯誤的解、不是再寫一條 hook（#82）。

When to Consult This Skill（觸發路由）

每份 reference 自包含：以該情境為核心、把六大原則翻譯成可直接套用的協議步驟與模板。閱讀任一 reference 不需要回來看其他 reference。

Success Criteria（M1-M2 認知負擔類）

Directory Index

1requirement-protocol/
2├── SKILL.md                                       # 本檔：四支柱 + 七大原則速查 + 觸發路由
3└── references/
4    ├── clarifying-ambiguous-instructions.md       # 情境 1：模糊指令的澄清協議（spatial / relative / isolation / decision-authority）
5    ├── failure-pivot-protocol.md                  # 情境 2：失敗 2 次的轉折協議（停下、驗證假設、換方向）
6    ├── cost-and-checkpoint.md                     # 情境 3：覆寫成本告知 + revert 含 checkpoint
7    ├── progressive-verification.md                # 情境 4：placeholder 漸進 + measurement 完整性 + 最小必要範圍
8    ├── tool-switching-timing.md                   # 情境 5：推理 / DevTools / playwright 之間的切換時機
9    └── decision-dialogue.md                       # 情境 6：呈現決策的五維度協議（呈現 / 策略 / 批次 / 時間 / 選項類型）

Reading Order（建議閱讀順序）

1. 第一次接觸 → 從本 SKILL.md 的「三大支柱 + 六大原則」讀起
2. 進入實際情境 → 依觸發路由讀對應 reference（只讀一份）
3. 想驗證自己有沒有套用對 → 用該 reference 結尾的 self-check checklist 自評

相關抽象層原則（在 content/report/）

本 skill 的協議建立在幾條抽象層原則上、實作協議時可背景引用：

• #42 2 次門檻 — 第 1 次失敗是運氣、第 2 次是訊號（六大原則 2/3 的根據）
• #43 最小必要範圍 — 範圍從窄起、有證據再擴張（原則 6 的根據）
• #44 SSOT — 值的住址只能一處（成本告知與澄清的共骨）
• #45 外部組件合作四層 — 離公共介面越近越穩
• #67 寫作便利度跟意圖對齊反相關 — 容易寫的位置通常是錯位的位置（meta-principle、解釋為什麼澄清協議能 catch 到便利驅動的錯誤）
• #68 驗收的時間軸：四個 checkpoint — 寫之前 / 開發中 / ship 前 / ship 後分散驗收（原則 6 的展開）
• #69 Test-First：先看到 RED 才相信 GREEN — 「需求確認」最重要的一環：使用者意圖落實成測試 → 在 buggy code 上跑出 RED 才證明測試 catch 到該意圖、再修到 GREEN — 跳過 RED 等於跳過「測試對應到使用者意圖」的驗證
• #70 URL 是 stateful UI 的儲存層 — 列「使用者意圖完整集合」要包含 URL 維度：分享 / reload / back-forward 該不該保留 state
• #71 Tab Order = DOM Order = Mental Model 三者對齊 — A11y 維度的需求澄清：使用者預期「先做 X 再做 Y」、tab 順序該對齊 mental model
• #72 高 ROI 無外部觸發的工作會被結構性跳過 — meta-原則：澄清 / Checkpoint 1 / RED phase 都是「沒便利路徑」工作、修法是 L3-L5 結構性對策（PR template / CI / pair）、不是「下次記得」
• #73 搜尋引擎的匹配模式跟使用者預期的對齊 — Checkpoint 1 列「使用者意圖完整集」要包含「使用者打字行為的預期」：工具預設 matching mode（prefix）跟使用者預期（substring，被 Google 訓練）對齊嗎？
• #74 決策呈現：選項 + 推薦 + 開放修改 — 不要開放問、給結構表 + 推薦、把整理問題的成本攤在 agent 而非 user
• #75 主策略 + 補強：選擇不必互斥 — 多策略可疊加（structural + UX）、預設「五選一」會放掉互補可能
• #76 分批 ship：可見性 + 風險 + 驗證三軸切分 — 「ship 順序 ≠ 重要程度」、低風險可見價值先 ship
• #77 「現在不決定」是合法選項 — 決策表加「延後 + 條件」欄、區分逃避決策 vs 結構性延後
• #78 反省任務預設複選 — 互斥要證明、不互斥是預設、反省題用 radio = 結構性 collapse
• #79 決策對話的五維度 — meta-#74-#78、五個獨立維度的鬆綁、預設都選窄格 = 把使用者塞進最少自由度的盒子
• #80 Yes/No 二選是隱式 collapse — 「需要 X 嗎？」「OK 嗎？」最常見最隱形的 collapse、修法是翻成多選表
• #81 卡片系統的迭代浮現 — 本 skill 的 reference 是 spiral 浮現、不是線性寫成、process-level 元原則
• #82 字面攔截 vs 行為精煉 — 驗證手段跟錯誤層次對齊、行為錯誤（如 collapse）靠 multi-pass spiral 收斂、不是「補一條 hook 規則」、本 skill 的 reference + dogfood examples + self-check 就是 multi-pass 設計

Last Updated: 2026-04-26 Version: 0.7.0 — Phase B1 結構升級：加第 4 pillar「Multi-pass Refinement」+ 第 7 原則、明示 multi-pass 在「需求協議」場景的展開、串連 #82 / #83 / #85 Version: 0.6.0 — 補 #82 (字面攔截 vs 行為精煉)：點出 hook 對行為錯誤無能為力、本 skill 的 reference + self-check + dogfood examples 就是 multi-pass 設計、不是「再補一條 hook 規則」 Version: 0.5.0 — 補 #80 (yes/no collapse) + #81 (卡片迭代浮現)、reference 加 dogfood examples 段（4 個 Bad/Good 對照）、#75 加 selector stacking 跨連 #46-#50 Version: 0.4.0 — 接入 #74-#79 決策協議系列：新增第 6 份 reference decision-dialogue.md（五維度：呈現 / 策略 / 批次 / 時間 / 選項類型）；觸發路由加 3 條入口（呈現決策 / 開放問 / 反省題）；相關抽象層原則段補 #74-#79 Version: 0.3.0 — 接入 #69-#73：相關抽象層原則段補 Test-First (#69)、URL state (#70)、tab order (#71)、外部觸發 meta (#72)、search 匹配模式 (#73) Version: 0.2.0 — 接入 #55-#68 系列：clarifying-ambiguous-instructions 加第 5 類「篩選類」（呼應 #58）；觸發路由加篩選類入口；SKILL.md 加「相關抽象層原則」段（#42-45 + #67-68） Version: 0.1.0 — 從 content/report/ 50+ 篇事後檢討萃取「需求 → 實作對話協議」這條主軸；五份 references 對應「模糊指令 / 失敗轉折 / 成本與 checkpoint / 漸進驗證 / 工具切換」五個情境

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 / 漸進驗證 / 工具切換」五個情境。

適用：CSS / DOM debug、layout 卡關、不確定該用哪個工具。 不適用：純邏輯 bug（這時 logging / debugger 比 layout 工具有用）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋四種工具的 ROI 對照、切換時機、最低門檻入口。

何時參閱本文件

為什麼工具切換要早、不該等到推理徹底失敗

CSS 行為由「規則 + DOM tree + 樣式繼承 + 框架渲染」四個變數共同決定。靜態推理只能基於假設的 DOM tree — 假設錯了、推理就錯。視覺截圖只能傳達「結果是什麼」、無法傳達「為什麼」。

Playwright 的 browser_evaluate 直接執行 JS 在 live page、返回真實的 DOM tree、computed style、bounding rect — 把四個變數全部變成已知。

門檻在第 2 次：第 1 次推理快（假設正確時一次到位）；第 2 次推理失敗 → 假設可能錯 → 繼續推理會在錯誤假設上累積。Playwright 起步成本中、但後續穩定。

四種工具的 ROI 對照

選擇順序：

Playwright 在開發循環的三個位置

位置 1：假設驗證（寫 CSS 規則前）

確認 DOM 結構符合假設。

1async () => {
2  const drawer = document.querySelector('.pagefind-ui__drawer');
3  let chain = []; let n = drawer;
4  while (n && n !== document.body) {
5    chain.push(`${n.tagName}.${n.className}`);
6    n = n.parentElement;
7  }
8  return chain;
9}

返回值對照假設、發現 drawer 是 form 的 child（不是 sibling）→ grid-row 控制無效、改方向。

位置 2：行為驗證（layout 規則寫完後）

驗證實際 layout 結果。

1async () => ({
2  rect: document.querySelector('.target').getBoundingClientRect(),
3  computedTop: getComputedStyle(document.querySelector('.target')).top,
4  computedDisplay: getComputedStyle(document.querySelector('.target')).display,
5})

位置 3：互動驗證（使用者操作後的狀態）

1async () => {
2  const input = document.querySelector('.search-input');
3  input.value = 'pre';
4  input.dispatchEvent(new Event('input', { bubbles: true }));
5  await new Promise(r => setTimeout(r, 1000));
6  return Array.from(document.querySelectorAll('.result'))
7    .filter(el => getComputedStyle(el).display !== 'none')
8    .map(el => el.textContent.slice(0, 50));
9}

第 2 次同個 bug → 寫成測試固化

第 1 次 debug 完、bug 修好。第 2 次同個版型問題（不同 commit / 不同 viewport）再出現 → debug 完後把 query 寫成 playwright 測試。

1test('search scope is between form and results', async ({ page }) => {
2  await page.goto('/search/?q=pre');
3  const formRect = await page.locator('.pagefind-ui__form').boundingBox();
4  const scopeRect = await page.locator('.scope-toggle').boundingBox();
5  const resultsRect = await page.locator('.results').boundingBox();
6  expect(scopeRect.y).toBeGreaterThan(formRect.y + formRect.height);
7  expect(resultsRect.y).toBeGreaterThan(scopeRect.y + scopeRect.height);
8});

未來 layout 改動觸發 regression、CI 立刻發現、不需要再人工 debug。

Playwright 引入的最低門檻

1# 起本地 server（任何方式）
2python3 -m http.server 8000 --directory public
3# 或 hugo server
4hugo server

Playwright MCP 提供的核心工具：

• browser_navigate(url) — 開頁
• browser_evaluate(fn) — 執行 JS 拿結果
• browser_take_screenshot() — 截圖
• browser_snapshot() — accessibility tree

寫一個 evaluate fn ≈ 30 行 JS。比反覆推理快得多。

主動切換訊號（不要等使用者打斷）

當以下任一觸發、執行者要主動提：「我推理 2 次失敗了、我們起 server、用 playwright 量 live DOM 確認假設」。不要等到第 5 次才切。

Wrong vs Right 對照

範例 1：CSS 不生效

錯：

1/* 改了 3 次 specificity、還是沒生效 */
2.target { color: red; }                    /* 失敗 */
3.parent .target { color: red; }            /* 失敗 */
4.parent .container .target { color: red; } /* 失敗 */
5.parent .container .target { color: red !important; } /* 失敗 */

對：

1.target { color: red; }

第 2 次失敗 → 切 playwright：

1async () => getComputedStyle(document.querySelector('.target')).color
2// 返回 "rgb(0, 0, 255)" — 不是我寫的紅色

1async () => {
2  const el = document.querySelector('.target');
3  return Array.from(getMatchedCSSRules?.(el) || [])
4    .map(r => r.cssText);
5}
6// 看到 vendor 的 .pagefind .target { color: blue !important } 在贏

→ 換方向：用 CSS Layers 把 vendor CSS 包進 layer、自家 unlayered 自動贏。

範例 2：Layout 在 mobile viewport 錯

錯：

反覆推理 + 在 DevTools 切 viewport 視覺確認 → 改 → 失敗 → 改 → 失敗。

對：

第 2 次推理失敗、切 playwright：

1async () => {
2  await page.setViewportSize({ width: 375, height: 667 });
3  return {
4    h1: document.querySelector('h1').getBoundingClientRect(),
5    form: document.querySelector('form').getBoundingClientRect(),
6    scope: document.querySelector('.scope').getBoundingClientRect(),
7  };
8}

量化資料 → 立刻看到「scope 的 top 比 form 的 bottom 小 12px」→ overlap → 改 form margin-bottom。

自檢清單（dogfooding）

debug 卡關時：

• 我推理失敗幾次了？≥ 2 次 → 該切換工具
• 我能說出「假設是什麼、用什麼工具能驗證」嗎？
• 切到 playwright 之前、有沒有試圖用更努力的推理多撐一次？（如果有 → 停）
• 第 2 次同個版型 bug 出現時、有沒有寫成測試固化？
• 對外回報切換工具的提案、有沒有寫得具體（要起哪個 server、量什麼）？

延伸閱讀

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

• playwright-early-in-loop — 在開發循環裡早一點用 playwright 看真實結果
• verification-method-timing — 驗證方法的選擇時機
• layout-tests-with-playwright — 用前端測試把排版問題自動化

Last Updated: 2026-04-26 Version: 0.1.0