空間 / 尺寸類指令缺少明確數值時、先列計算過程或假設、確認後再實作。 直接用估算寫死會在使用者實際看到結果時才被發現不對、引起多輪試錯。澄清的成本是「多打一句話」、收益是「一次到位」。

為什麼空間指令需要澄清

商業邏輯

「對齊」「擺在旁邊」這類描述是關係性指令 — 描述了兩個元素的相對位置，但沒給絕對數值。實作時需要把關係轉成具體數字（padding 多少、top 多少）。

執行者依憑感覺取數字 = 用自己的估算代替使用者的意圖。估算與意圖不一致時、使用者看到結果才知道、糾正成本高。

把計算過程列出來確認 = 把「估算」變成「協商」 — 使用者有機會在實作前指正。

這次任務的實際情境

觀察

第三個是少數有明確數值的情境、那次一次到位。前兩個沒給數字、靠估算、結果都要重做。

判讀

差別在「使用者有沒有給確定值」。沒給時、執行者該做的不是「自己決定」、是「把計算列出來確認」。

執行：澄清 protocol

收到空間 / 尺寸類指令時、先檢查：

例：

「padding 對齊到搜尋欄下緣 — 我會用 H1 64px + form 68px = 132px 當基準、加 8px buffer 共 140px、OK 嗎？或是你想要其他數字？」

把計算過程攤開、使用者可以指正「H1 沒這麼高、應該 70px」、避免實作後重做。

內在屬性比較：四種空間指令處理方式

優先順序：有數值用、可算就算、估算寫死最後選。

列計算的好習慣

1. 攤開假設

1計算 filter padding-top：
2  H1 height = 64px（假設、實際看 theme 渲染可能不同）
3  Form height = 68px（pagefind input 64 + border 4，鎖定 scale=1.0）
4  Gap = 20px（pagefind drawer 預設 margin-top）
5  Total = 152px

每個值來源寫清楚 — 使用者可以指出某個假設錯了。

2. 用變數表達

1padding-top: calc(var(--search-title-h) + var(--search-form-h) + var(--search-gap));

使用變數取代 magic number — 改一處全部跟著動、未來調整成本低。

3. 區分「設計值」與「量測值」

確認時把每個值的類型寫清楚、使用者知道哪些是「我可以決定」、哪些是「實作時才知道」。

設計取捨：空間/尺寸指令的處理策略

四種做法、各自機會成本不同。這個專案在缺數值時選 A（列計算過程確認）當預設、其他做法在特定情境合理。

A：列計算過程確認後實作（這個專案的預設）

• 機制：把計算過程與假設攤開、給使用者確認、再用 calc(var(...) + var(...)) 實作
• 選 A 的理由：使用者能指正特定假設（不只「對」「不對」）、實作後改 token 自動跟上
• 適合：缺數值的空間 / 尺寸指令（大多數情境）
• 代價：多一輪對話確認

B：直接照使用者給的數值寫

• 機制：使用者給「filter 寬 400px」就直接 width: 400px
• 跟 A 的取捨：B 一次到位、無需確認；前提是使用者已給確切數值
• B 比 A 好的情境：使用者明確指定數值、執行者只需照寫

C：用估算值寫、之後再調

• 機制：執行者依感覺給數字（「padding-top: 152px」）、寫了之後等使用者試
• 跟 A 的取捨：C 看似省溝通成本、實際把確認延後到實作後；C 在估算錯時要重做
• C 才合理的情境：視覺差容易調（< 5px 微差）、且確認成本比實作高（罕見）

D：不確認直接寫死

• 機制：執行者自己決定數值、不問也不告知
• 成本特別高的原因：跟使用者意圖不一致時要重做、多輪試錯
• D 是反模式：「使用者會看到的數字」屬於該確認的決定（#21 可決定 vs 該先確認）— 自決會跟意圖不一致、被退回時白做

判讀徵兆

核心原則：空間關係描述只是意圖、不是實作數字。把意圖翻譯成數字的過程要對外可見、讓使用者參與。

第三輪指令類型現有五類：空間（本卡）/ 相對位置（#17）/ 隔離（#18）/ 決定權（#21）/ 篩選（#58）。前四類缺幾何 / 邊界 / 拍板資訊、第 5 類缺操作層級資訊。

相對位置指令（「X 在 Y 旁邊」「Y 顯示在 main 左側」）是模糊的 — 同一句話可以對應多種 layout 結構。實作前用文字描述意圖中的 layout 草圖、讓使用者確認後再寫 CSS。 沒確認直接擺、實作出來常與使用者預期不同、要重做。

為什麼相對位置需要澄清

商業邏輯

「X 在 Y 旁邊」這類描述至少對應四種 layout 實作：

執行者選哪種、結果不同。憑直覺選 ≠ 使用者意圖。

這次任務的實際情境

觀察

每個指令都讓我選了使用者沒想要的實作。

判讀

問題在「相對位置」這類描述本質就是模糊的 — 沒指定座標系、沒指定相對層級、沒指定誰是 layout flow 主角。

執行前該做的：把我準備寫的 layout 用文字描述出來、讓使用者確認意圖一致。

執行：layout 草圖 protocol

收到相對位置指令時、先寫文字草圖：

1我準備這樣寫：
2  - main 維持 70ch 置中（layout flow 主角）
3  - filter 用 absolute 浮在 main 左外側、寬 400px、間距 2rem
4  - scope UI 在 main 內、緊接 search input 下方、結果上方
5  - 三者位置關係：filter 與 main 同 viewport 中段、scope 在 main 內
6
7確認對應你的意圖嗎？或是想要不同安排？

把意圖中的 layout 結構攤開 — 使用者可以指正「filter 應該在 grid 內、不是 absolute」、避免實作後重做。

內在屬性比較：四種相對位置描述

執行者該主動把對話從「純位置詞」推到「文字草圖 + 確認」 — 縮小模糊範圍。

文字草圖的好習慣

1. 描述 layout 主角

哪個元素是「決定其他元素位置的 anchor」？通常是內容主體（main、article）。其他元素相對這個主角描述。

1Layout 主角：main（70ch 置中）
2其他元素：
3  - H1：main 內、第一個元素
4  - filter：main 左外側 400px
5  - footer：main 之後

2. 描述層級關係

哪些元素在同一 layout 流、哪些是疊層？

1Layout flow 內：H1、search input、results
2疊層：
3  - filter：absolute、浮在 main 左外
4  - scope UI：absolute、浮在 search input 下方

3. 描述 viewport 行為

不同 viewport 下、layout 怎麼變？

1Desktop ≥ 1400：filter 顯示在左外、scope UI 浮在 input 下方
2Mobile < 1400：filter 移到 pagefind drawer 內、scope UI 維持原位

對使用者描述 layout 的格式

Inline ASCII 草圖

文字環境下、ASCII 比 PNG 圖更實用：

1┌────────────┬──────────────────┐
2│            │ H1 搜尋           │
3│ filter     ├──────────────────┤
4│ (sticky)   │ Search input     │
5│            ├──────────────────┤
6│            │ Scope UI         │
7│            ├──────────────────┤
8│            │ Results          │
9└────────────┴──────────────────┘

幾秒鐘畫出來、使用者一眼看出意圖、可以指正特定區域。

敘述列表

不畫圖也可以列：

1從上到下、從左到右：
2  1. 左欄：filter（400px、main 外、sticky）
3  2. 右欄：
4     a. H1 搜尋
5     b. Search input（中央欄）
6     c. Scope UI（input 下、results 上）
7     d. Results

兩種格式選一種、確認後再寫 CSS。

設計取捨：相對位置指令的處理策略

四種做法、各自機會成本不同。這個專案選 A（文字草圖確認）當預設、其他做法在特定情境合理。

A：文字 layout 草圖 + 主角/疊層說明確認（這個專案的預設）

• 機制：把意圖翻成「main 70ch 置中、filter absolute 浮在 main 左外、scope 在 main 內 absolute 浮在 input 下」這類具體描述、使用者確認
• 選 A 的理由：草圖 30 秒打完、使用者 30 秒內 yes/no、避免寫完 CSS 才被指正
• 適合：相對位置指令的多數情境
• 代價：多 30 秒對話成本

B：ASCII 圖更詳細

• 機制：用 box-drawing 字元畫實際 layout 草圖
• 跟 A 的取捨：B 視覺直觀、A 文字描述更精確；B 對複雜 layout 表達力強
• B 比 A 好的情境：layout 涉及 ≥ 4 個區塊、文字描述容易混淆

C：加層級指示（中間步驟）

• 機制：「filter 在 main 外的 sidebar」（不是「在 main 旁邊」）
• 跟 A 的取捨：C 比純位置詞具體、比草圖簡略；用於初步對話
• C 比 A 好的情境：對話初期、還沒到實作決策的階段

D：純位置詞直接實作

• 機制：照「filter 在 main 旁邊」字面意思挑一種實作
• 成本特別高的原因：同一句話對應多種 layout 結構、選錯就重做
• D 是反模式：「相對位置」永遠模糊、跳過確認等於賭 — 選錯重做的成本遠大於確認的對話成本

判讀徵兆

核心原則：相對位置描述只是意圖、不是實作藍圖。實作前先把意圖畫成 layout 草圖、確認後再開工。

第三輪指令類型現有五類：空間（#16）/ 相對位置（本卡）/ 隔離（#18）/ 決定權（#21）/ 篩選（#58）。

「隔離」「不要動 X」是描述意圖的詞、不是描述實作的詞。 實作前先確認隔離邊界是哪一種：DOM 結構、layout flow、state、framework 管轄區。每種邊界的實作策略不同、混淆會做出不符合使用者意圖的隔離。

為什麼隔離需要澄清

商業邏輯

「隔離」這個詞涵蓋多種獨立的概念：

每種需要的實作完全不同。執行者選錯邊界 = 做了不符合使用者意圖的「隔離」。

這次任務的實際情境

觀察

「不動 pagefind 行為」這句、我多次把 scope UI 注入 pagefind DOM、違反使用者的隔離意圖 — 我以為「不動」只指邏輯、實際包含 DOM 結構。

判讀

執行前該確認：「不動 / 隔離」的邊界是哪一種類型？

執行：邊界類型確認 protocol

收到隔離類指令時、列四種可能的邊界：

1你說的「不動 pagefind」涵蓋哪些？
2  □ 不改 pagefind 的搜尋邏輯（不 fork / patch source）
3  □ 不改 pagefind 渲染的 DOM 結構（不在內部 appendChild）
4  □ 不改 pagefind 的 state（checkbox 勾選等）
5  □ 完全不互動（連 CSS 都不覆寫）

使用者勾選對應項、執行者照那個邊界實作。

或更簡單的問法：「具體來說、什麼算動、什麼不算動？」

內在屬性比較：四種隔離邊界的特徵

執行前確認邊界類型 — 不確定就問。

隔離邊界的辨識技巧

1. 從「會發生什麼」反推

問使用者：「如果 X 改了、Y 應該也跟著改嗎？」

2. 從「動誰會壞」反推

問：「我能在哪個 DOM 區域加東西？」

3. 從「升級時誰要動」反推

問：「X 升級時、我們要回頭改什麼嗎？」

設計取捨：隔離指令的處理策略

四種做法、各自機會成本不同。這個專案選 A（列邊界類型確認）當預設、其他做法在特定情境合理。

A：列四種邊界類型確認（這個專案的預設）

• 機制：列出 DOM 結構 / layout flow / state / framework 管轄區四選項、使用者勾選對應項
• 選 A 的理由：明確 + 完整、使用者快速指出真正想要的隔離
• 適合：隔離意圖不明確的情境
• 代價：多一段四選項描述

B：反推法（從「會發生什麼」「動誰會壞」反推）

• 機制：問「如果 X 改了、Y 應該也跟著改嗎？」「我能在哪個區域加東西？」根據答案歸類邊界
• 跟 A 的取捨：B 對使用者比較不負擔（不需理解四種邊界術語）、A 直接呈現答案空間
• B 比 A 好的情境：使用者不熟悉 DOM / layout / framework 術語

C：依直覺選一種實作

• 機制：執行者自己解讀「隔離」、選一種實作
• 跟 A/B 的取捨：C 跳過確認、A/B 確認；C 在意圖一致時省時間、不一致時重做
• C 是反模式：「隔離」這個詞本身就太模糊、跳過確認等於賭 — 意圖不一致時重做的成本遠大於確認的對話成本

D：通用問法「具體什麼算動」

• 機制：直接問「具體來說、什麼算動、什麼不算動？」
• 跟 A 的取捨：D 比 A 更簡略、把分類負擔丟給使用者；A 直接給選項使用者只需勾選
• D 比 A 好的情境：使用者已經想得很清楚、只需要表達 — A 反而過於 structured

判讀徵兆

核心原則：隔離指令的核心是「隔離邊界類型」 — 這個答案決定實作策略。沒確認邊界就動手 = 隨機選一種隔離、可能與使用者意圖不一致。

第三輪指令類型現有五類：空間（#16）/ 相對位置（#17）/ 隔離（本卡）/ 決定權（#21）/ 篩選（#58）。

覆寫成本要在開工前報、不能默默承擔。 客製要對抗多層（UA 預設 + 跨瀏覽器 + framework specificity）時、先把「需要寫多少 / 哪幾條 / 是否有殘留風險」攤開、讓使用者用「視覺改善 vs 維護成本」的角度判斷值不值。

為什麼成本要事先告知

商業邏輯

執行者單方決定「這客製值不值得做」會出現兩種失敗：

兩種失敗都來自「成本與價值的判斷沒對齊」。把成本攤開讓使用者參與判斷、避免兩種失敗。

這次任務的實際情境

觀察

要移除 Pagefind filter 的 <details><summary> disclosure 三角圖示。

我嘗試了：

 1/* 1. UA 預設 marker（Chrome / Firefox） */
 2summary::marker { content: ""; color: transparent; font-size: 0; }
 3/* 2. UA 預設 marker（Safari / 老 Chrome） */
 4summary::-webkit-details-marker { display: none; }
 5/* 3. 改 summary display 避免 list-item 行為 */
 6summary { display: block; list-style: none; }
 7/* 4. 蓋過 pagefind 的 ::after 自訂 chevron */
 8.pagefind-ui__filter-name::after { display: none !important; }
 9/* 5. 處理 reset 邊界外的 fallback */
10/* ... */

寫完後使用者說：「如果要做到這麼大的複寫原設計、先還原回去、先不要做這個變更」。

判讀

我的失敗：開工前沒報「這個客製需要對抗 UA + 跨瀏覽器 + framework 三層、預估 5+ 條 CSS、跨瀏覽器有殘留風險」。直接做、使用者看到改動規模才退回。

正確流程應該在嘗試第 2 條 CSS 時就停下來報告：

移除 disclosure 三角需要對抗：

• UA 預設 marker（Chrome / Firefox 的 ::marker、Safari / 老 Chrome 的 ::-webkit-details-marker）
• Summary 預設 display: list-item 行為
• Pagefind 的自訂 ::after chevron

預估 4-5 條 CSS 跨 3 種瀏覽器寫法、可能有殘留風險（::marker 在某些瀏覽器版本不能用 display: none）。

視覺改善：filter 名稱旁邊少一個小三角。

值得做嗎？

讓使用者判斷再決定。

執行：覆寫成本告知 protocol

開始任何客製前、先評估這三個累積層：

任一層有「需要對抗」就把成本報出來、讓使用者參與決定。

內在屬性比較：四種覆寫深度

「成本 vs 改善價值」的對應 — 高成本只用在高價值場景。

告知時機與格式

觸發點

報告格式

1這個客製需要：
2  - 對抗 [UA / framework / 跨瀏覽器]：N 條 CSS
3  - 殘留風險：[列出可能在某些情境失效的 case]
4  - 改善價值：[視覺差異、UX 改善]
5  
6值得做嗎？或先接受原設計？

讓使用者用「成本 vs 價值」做決定。

設計取捨：客製深度告知的時機

四種做法、各自機會成本不同。這個專案選 A（開工前評估 + 第 2 條 CSS 失敗即告知）當預設、其他做法在特定情境合理。

A：開工前評估三層成本、開工後第 2 條失敗即告知（這個專案的預設）

• 機制：開工前評估 UA / framework / 渲染週期三層；開工後寫到第 2 條 CSS 還沒蓋過就停下告知
• 選 A 的理由：使用者參與「值不值」判斷、避免做到一半被退回
• 適合：所有有覆寫嫌疑的客製
• 代價：對話成本（一段成本評估 + 等決定）

B：寫到第 N 條才告知（N > 2）

• 機制：執行者自己加碼、到 4-5 條才停
• 跟 A 的取捨：B 給執行者更多嘗試空間、A 早提早決；B 在 N 增加時白費時間放大
• B 是反模式：第 2 次失敗就是 #42 2 次門檻 的訊號、繼續加碼只是放大沉沒成本

C：默默寫到底、不告知

• 機制：執行者自己承擔、不報告成本
• 成本特別高的原因：使用者看到改動規模才退回、所有時間白費
• C 才合理的情境：客製極簡（< 1 條 CSS）、確定不會對抗任何層

D：開工前直接接受原設計、不嘗試

• 機制：看到客製需求是「對抗多層」就直接拒絕、不寫
• 跟 A 的取捨：D 完全省成本、A 留空間給「值得做」的客製
• D 比 A 好的情境：使用者明確說「這是視覺微調」+ 對抗三層、且預估成本高 — 直接接受原設計

判讀徵兆

核心原則：客製成本是使用者該知道的資訊、不是執行者單方承擔。事先告知 = 共同決定 = 不會做到一半被退回。

成本告知有兩種時機 — 本卡聚焦「實作前告知工程成本」、runtime 持續顯示掃描成本見 #62 Pattern：誠實進度 UX。共同精神是「不 silent 累積負擔」。

「可決定」與「該先確認」的分界線是「使用者會看到嗎」。 純技術實作細節（用 grid 或 flex、用 ResizeObserver 或 setInterval）可以自決；但只要結果會在 UI 上出現（數字、順序、文字、配色），就要先給選項讓使用者點頭。

為什麼要分這條線

商業邏輯

執行者自決所有事 = 強迫使用者用「視覺驗收」做決定 — 看到結果才能說「這不對」、不對就要重做。

把「使用者會看到的決定」拉出來事先確認 = 在實作前讓使用者參與決策、避免實作後被退回。

但所有事都要確認 = 對話成本爆炸、使用者疲勞、效率低。

兩者的平衡點：只把使用者實際在乎的決定攤出來確認、技術細節不打擾。

這次任務的實際情境

觀察

我自決後被肯定或否定的決定：

可以看出規則：使用者會看到的視覺結果（breakpoint 對應的 viewport 行為、順序對應的閱讀體驗、預設值對應的初始視覺）都該確認；底層工具選擇（grid / flex / absolute、ResizeObserver / setInterval）可以自決。

判讀

判斷標準是「這個決定會在 UI 上產生使用者能感知的差異嗎」：

執行：自決前的兩問

每個決定執行前先問：

1. 這個決定在 UI 上會產生使用者能感知的差異嗎？
2. 是不是有多個合理選項、選不同會影響使用者體驗？

兩個都「是」 → 該確認。

兩個都「否」或只有一個「是」 → 可自決。

確認的格式：給選項而非開放問

較差的問法

「Breakpoint 應該設多少？」

開放問題、使用者要自己想出答案。

較好的問法

「Breakpoint 我預估三個選項：

• 1280px：物理上能放下、但邊緣情境可能擠壓
• 1400px：較安全、有 120px 餘裕
• 1564px：完全不溢出 body padding、最保守

我會選 1400px 作為平衡。OK 嗎？或要其他？」

給選項 + 推薦 + 開放修改空間 — 使用者可以「OK」「換 1280」「再放寬到 1600」三種回應。對話成本低。

內在屬性比較：四種決策模式

優先「自決技術細節 + 列選項確認 visible 決定」 — 對話成本低、重做風險低。

「使用者會看到嗎」的測試

當不確定某個決定該確認還是自決時、用三個測試：

1. UI 變動測試

「不同選擇會在 UI 上看到差異嗎？」

2. UX 偏好測試

「選不同會讓使用者覺得體驗不同嗎？」

3. 不可逆測試

「這個決定寫進 commit 後、之後改成本高嗎？」

三個測試任一個「是」 → 確認。

設計取捨：決定權分配的策略

四種做法、各自機會成本不同。這個專案選 A（visible 決定先確認 + 技術自決 + 給選項）當預設、其他做法在特定情境合理。

A：Visible 決定先確認、技術自決、確認時給選項（這個專案的預設）

• 機制：使用者會看到的數字 / 順序 / 文字先列選項給使用者選；純技術實作（grid / flex / observer）自決
• 選 A 的理由：對話成本低（只確認該確認的）+ 重做風險低（visible 決定使用者參與）
• 適合：所有客製情境
• 代價：執行者要主動分辨「visible vs 技術細節」、給選項時要先想出選項

B：全部自決

• 機制：執行者自己決定所有事
• 跟 A 的取捨：B 對話成本 0、A 適度；B 容易做到使用者不要的東西
• B 才合理的情境：純內部工具、執行者就是使用者；或時間極緊、優先求動

C：全部確認

• 機制：每個決定都先問
• 跟 A 的取捨：C 重做風險 0、A 適度；C 對話成本爆炸、使用者疲勞
• C 才合理的情境：完全不熟悉的領域、執行者沒有判斷能力（罕見、應透過學習脫離此狀態）

D：開放問題、不給選項

• 機制：直接問「breakpoint 應該設多少」
• 跟 A 的取捨：D 把分析負擔丟給使用者、A 執行者先做分析給選項
• D 才合理的情境：使用者已經有明確答案、只需要傳達 — 否則 A 的「給選項 + 推薦」更有效率

判讀徵兆

核心原則：能影響使用者體驗的決定屬於使用者、能影響執行者效率的決定屬於執行者。分清楚就不會把該確認的事自決、也不會把該自決的事拿去煩使用者。

第三輪指令類型現有五類：空間（#16）/ 相對位置（#17）/ 隔離（#18）/ 決定權（本卡 #21）/ 篩選（#58）。前四類缺幾何 / 邊界 / 拍板資訊、第 5 類缺操作層級資訊。

退出指令（「先還原」「先重來」「先放著」）的執行前要先確認兩件事：還原到哪個狀態、要不要先存 checkpoint。 直接刪掉當前進度、未來想比較沒得比、想恢復也找不到。

為什麼退出指令需要 protocol

商業邏輯

退出指令的字面意思是「拿掉現在做的東西」、但背後通常有更複雜的意圖：

執行者不確認意圖、直接刪 = 把使用者的選項收窄成「沒有了」。事先確認 = 為使用者保留可能性。

這次任務的實際情境

觀察

使用者說：「如果要做到這麼大的複寫原設計、我們先還原回去、先不要做這個變更」。

我立刻刪掉那段 CSS、繼續往下做其他事。沒問「還原到哪」、沒先 commit checkpoint。

判讀

後來想比較「複雜覆寫版本」與「接受原設計版本」的差異 — 沒得比。「複雜覆寫版本」已經不存在於 git 歷史。

正確流程應該是：

1. 收到「還原」指令時、先回應「我會先 commit 當前進度（即使未採用）作為 checkpoint，再還原到 X 狀態。OK 嗎？」
2. 確認後、commit 當前狀態（不 push）、commit message 標明「探索版本、未採用」
3. 還原到 X 狀態
4. 繼續做後續事

未來想比較或恢復、checkpoint 都還在。

執行：退出指令的 protocol

收到退出指令時、依序處理：

Checkpoint 的命名與 commit message

當前進度作為 checkpoint commit、message 應該包含：

1chore(explore): N+1 attempts to remove disclosure marker
2
3探索方向：用 ::-webkit-details-marker / ::marker / display: block 三層
4覆寫移除 disclosure 三角圖示。
5寫了 5 條 CSS 跨 3 種瀏覽器、覆寫成本過高。
6
7最終決定：接受原設計、不採用此方向。
8此 commit 保留探索成果、未來若評估值得做時可參考。

關鍵元素：

• chore(explore): prefix — 標明非正式採用
• 探索方向 — 說明做了什麼
• 最終決定 — 為什麼不採用
• 保留理由 — 未來何時可能重用

未來人看到這個 commit、知道「這是探索、不是當前實作」、不會誤用。

內在屬性比較：四種退出處理

優先選 checkpoint 方式 — 為未來保留比較與恢復的可能性。

退出意圖的辨識

從語氣判斷

不確定就問。「不要這樣寫」這類指令容易被理解成「全還原」、實際只是「這段重寫」。

確認意圖的問法

1你想要：
2  □ 完全還原、刪掉這次的 CSS
3  □ 還原但保留 commit checkpoint、未來可能參考
4  □ 局部修正（哪一段保留、哪一段重寫）
5
6或是其他？

設計取捨：退出指令的處理策略

四種做法、各自機會成本不同。這個專案選 A（Checkpoint + 確認還原範圍）當預設、其他做法在特定情境合理。

A：Commit checkpoint + 確認還原範圍（這個專案的預設）

• 機制：commit 當前進度（標明「探索、未採用」）+ 問「還原到哪個 commit」+ 執行還原
• 選 A 的理由：未來想比較或恢復都還在、checkpoint 成本只是多一個 commit
• 適合：探索性嘗試、未採用方案的退出
• 代價：多一個 commit 在歷史中（可後續 squash 或保留）

B：git stash 暫存

• 機制：把未 commit 的變更存到 stash、不污染 commit 歷史
• 跟 A 的取捨：B 不留 commit、A 留 commit；B 適合「短期暫停、之後恢復」、A 適合「長期探索紀錄」
• B 比 A 好的情境：暫時切到別的工作、之後一定會回來繼續

C：git reset --hard（直接丟）

• 機制：reset 到指定 commit、未 commit 的變更全失去
• 跟 A 的取捨：C 完全清乾淨、A 保留紀錄；C 在 git reflog 內短期還能恢復、但之後永久消失
• C 才合理的情境：確定不要的探索、且確認不需要未來參考

D：直接刪檔案、不留 git 紀錄

• 機制：手動刪 / 改、不 commit
• 成本特別高的原因：未來想比較或恢復都做不到、使用者選項被收窄
• D 是反模式：git 是免費的紀錄工具、不用反而是浪費 — 未來想比較或恢復都做不到、使用者選項被收窄

判讀徵兆

核心原則：退出指令的執行不該收窄使用者的未來選項。Checkpoint = 給未來保留可能性、成本只是多一個 commit。

「依 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 失敗最隱蔽）

判讀徵兆

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

本卡抽自 infra 教學模組的溝通層文章重寫。原稿用辦公大樓比喻解釋 VPC / IAM / IaC 等概念給非工程決策者，經作者 review 判定比喻程度過重、反而阻礙溝通。重寫後改為管理視角的情境遞進。限制：evidence 來自單一模組的一次重寫，跨領域（醫療→管理、法律→工程等）的適用性未驗證。

核心原則

向非本領域的專業人士解釋技術議題時，有效的做法是減少術語、讓情境從簡單到複雜遞進。堆疊比喻（「VPC 像辦公大樓」「IAM 像門禁卡」「state 像資產清冊」）看似降低門檻，但有三個結構性問題。

第一，比喻傳遞形狀但不傳遞嚴重性。「VPC 像辦公大樓的圍牆」讓人理解隔離這個概念，但不讓人理解隔離失敗時一個被入侵的服務能橫向存取所有資料庫的商業代價。決策者需要的是後者。

第二，比喻在細節處崩解。辦公大樓沒有 CIDR 地址空間、沒有 peering、沒有跨區冗餘。當討論深入到需要判斷「CIDR 該切多大」或「要不要跨帳號」時，比喻不但幫不上忙，還會成為錯誤直覺的來源 — 讀者開始用辦公大樓的邏輯推斷網路架構。

第三，過度比喻隱含「對方聽不懂」的預設。專業決策者能聽懂「環境描述檔讓系統可以在故障後重建」，不需要先繞到「就像建築藍圖」才能理解。多一層比喻是多一層認知負擔，不是少一層。

情境

infra 教材的溝通層文章原稿用延伸比喻架構整篇文章：

• VPC = 辦公大樓，有自己的地址範圍
• Subnet = 樓層分區（public = 大廳，private = 辦公區）
• Security group = 每個房間的門禁卡設定
• IAM = 員工證與權限
• IaC = 建築藍圖
• State = 資產清冊

每個比喻單獨看都成立，但串在一起時文章變成了一個辦公室管理指南，讀者要在「比喻世界」和「技術世界」之間反覆切換。決策者讀完後記住的是比喻、不是操作風險。

理想做法

用情境遞進替代比喻堆疊。每個技術概念對應到它解決的管理問題，然後從最簡單的情境開始、逐步加入複雜度：

每一行用決策者熟悉的語言：影響範圍（幾個客戶）、恢復時間（幾小時 vs 幾天）、成本（工程師時間 + 停機損失）。這些維度是決策者日常在處理的，不需要翻譯。

情境遞進的優勢是它讓對方在自己的認知框架裡接收新資訊 — 管理者懂「服務掛了要能重建」，從這個已知出發、往「怎麼確保重建結果一致」「怎麼避免測試影響正式」遞進，每一步都建立在前一步的理解上。

沒這樣做的麻煩

• 記住比喻、忘記風險：決策者開會時說「那個門禁卡的東西做了嗎」，但說不出它解決什麼問題、不做會怎樣。比喻成了一個替代理解的標籤。
• 比喻限制討論深度：當需要討論「要不要把 production 拆到獨立帳號」時，辦公大樓比喻沒有對應物。討論被迫回到技術語言，之前的比喻投資歸零。
• 溝通問題被錯誤歸因：推不動 infra 時，團隊以為是「沒解釋清楚」，於是加更多比喻。但問題其實是提案語言跟決策語言的框架不對，不是理解力不足。結果越比喻越偏離決策者的關注點。

判讀徵兆

寫跨專業溝通文件時，如果發現自己在做以下事情，代表可能掉進了比喻堆疊：

• 為每個技術概念都找一個日常比喻（「X 就像 Y」超過三個）
• 比喻之間需要互相引用才能成立（「記得剛才說的大樓嗎？這個是大樓裡的…」）
• 比喻崩解後要補救（「辦公大樓的比喻在這裡不完全適用，但大致上…」）
• 文章的主要結構是比喻而非情境（H2 標題是比喻物、不是管理問題）

替代方式：每個概念用「它解什麼管理問題 + 不做的後果量級」一句話帶入，需要深入時用情境遞進展開。

跟其他抽象層原則的關係

• → 讀者是缺經驗的專業人士、不是外行人：本卡的前提 — 跨專業溝通的對象是專業人士，比喻堆疊預設對方「聽不懂」
• → #155 用語意標題引用、不用位置編號：情境遞進跟語意引用同源 — 都是用內容本身（情境描述 / 語意標題）承載意義，不靠外部代理物（比喻 / 編號）
• → #148 跨輪 review 停止訊號：溝通層文章的 review 停止訊號之一是「比喻已經從輔助變成主體」— 這個 frame 在 Round 3 steelman 可以 catch

本卡抽自 infra 教學模組的管理層視角掃描。22 篇技術文章完成三輪審查後，掃描「管理層會問什麼」發現 10 處缺口，集中在成本量級和時程估算。限制：evidence 來自單一教學模組；成本數字（AWS 定價）有時效性，寫入教材後需要維護。

核心原則

技術教材的讀者通常需要向上彙報：為什麼要做這件事、要花多久、花多少錢、做完怎麼知道有效果。如果教材只講技術機制（怎麼寫 HCL、怎麼設 IAM），讀者學會了做法卻沒有素材向管理層說明，結果是做法正確但推不動——因為管理層沒拿到他們決策需要的資訯。

管理層需要的資訊有四類，跟技術段落的位置關係明確：

情境

infra 教學模組的 22 篇文章完成三輪寫作審查（compliance / cadence / steelman）後，從管理層視角掃描發現：

• NAT per-AZ vs 共享的段落講了可用性取捨，但沒說每個 NAT Gateway 月費約 $32——管理層看不到這筆錢的量級
• 環境拆分的 retrofit 路徑講了操作步驟，但沒給時程估算——管理層問「要多久」時工程師得另外估
• tagging 講了為什麼要標，但沒說怎麼量化進度——管理層沒有可追蹤的指標
• 跨帳號策略講了 SCP 怎麼設，但沒標記這是需要 CTO 對齊的決策——工程師可能自己決定了影響全組織的設定

這些缺口的共同模式是：技術內容本身完整，但缺少讓讀者「帶出去用」的彙報素材。

理想做法

在技術段落旁邊嵌入管理層資訊，用 1-2 句帶過量級，不獨立成段。嵌入而非集中的理由是：工程師讀到技術取捨時，同時拿到彙報素材，不需要翻到另一篇文章去找對應的商業論證。

成本用量級而非精確數字。「每個 NAT Gateway 月費約 $32」比「$31.54/月」有用——量級讓管理層判斷這是百元級、千元級還是萬元級的決策，精確數字會隨定價調整而過時。

時程用範圍而非單點。「1-2 週」比「10 天」誠實——infra 工作的時程變數主要來自 stateful 資源的數量和 drift 的嚴重度，這些在動工前無法精確預估。

進度用可查詢的指標。「缺 tag 資源數 / 總資源數」比「我們在做 tagging」可追蹤——管理層需要的是趨勢線，不是狀態報告。

沒這樣做的麻煩

• 推動卡在溝通：工程師學會了怎麼做 IaC，但在預算會議上說不出「導入要 2-3 天、第一個里程碑是一條指令重建環境」，管理層聽到的是一個沒有時間框架的技術提案
• 成本決策沒有量級感：multi-AZ RDS 費用翻倍、NAT per-AZ 三倍固定費——這些取捨在技術上有道理，但管理層需要知道「翻倍是從 $50 到 $100 還是從 $5000 到 $10000」才能判斷值不值得
• 進度不可見：infra 工作的中間產出（state 設好了、第一批資源 import 了）對管理層不可見，看起來像「花了兩週什麼都沒產出」。有量化指標（覆蓋率從 40% 到 70%）才能讓進度可追蹤

判讀徵兆

寫技術教材時，對每個取捨段落問兩個問題：

• 「讀者的老闆會問什麼？」——如果答案是「多少錢」或「多久」而段落裡沒有，就是缺口
• 「這個決定影響範圍多大？」——如果影響跨團隊或跨帳號，標記為需簽核的決策點

成本數字寫入教材後要標明是量級參考而非精確報價，避免讀者直接拿去做預算。雲端定價會變，量級通常穩定——$30/月級的服務不太會跳到 $300/月。

跟其他抽象層原則的關係

• → 讀者是缺經驗的專業人士、不是外行人：本卡是該原則的延伸——讀者是專業人士，他們的工作流程包含向上彙報，教材應該支援這個流程
• → 跨專業溝通用情境遞進、不用比喻堆疊：管理層資訊用量級和範圍表達，不用比喻——「月費約 $32」比「大約一頓飯的錢」精確且專業
• → infra 投資的商業論證：該文集中處理商業論證，本卡講的是把商業素材分散嵌入技術段落，兩者互補