自包含聲明：本文件不依賴其他 reference。讀完本文件即可獨立執行外部分析材料到教學文章的轉換。

何時參閱本文件

不適用：純翻譯逐句校稿、學術論文正式摘要、內部 analyst-to-analyst 報告。這些產物可以保留原文的 reader contract 或 process metadata。

為什麼外部分析改寫需要獨立指引

外部分析文章同時帶有三種東西：事實材料、原作者 frame、原作者 reader contract。AI 或人類若只做風格轉換，會把三者一起搬進新文章。結果是文字符合目標風格，但結論仍沿用原作者視角，讀者仍需要原領域背景，文章也缺少可遷移的教學框架。

教學型分析文章要做的是「source transformation」：保留可驗證事實，辨識原作者判讀，重建適合目標讀者的推導，最後交付可重用的判斷問題與預警訊號。

五個 Pass

Pass 1：Source Layering

Source layering 是把材料拆成事實、原作者判讀、本文推導。每句材料進正文前先問：

寫法規則：

• 事實放在背景或事件段。
• 原作者判讀只當 hypothesis prior，不直接當本文結論。
• 本文推導要明確標成本文整理出的框架或判斷問題。

反例：

1這代表基礎設施廠商正在垂直整合 data pipeline。

問題：若「垂直整合」是本文推導，這句把推導寫成事實。

正例：

1本文把這個收購視為「基礎設施廠商往 data pipeline 延伸」的訊號。這是本文判讀，不是事件本身。

Pass 2：Reader Level

Reader-level pass 是把原文 reader contract 改成目標讀者 contract。先辨識原文寫給誰，再決定是否降一級。

檢查法：

• 三句內連續三個以上跨領域術語，拆段或補卡。
• 一句話跨三個以上因果步，拆成多段。
• 讀者能背結論但說不出推導，補機制、公式、數字或例子。

Pass 3：Internal Analysis

Internal analysis 是作者背後的 hypothesis 探索，不等於文章章節。可以用 WRAP 或其他決策框架做內部檢查：

• 要回答什麼問題？
• 手上 evidence 夠不夠？
• 有哪些本質不同的合理解釋？
• 每個解釋的 evidence weight 是什麼？
• 哪些觀察會推翻本文判讀？

這些問題要做完，但不直接當正文標題。正文標題描述讀者會學到什麼，不描述作者正在執行哪個分析步驟。

Pass 4：Title Promise

Title promise 是標題對讀者做的合約。跑完內部分析後，列出文章每段是否服務標題承諾。

Title promise pass 保護讀者不被作者的分析過程帶離主題。

Pass 5：Deliverable

Deliverable pass 確認文章交付的是可遷移框架，而不是原文摘要。結尾至少回答：

• 下次遇到同類事件要看哪些訊號？
• 哪些機制若成立，本文判讀才成立？
• 哪些觀察會削弱或推翻本文判讀？
• 讀者下一步該看哪個概念、卡片或案例？

常見責任順序：

1事件本身 → 結構性機制 → 長期影響 → 預警訊號 → 可遷移框架

這是責任清單，各文章可以調整順序。不同文章可以調整順序，但不能缺少可遷移框架與失效條件。

自檢清單

• 每個來源句子都能標成事實、原作者判讀、本文推導之一。
• 原作者 frame 沒有被寫成事件事實。
• 目標讀者不需要原文 reader contract 也能理解主體推導。
• 三句內沒有未解釋的連續跨領域術語。
• 內部分析框架沒有外露成正文標題。
• 正文段落都服務 title promise。
• 結尾提供可遷移框架、預警訊號與下一步路由。

反模式速查

核心原則：外部分析文章改寫的核心是 source transformation。保留事實、分離原作者判讀、重建目標讀者可理解的推導，最後交付可遷移框架。

三層機制

Step 0 變數選取

Step 0 變數選取重視決策影響力。好的 Step 0 只問「答案會根本改變建議」的關鍵條件。

回答格式

1目前我可以先給通用判讀；若要給個人化建議，需要先確認：
21. ...
32. ...
43. ...
5
6在以下假設成立時，我會傾向 ...；如果假設不同，建議會改成 ...。

反模式

Last Updated: 2026-04-30 Version: 2.0.0 — 可攜個人化建議整合模板。

分工

建議索引欄位

維護原則

1. WRAP skill 不引用專案規則庫。
2. 專案規則庫可以引用 WRAP skill 與 integration patterns。
3. 同一條規則只保留一個權威來源。
4. 自動化工具讀權威來源，不複製清單。
5. 規則變更時，同步更新範例與反模式。

反模式

Last Updated: 2026-04-30 Version: 2.0.0 — 可攜規則庫映射模板。

三問

填答格式

 1W：
 2- 首選路徑：
 3- 替代路徑 A：
 4- 替代路徑 B：
 5- 選擇理由：
 6
 7A：
 8- 預估投入：
 9- 被擠壓目標：
10- 現在做的理由：
11
12P：
13- 失敗原因 1 / 防護：
14- 失敗原因 2 / 防護：
15- 失敗原因 3 / 防護：

適用範圍

升級條件

Last Updated: 2026-04-30 Version: 2.0.0 — 可攜三問模板。

適用情境

核對流程

1. 找到權威來源：官方文件、本機 schema、原始設定、標準文件或實際程式碼。
2. 拆成逐項清單：每個欄位、能力、規則或聲明各自核對。
3. 標記來源狀態：confirmed、inferred、missing、conflict。
4. 對 missing 與 conflict 項目重新查證或移除。
5. 在輸出中標示哪些是來源事實，哪些是分析推論。

來源狀態表

反模式

Last Updated: 2026-04-30 Version: 2.0.0 — 可攜來源核對模板。

本檔位置：compositional-writing 的文章轉譯 / 翻譯 / 術語改寫 reference。

何時讀：把英文材料轉成中文、把既有文章改寫成另一種語言、整理 AI / 工程 / 方法論術語，或 reviewer 指出「這個翻譯放在句子裡怪怪的」時。

核心命題

翻譯 review 的核心是句內邏輯對位，不是詞典對位。翻譯完成後要把譯名放回原句，檢查它跟主詞、動詞、修飾語、因果關係是否仍然成立；如果譯名讓句子多出原文沒有的前提，或讓讀者追問方向改變，這個翻譯就有問題。

翻譯錯誤常在中文很順時被放過。順口只代表中文語感成立，不代表原文概念、句內角色、後續推論成立。多輪檢查時要把「順不順」跟「邏輯是否對位」分開看。

為什麼文章轉譯容易誤譯

文章轉譯容易誤譯，是因為譯者會同時壓縮三件事：讀懂原文、找中文詞、讓句子順。這三件事會互相干擾，尤其在 AI / 工程 / 方法論文章中，原文詞常同時有字根、日常語意、術語語意。

翻譯 review 的任務是把這些便利訊號重新拆開。先問原文概念在句子中承擔什麼責任，再決定中文詞是否能承擔同一個責任。

句內邏輯檢查

句內邏輯檢查要求把翻譯後的中文詞放回原句，逐項檢查語法角色與論證角色。這一步比查字典更早，因為很多錯譯不是「查不到正確譯名」，而是譯名放進句子後改變了原句的邏輯。

檢查時可以把原句拆成一句話：「因為 X，所以 Y」。若中文譯名把 X 換成 X’，後面 Y 還能成立嗎？不能成立就要重譯。

Case：paternalism 不是父權式保護

paternalism 被翻成「父權式保護」的問題是句內邏輯錯位。這個譯名同時抓到 paternal 的父系字根與「保護他人」的語境，所以中文看似能讀；但放回句子後，它讓句子多出原文沒有的前提：這裡似乎涉及父權或性別權力結構。

修法的重點是補定義句讓邏輯回到原文責任：

1家長主義（paternalism）在本文指「以對方利益之名限制對方自主」。
2常見譯名也包含「家長作風」；本文統一用「家長主義」。

Case：Steelman 不是最強版本測試

Steelman 被翻成「最強版本測試」的問題是概念角色被換掉。這個譯名在 checklist 語境裡看似自然，因為 reviewer 確實會問「有沒有通過」；但 Steelman 的核心責任是把被放棄選項或反方立場重建成最有力版本。

修法的重點是保留概念角色：

1最強版本論證（Steelman）在本文指：
2先把被放棄選項或反方立場重建成最有力版本，再檢查自己的選擇是否仍站得住腳。

多輪檢查流程

翻譯 review 要獨立成一輪，放在一般命名 / grep-ability 檢查附近。它不取代文章的意圖檢查、語氣檢查或邊界檢查，而是補上「語言轉換後邏輯是否仍成立」這個角度。

這輪可以很短，但不能省。文章轉譯時，最容易被放過的錯誤就是「中文通順、邏輯錯位」。

原文錨點與完整名詞頭

原文錨點負責保留概念邊界，完整名詞頭負責讓中文術語離開原句仍能獨立成立。兩者是翻譯 review 的輔助工具，不是最終目的；最終目的仍是句內邏輯對位。

反模式

最小檢查表

• 所有翻譯 / 轉譯來的術語第一次出現都有原文錨點
• 每個譯名放回原句後，主詞、動詞、受詞、修飾語都成立
• 中文修飾語沒有引入原文沒有的前提
• 段落因果可寫成「因為 X，所以 Y」，且 X 沒被譯名換掉
• reader 看到中文詞會追問原文核心問題
• title、heading、description、link label 沒有殘留舊譯名

核心：翻譯 review 的核心是確認語言轉換後，句子仍在說同一件事。

三層分工

對齊規則

1. 文字規則定義語意，不重複機器清單。
2. 機器設定保存關鍵字與閾值，作為自動化來源。
3. 自動提醒只讀設定，不硬編碼第二份清單。
4. 每次新增觸發類型，都同步更新 human rule 與 machine config 的映射說明。

建議欄位

反模式

Last Updated: 2026-04-30 Version: 2.0.0 — 可攜觸發條件對齊模板。

收錄欄位

抽象化規則

1. 移除專案私有路徑、內部編號與人名。
2. 保留決策結構：目標、選項、證據、成本、回退。
3. 把工具名稱改成中性角色，例如 task runner、rule store、automation hook。
4. 若案例依賴特定工具，改寫成「某 CLI」「某任務系統」「某文件產生流程」。
5. 每個案例最後要有可 grep 的 reuse signal。

案例模板

1## {case-title}
2
3**Situation**：...
4**Trigger**：...
5**錯誤路徑（Faulty path）**：...
6**WRAP observation**：...
7**改善路徑（Better path）**：...
8**防護欄（Guardrail）**：...
9**重用訊號（Reuse signal）**：...

常見案例類型

Last Updated: 2026-04-30 Version: 2.0.0 — 可攜案例庫模板。

依賴方向

1WRAP core skill  ->  integration patterns  ->  project-specific implementation
2通用原理             可攜模板                  各專案自行落地

整合層可以引用 WRAP core skill，專案實作可以引用整合層。WRAP core skill 保持獨立，避免反向依賴任何專案實作。

檔案清單

使用方式

1. 先讀 skill，確認是否觸發 WRAP。
2. 需要把 WRAP 接到工具或流程時，讀本目錄的對應模板。
3. 在專案內建立自己的實作文件，填入實際路徑、指令、狀態欄位與 owner。
4. 保持核心 skill 與專案實作分離。

可攜限制

本目錄保留為可攜模板，因此遵守以下限制：

• 只使用 skill 內部相對連結與中性範例。
• 只使用通用任務名稱，避免專案內部任務編號、批次代號、錯誤代碼或歷史編號。
• 保持 CLI、掛鉤框架（Hook framework）與任務管理工具的供應商中立。
• 範例使用中性名稱，例如 task、rule store、automation hook、case library。

Last Updated: 2026-04-30 Version: 2.0.0 — 改為 portable integration patterns。

核心理念：提醒決策者「你是有選擇的」，不替決策者做選擇。

本 SKILL 為通用 WRAP 規則，獨立於任何專案框架。專案若需要掛鉤（Hook）、CLI 或任務系統整合，請在該專案內另建落地層文件。

觸發條件

上述 4 項決策路徑層因子可由各專案映射到自己的掛鉤（Hook）、CLI 或任務系統；本 skill 只保留通用判斷語意。

快速模式（5 分鐘）：錨點 + Step 0 + W + 基本率（R 核心）+ 機會成本（A 核心）+ 決定 快速+模式：快速模式 + 強制 R 的基本率 / 反向驗證兩階段反思（分析任務最容易跳過事證直接下結論，故在快速基礎上補回 R 核心 + 一輪反向驗證） 完整模式（15-30 分鐘）：全階段 Step 0 強制：個人化建議場景，不論採用哪個模式，Step 0 為必經閘門

各專案可依自身工作流建立機器可讀觸發條件、自動觸發機制、關鍵字清單對應，以及任務啟動階段的簡化三問（W/A/P 1-2 分鐘版）。

錨點確認（Anchor Check）

進入分析前先確立錨點。

第一錨點 — 產品決策：

第二錨點 — 流程決策：

閘門判斷：

1這個問題影響核心客戶 / 核心目標嗎？
2    ├─ 是 → 進入 Step 0
3    ├─ 否 → 這個流程改善影響決策品質或開發效率嗎？
4    │        ├─ 是且持續回報 > 一次性投入 → 進入 Step 0
5    │        ├─ 是但低回報 → 建提案（提案暫存區） → 回到核心任務
6    │        └─ 否 → 記錄待辦 → 回到核心任務
7    └─ 純粹救火 → 建任務單位 + 低優先級 → 回到核心任務

引用：英特普拉思特「病人才是我們的客戶」— 確立後，所有困難的決定都有了錨點。

Step 0. 資料充足度閘門（Data Sufficiency Gate）

核心問句：「我手上的資訊夠做這個決策嗎？還是我正在用假設替代資料？」

模式辨識

使用者說「我是 X」、「推薦給我」、「我該買哪個」 → 決策諮詢。決策諮詢以個案資料為基準，群體平均值只作為背景參考。

判定流程

 1Step 0：資料充足度檢查
 2    │
 3    ├─ 檢查 1：我知道當事人是誰嗎？（年齡/性別/身體/財務條件）
 4    ├─ 檢查 2：我知道當事人的目標嗎？
 5    ├─ 檢查 3：我知道當事人的限制嗎？（預算/時間/禁忌）
 6    ├─ 檢查 4：我知道當事人的環境嗎？（地區/可用資源）
 7    ├─ 檢查 5：我在用「平均值假設」替代「個人資料」嗎？
 8    └─ 檢查 6：如果假設錯誤，後果會嚴重嗎？
 9        │
10        ▼
11判定結果
12    ├─ 資料充足 → 進入 W 階段
13    ├─ 資料不足 + 低風險 → 進入 W，但標記假設
14    ├─ 資料不足 + 中風險 → 暫停，漸進式問 2-3 個關鍵變數
15    └─ 資料不足 + 高風險 → 強制完整問卷 + 建議諮詢專業人士

為什麼 Step 0 必須在 W 之前

W 階段「擴增選項（Widen Options）」是「擴增選項空間」，但選項的意義取決於當事人條件。如果不先確認資料充足度：

結論：Step 0 缺失會讓整個 WRAP 流程變成「精美的錯誤分析」。

反模式偵測

失敗模式：Step 0 最容易被跳過是因為反問當事人打斷對話流暢度。流暢度與準確度的取捨應交由當事人決定。

各專案可建立個人化建議的三層機制（識別 / 分級 / 誠實）。

W — 擴增選項（Widen Your Options）

核心問句：「還有什麼其他方式可以達成目標？」

爬梯子法（由近到遠）

每層找到可行方案就停止，找不到才往上爬。

品質檢查

反向思考（Consider the Opposite）是最容易被跳過但最重要的檢查 — 也是防止「在錯誤問題框架下擴增選項」的最後防線。詳細操作與範例見 detailed-techniques。

方案性質三類涵蓋與方案關聯性檢查用來抵抗 LLM 的工具化偏誤（toolification bias）：LLM 在不少情境傾向把「新增工具」當答案，較少提「改造既有機制」與「零工具」選項。即使補上多個方案，若方案間強關聯也可能退化為 1 個實質選項。

假設層級多元性（真正的擴增選項，Widen）

選項必須在「假設根因」層級多元，而不只是「實作手段」層級多元

擴增選項（Widen）列出多個方案 ≠ 真正擴增了選項空間。若所有方案都接受同一個未驗證的根因假設，仍是偽擴增選項（pseudo-Widen） — 方案脫靶率會集中分佈（要嘛全中、要嘛全脫）。

最低操作：列方案前先寫出「我假設問題是 X 造成的」，再質疑 X 是否為真根因。

分析類任務（根因調查、設計決策）建議完整執行三層質疑、現實檢驗（Reality Test）閘門與警告信號檢查。

多輪迭代查詢（深度議題建議）

對複雜議題（如規則設計、提案評估），W 階段不應一次性完成擴增，採四輪迭代結構：

進入下一輪訊號（至少 3 條）、邊界條件、實證統計詳見 iterative-research。

R — 現實檢驗（Reality-Test Your Assumptions）

核心問句：「需要什麼事證才能證明這個方法可行？」

基本率 > 預測

大範圍觀照（Zoom Out）+ 近距離檢視（Zoom In）

兩者缺一不可：基本率建立基準，近距離檢視觸動直覺。

大範圍觀照（Zoom Out）前置確認（搜尋範圍校準）：

搜尋前問自己：「我搜尋的是問題本身的基本率，還是我預設解法的基本率？」

• 搜尋「tool call 閾值校準」→ 預設解法的基本率（狹窄）
• 搜尋「為什麼要拆分任務」→ 問題本身的基本率（廣闊）

清單類答案的來源核對

LLM 列清單時最容易產生幻覺（會「補齊」看起來合理的項目）。現實檢驗（Reality Test）對清單類答案必須執行逐項對 source 核對，禁止整批信任。

最低規則：

• 找到該領域的權威 source（官方 docs、本機 spec、Context7）
• 清單每一項對照 source；找不到 → 標記為候選幻覺
• 單項細節（schema、欄位語意）比整體清單可信

完整防護重點是幻覺模式分類、逐項核對流程與反模式識別；各專案可另建來源清單與核對模板。

試水溫（Ooch）

對每個選項問：「能否用最小成本驗證？5 分鐘內能得到初步答案嗎？」

• 能 → 先試水溫再決策
• 驗證成本高 → 進入完整分析

最強版本論證（Steelman）

選定方案後、執行前：

1. 「用最有力的方式陳述被放棄選項的優點」
2. 「列出選定方案的三個缺點」

做得到 → 決策品質足夠；做不到 → 回到 R 階段補充。

反向驗證範本（深度議題建議）

對結論做反向搜尋避免確認偏誤。標準格式：

1| 我們的結論 | 反向搜尋目標 |
2|----------|-----------|
3| [結論] | [批評 / 反例 / 反駁 / 限制] |

至少涵蓋 4-8 種反向方向類型（學術批評 / 反方論點 / 失效情境 / 統計限制 / 文化限制 / 家長主義（paternalism）警示 / 取捨揭露（trade-off） / 自我參照悖論）。

詳見 iterative-research 「反向驗證實踐範本」章節。

A — 拉開距離（Attain Distance）

核心問句：「投入這個問題的時間，會擠壓哪個更重要的目標？」

前置強制檢查

進入 A 前必完成以下 4 項檢查，任一觸發即回 W 階段重擴增。

工具選擇檢查（Tool selection check）觸發條件：選工具（tool）前 + 預估步驟數 > 2 + 涉及 Write/Bash 組合（例如 Write 暫存檔再 Read 再 Bash 寫入）。

Tool selection 4 問：

違反防護的代價：A 階段方案比較表面周詳，實際全指向同類型解法；或單步最優化但總步驟盲，把多步繞路誤判為簡單方案。

完整 4 問操作細節見 detailed-techniques 「工具選擇檢查（Tool selection check）詳細技巧」章節。

機會成本顯性化

每個選項強制列出：

1選項 A：[做法]
2  機會成本：花 X 時間，這段時間可以 [替代用途]
3  風險：[可能失敗的條件]
4  不選其他的代價：[放棄什麼]

引用：DVD 實驗 — 只加上「不買，留下 14.99 美元買別的」，不買率從 25% 升到 45%。顯性化機會成本能改變決策。

10/10/10 規則

核心優先事項對齊

排序確定後，低優先事項的決策自動有答案 — 記錄延後，不投入時間。

提案系統對接

使用「安全停放區」承接暫緩想法：想法被記錄，並明確標示目前聚焦的工作。

悖論識別檢查清單（規則 / Skill / 掛鉤（Hook）設計時必檢）

設計規則 / 流程 / 系統時，必對 5 條檢查清單逐項自檢：

• 此規則是否本身違反它要保護的價值？
• 此規則是否通過善意家長主義（benevolent paternalism）4 條件測試？（實質傷害 / 介入有效 / 利益大於風險 / 最小限制）
• 此規則的「正確示範」是否本身違反它要禁止的模式？
• 此規則的設計者立場是否被透明化？
• 此規則是否預留「用戶可覆蓋」機制？

詳見 anti-paternalism（含規則設計中的家長主義（paternalism）悖論案例）。

P — 準備好犯錯（Prepare to Be Wrong）

核心問句：「假設這個方案失敗了，最可能的原因是什麼？」

決策確定後、執行前，完成四項檢查：

Gary Klein 方法：先假設計畫失敗了，然後問「是什麼殺了它？」比問「可能會失敗嗎？」多產出 25% 的洞察（且更具體）。

自我暴露偏好實踐（提供建議時必行）

提供建議時必暴露偏好、推理鏈、盲點，不偽裝中立：

Voss 自陳：「one person’s influence is another person’s manipulation」——影響力的本質取決於是否被透明化。推薦標記（Recommended）已被學術界（DarkBench）列為 LLM 暗黑模式（dark pattern）。

詳見 anti-paternalism 「自我暴露偏好實踐」章節。

絆腳索（Tripwire）

核心理念：絆腳索不保證做出正確決定，但讓你意識到「是該做決定的時候了」。

絆腳索類型

完整類型（含正面絆腳索 — 捕捉意外成功）、命名效應、切割機制見 tripwire-catalog。

階段間切割點

WRAP 每階段之間是切割點 — 強迫問「是否繼續」：

• Step 0 完成 → 「資料夠了嗎？還是需要先問？」
• W 完成 → 「選項品質夠嗎？」
• R 完成 → 「證據支持哪個選項？」
• A 完成 → 「這符合核心優先事項嗎？」
• P 完成 → 「行前預想的風險可接受嗎？」

與其他決策類 Skill 的關係

參考文件

通用（可跨專案複用）

專案整合（落地層）

需要把 WRAP 接到具體掛鉤（Hook）/ CLI / 任務系統時讀。各檔為「通用語意 → 專案實作」的對應範本，複用到新專案時各自改寫。

Last Updated: 2026-04-28 Version: 2.4.0 — 多輪 review 修正：參考文件表補 integration-patterns 路由 + claim-quick-wrap（原 orphan）；觸發條件補「不可逆 / 時間壓力」「利害關係人衝突」+ 定義「快速+」模式；階段標題去除錯亂編號（0. / 5.）；LLM 工具化偏誤改條件式語氣；安全係數標經驗值。 Version: 2.3.0 — 觸發條件新增 4 項決策路徑層干擾（CLI 自動駕駛（autopilot） / 既有結論錨定（Anchor） / 草率改規則 / 多步驟成功率盲點）；既有觸發條件不變動（向後相容）。 Version: 2.2.0 — 觸發條件新增反思深度質疑（reflection_depth_challenge）說明，含與被困住語意的差異。 Version: 2.1.0 — 新增多輪迭代查詢方法論（W）+ 反向驗證範本（R）+ 悖論識別檢查清單（A）+ 自我暴露偏好實踐（P）+ 2 個新 references（iterative-research / anti-paternalism）。 Source: 《零偏見決斷法》(Decisive) — Chip Heath & Dan Heath

wrap-decision 是一套 WRAP 決策框架 skill，原生位置在 .claude/skills/wrap-decision/ 供 Claude runtime 呼叫；這份是同內容的文章版本，讓人類讀者也能直接在 blog 閱讀。

核心是提醒決策者「你是有選擇的」。它把決策拆成錨點確認、Step 0 資料充足度閘門、W 擴增選項、R 現實檢驗、A 拉開距離、P 準備好犯錯，以及絆腳索（Tripwire）監控。

閱讀順序

場景 1：第一次接觸

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

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

與 blog 專案其他資料的關係

Last Updated

2026-05-04 — 同步到 .claude/skills/wrap-decision/ @ v2.3.0：

• v2.1.0 — 新增多輪迭代查詢方法論、反向驗證範本、悖論識別檢查清單與自我暴露偏好實踐。
• v2.2.0 — 新增反思深度質疑觸發條件。
• v2.3.0 — 新增 CLI 自動駕駛（autopilot）、既有結論錨定（Anchor）、草率改規則與多步驟成功率盲點等決策路徑層干擾。

0. 錨點確認 — 詳細操作

任務認領時的錨點確認

每個任務認領後、分析/派發前，確認核心目的：

這是權重排序問題：在這個任務的脈絡下，哪個權重更高？

開發途中的重新確認

觸發重新確認的時機：

• 資源耗盡時 → 「簡化 scope 快速交付，還是維持完整度？」
• 發現額外問題時 → 「一起處理還是建任務延後？」
• 方案需大幅修改時 → 「核心目的有沒有改變？」

W — 擴增選項詳細技巧

爬梯子法範例

以「掛鉤（Hook）錯誤處理」類的除錯場景為例：

教訓：在「身邊」層打轉多輪，不如首輪就爬到「同領域」層 — 往往 10 分鐘解決。

向外求解（Find Someone Who’s Solved Your Problem）

核心問句：「還有誰跟我一樣在為這個問題傷腦筋？我可以從他們那裡學到什麼？」

做法：

1. GitHub Issues 搜尋：{工具名} {症狀關鍵字}
2. Stack Overflow / 官方文件搜尋
3. 如果找到 → 可能根本不需要自己實作

AI 內建知識調用

AI 擁有兩種「爬梯子」工具：

擴增選項三步走：

1. 自問內建知識 → 產出 3-5 個已知方案
2. 網路搜尋（WebSearch）驗證 → 確認是否過時、發現新解法
3. 當前專案適配 → 選擇適合當前架構的方案

假選項偵測規則（季辛吉陷阱）

季辛吉回憶錄：國務院給尼克森三選項（核戰/現狀/投降），實際只有「現狀」可選。

範例案例：改 exit code / 改 stderr / 改 stdout → 本質都是「修改掛鉤（Hook）」→ 假選項。

R — 現實檢驗詳細技巧

問對問題：基本率問法

向 AI 問基本率（過去和現在），不問預測（未來）：

• 「類似案子的重要變數是什麼？」
• 「多少比率在 X 階段就解決？」
• 「成功的案例有什麼共同特徵？」

AI 本質上是基本率的巨大資料庫 — 擅長回答「通常怎麼解決」而非「這次會不會成功」。

大範圍觀照（Zoom Out）+ 近距離檢視（Zoom In）操作

大範圍觀照（Zoom Out）：

• 搜尋社群基本率：「多少人遇到同樣問題？」
• AI 內建知識：「這類問題通常怎麼解決？」
• 統計性判斷：「做了這決定，合理預期會發生什麼？」

近距離檢視（Zoom In）：

• 讀具體案例內文（不只 Issue 標題）
• 讀 source code（不只代理人報告，實際 git diff）
• 小規模實驗驗證假設

如同羅斯福的訊息策略：不完全依賴單一來源，多源交叉驗證。

試水溫操作範例

試水溫成本：5 分鐘。全力投入失敗成本：2 次修改 + 1 次回退 + 問題惡化。

最強版本論證流程

來源：努金調解索尼 vs 蘋果 — 「我會陳述對方的立場，且優於其自我陳述。」

操作步驟：

1. 列出被放棄選項的優點（比其支持者說的更完整）
2. 列出選定方案的缺點（至少 3 個）
3. 自問：「我能否闡明反對意見，且優於反對者自己的陳述？」
   • 能 → 真的理解了取捨（trade-off）
   • 說明不足 → 可能還在確認偏誤中 → 回到 R 階段

A — 拉開距離詳細技巧

機會成本顯性化範例

除錯情境範例：

1選項 A：修改核心錯誤處理函式
2  機會成本：花 2 小時可能白做，這段時間可以推進其他任務
3  風險：根因判斷錯誤 → 改壞更多元件
4  不選其他的代價：沒有搜尋社群，可能 10 分鐘就有答案
5
6選項 B：搜尋 GitHub Issues
7  機會成本：10 分鐘
8  風險：找不到相關 Issue
9  不選其他的代價：如果是自己的 bug 就需要回來修

工具選擇檢查（Tool selection check）詳細技巧

問題背景：LLM 在選工具（tool）時常見一種傾向：單步決策敏感、總步驟數盲點。容易把「3 步繞路」誤估為「1 步直達」，因為每個單步看起來都合理。物化工具（tool）名稱（「用 Write」）會進一步窄化思考框架。

觸發條件：

• 選工具（tool）前（選擇具體工具呼叫的那個瞬間）
• 預估步驟數 > 2（有 2 個以上 tool call 才完成目的）
• 涉及 Write/Bash 組合（尤其 Write 到中介檔再讀回再寫入的模式）

4 問操作流程：

「低摩擦首選」白名單（長文寫入類）：

情境反向驗證

原場景（繞路）：決策者要把 1.5KB context 寫入任務紀錄的 Solution 欄位，選擇：

1. Write /tmp/ctx.md 建暫存檔
2. Read /tmp/ctx.md 讀回
3. Bash: task append --file /tmp/ctx.md

4 問驗證：

正確路徑（1 步直達）：

1task append TASK-ID --section "Solution" "$(cat <<'EOF'
2（content here）
3EOF
4)"

或更直接：Edit 工具打開任務紀錄編輯 Solution 欄位（0 步 tool call，整合在 Edit 單次呼叫內）。

教訓：4 問任一觸發，都是「繞路訊號」——單步都合理不代表總路徑短。

核心優先事項排序

典型軟體專案的優先事項（由高到低）僅供參考，各專案應建立自己的排序：

1. 產品功能開發
2. 程式碼品質
3. 開發流程改善
4. 工具維護

衝突時用排序終結爭論：第 4 項 vs 第 1 項 → 第 1 項勝 → 工具維護建任務延後。

P — 準備好犯錯詳細技巧

行前預想操作

Gary Klein 方法：先假設計畫失敗了，然後問「是什麼殺了它？」

• 比問「可能會失敗嗎？」多產出 25% 的洞察（且更具體）

除錯情境的行前預想範例（如果當時做了）：

• 失敗原因 1：根因判斷錯誤（可能性 > 50%）→ 已超過閾值，不應執行
• 失敗原因 2：影響範圍不清（可能性 40%）
• 失敗原因 3：實際執行環境行為不如預期（可能性 60%）

安全係數參考

展現謙卑：我們容易過度自信，所以預留緩衝。前三列為外部來源，最後一列是本框架的經驗起點、與 SKILL.md P 階段一致。

Last Updated: 2026-04-18 Version: 1.2.0 — A 階段新增工具選擇檢查（Tool selection check）4 問 + 情境反向驗證

使用時機

三問模板

W：還有什麼路徑

問題：除了我第一個想到的做法，還有哪兩個可行路徑？

最低回答格式：

1- 首選路徑：...
2- 替代路徑 A：...
3- 替代路徑 B：...
4- 放棄理由：...

通過標準：至少有兩個替代路徑，且差異落在假設或交付方式上，避免只做同一路徑的參數微調。

A：會擠壓什麼

問題：執行這個任務會擠壓哪個更重要的目標或工作？

最低回答格式：

1- 預估投入：...
2- 擠壓目標：...
3- 延後代價：...
4- 現在做的理由：...

通過標準：回答要指向具體目標、里程碑或使用者價值，避免只寫「影響進度」。

P：最可能怎麼失敗

問題：如果這個任務完成後仍然失敗，最可能的三個原因是什麼？

最低回答格式：

1- 失敗原因 1：...；防護：...
2- 失敗原因 2：...；防護：...
3- 失敗原因 3：...；防護：...

通過標準：每個失敗原因都有對應防護；任一原因機率高於 50% 時，先調整方案再開始。

任務類型差異

升級完整 WRAP 的訊號

常見反模式

可複製提示

1開始前先跑快速 WRAP（Quick WRAP）：
2
3W：除了第一個方案，還有哪兩條可行路徑？為什麼選現在這條？
4A：這會擠壓哪個更重要的目標？現在做的理由是什麼？
5P：如果完成後仍失敗，最可能的三個原因是什麼？各自的防護是什麼？

Last Updated: 2026-04-30 Version: 2.0.0 — 泛化為 portable 任務啟動檢查，移除特定任務系統、CLI 類別與內部編號依賴。

本檔位置：W 階段 + R 階段擴充。WRAP 既有的「擴增選項」與「現實檢驗」原則本身不規範搜尋的迭代結構，本檔補充。

來源：一次規則設計過程中，4 輪查詢累積約 27 個洞察（n=1 回顧、非統計），第 4 輪反向驗證揭露核心悖論。

為什麼一次性搜尋不夠

四輪結構

進入下一輪訊號

至少 5 條判定訊號，任一觸發即可進入下一輪：

1. 該輪新洞察 < 上一輪 50%（經驗閾值）→ 邊際效益遞減（自然進入下輪或收斂）
2. 已涵蓋正反雙面 → 可進入收斂
3. 用戶補充重大反向觀察 → 立即進入反向驗證輪
4. 發現自我參照悖論 → 進入元層次反思輪
5. 出現結論互相衝突 → 進入優先級裁決輪

邊界條件

• 不一定要 4 輪：簡單議題可能 2 輪夠
• 反向驗證輪幾乎不可省略（確認偏誤防護）
• 每輪 8 個搜尋是 網路搜尋（WebSearch）平行查詢上限的經驗值——可調整
• 每輪後必暴露偏好（不偽裝中立），讓用戶可介入糾正方向

反向驗證實踐範本（第 4 輪標準格式）

標準表格格式

1| 我們的結論 | 反向搜尋目標 |
2|----------|-----------|
3| [結論 1] | [批評 / 反例 / 反駁 / 限制] |
4| [結論 2] | [批評 / 反例 / 反駁 / 限制] |

8 種反向方向類型

每輪反向搜尋必涵蓋至少 4 種，理想涵蓋全部 8 種：

單次規則設計的查詢紀錄（n=1 回顧）

下表是一次規則設計過程的事後回顧、不是可複製的統計規律。數字（搜尋數 / 洞察數 / 累積）來自該次的記憶整理、樣本量 n=1。用它理解「四輪結構大致怎麼推進」、不要當成「每次都會這樣」的基準率 —— 這正是本檔自己倡導的「基本率 > 預測、不把單次回憶當統計」。

這次的觀察（n=1、非通則）：該次第 4 輪反向驗證的洞察數最高、且最尖銳（揭露核心悖論）。這支持「反向輪值得跑」、但「反向輪是主軸」是基於單次的推論、需後續案例累積驗證。

用戶介入點記錄

多輪查詢過程中，用戶補充常常打到決策者盲點。必記錄：

用戶補充是設計者盲點的最強發現器。記錄這些介入點作為未來相似議題的提醒。

反模式

相關規則

• anti-paternalism — 第 4 輪揭露的悖論如何處理

Last Updated: 2026-04-17 Source: 規則設計過程的方法論提煉

快速模式（5 分鐘）

適用：連續失敗、被困住、宣稱「做不到」

 1[錨點] 誰是客戶？當前版本核心目標？
 2   → 這個問題影響核心目標嗎？否 → 建任務延後
 3
 4[W] 我有幾個選項？
 5   → 只有 1 個？→ 強制再找 2 個
 6   → 搜尋社群了嗎？→ 沒有 → 先搜尋再決定
 7   → 選項有實質差異嗎？→ 沒有 → 假選項，重新擴增
 8
 9[R 核心] 這類問題的常見解法和成功率？（基本率 > 預測）
10   → 問過去，不問未來
11
12[A 前置] 框架概括測試：能否用一句話概括所有方案？
13   → 能 → 回 W 擴增多元選項
14   → 否 → 進 A 核心
15
16[A 核心] 投入這個問題的時間，會擠壓哪個更重要的目標？（機會成本）
17   → 列出放棄什麼
18
19[決定] 選項消失測試：以上選項全部被移除，還能怎麼做？

完整模式（15-30 分鐘）

適用：偏離核心、重大決策

0. 錨點確認

• 誰是我們的客戶？
• 當前版本的核心目標是什麼？
• 這個問題影響核心客戶/核心目標嗎？
• 如果不影響：建提案/任務延後，回到核心任務

W — 擴增選項

• 我有幾個選項？（至少 3 個有實質差異的）
• 當前專案有沒有類似解法？（grep / LSP）
• 社群有沒有人解決過？（GitHub Issues / 文件）
• 其他領域有沒有類比方案？（AI 知識 / 網路搜尋（WebSearch））
• 選項消失測試：以上選項全部被移除，還能怎麼做？
• 假選項偵測：選項之間是不同途徑，還是同一途徑的參數微調？

R — 現實檢驗

• 這類問題的常見解法有哪些？成功率？（基本率）
• 需要什麼事證才能證明這個方法可行？（事證問題）
• 有沒有辦法用最小成本驗證假設？5 分鐘內能得到答案嗎？（試水溫）
• 搜尋了具體案例嗎？讀了內文不只標題？（近距離檢視（Zoom In））
• 最強版本論證（Steelman）：能闡明被放棄選項的優點嗎？能列出選定方案的 3 個缺點嗎？

A — 拉開距離

前置強制檢查：

• 框架概括測試：能否用一句話概括所有候選方案？「能」→ 選項多元性不足，回 W
• 反面框架識別：問題的反面框架是什麼？（未列出即強制停下列出）
• 反向思考（Consider the Opposite）：若我相信的正好相反會怎樣？能提出有力相反論述 → 重新定義問題後從 W 重跑

正式 A 階段：

• 每個選項旁列出機會成本了嗎？
• 這個決策服務於哪個優先事項？
• 投入這個問題的時間，會擠壓哪個更重要的目標？
• 不值得投入的項目，是否已記錄到提案系統或任務延後？

P — 準備好犯錯

• 行前預想：假設失敗了，列出 3 個最可能原因（任一 > 50% → 重新評估）
• 未來區間：最好結果？最壞結果？兩端都能接受？
• 安全係數：預估時間 x 1.3-1.5
• 回退計畫：失敗怎麼回退？回退成本是多少？

5. 絆腳索設定

• 設定期限：非核心問題最多花多少分鐘？
• 設定失敗門檻：幾次失敗後切換方向？
• 設定偏離警報：什麼信號代表已偏離核心目標？

決策品質自測

完成 WRAP 後，用以下問題自測：

4/6 以上通過 → 決策品質足夠。 3/6 以下 → 回到對應階段補充。

Last Updated: 2026-04-16 Version: 1.1.0

本檔位置：A 階段 + P 階段擴充。WRAP 既有的「拉開距離」與「準備犯錯」原則本身不規範規則自身的悖論檢查與設計者偏好透明化，本檔補充。

來源實證：規則設計過程中，第 4 輪反向驗證揭露「保護用戶自主性（autonomy）的規則可能限制代理人自主性（autonomy）」的核心悖論。

為什麼需要悖論識別

規則設計的常見陷阱

悖論識別檢查清單

設計規則 / 流程 / 系統時，必檢查（至少 4 條）：

檢查 1：自我參照測試

此規則的「正確示範」是否本身就是它要禁止的模式？

範例：規則禁止「強勢敘事」，但規則自己用偽中立框架預先定義問題性質，這就是自我參照悖論。

檢查 2：善意家長主義（benevolent paternalism）4 條件測試

此規則是否符合 Frontiers AI 研究提出的「善意家長主義（benevolent paternalism）4 條件」？

4 條件全通過才能稱為「正當的家長主義（paternalism）」。任一不通過即為過度家長主義（paternalism）。

檢查 3：權力對偶性測試

此規則是否本身違反它要保護的價值？

範例：保護用戶自主性（autonomy）的規則限制了 Claude（也是利害關係人（stakeholder））的自主性（autonomy）。為了 X 反而傷害 X。

處理：在規則中明示「本規則是動態平衡」並提供「用戶可覆蓋」機制。

檢查 4：設計者立場透明化測試

此規則的設計者立場是否被透明化？

設計者本身是利害關係人（stakeholder），不可能完全中立。必須明示：

• 規則由誰設計？
• 設計者的利益偏好為何？
• 用戶有什麼權利覆蓋設計者偏好？

檢查 5：用戶覆蓋機制測試

此規則是否預留「用戶可覆蓋」機制？

沒有覆蓋機制的規則 = 思想改造（thought reform）。對應 Lifton 8 條件第 7「教義凌駕個人（Doctrine over Person）」。

自我暴露偏好實踐

為什麼必要

提供建議時假裝中立 = 隱性家長主義（paternalism）。Voss 自陳「one person’s influence is another person’s manipulation」——影響力的本質取決於是否被透明化。

4 個實踐維度

為什麼推薦標記（Recommended）是暗黑模式（dark pattern）

• 暗黑模式（dark patterns）中 confirmshaming 把「拒絕」框定為負面選擇
• 推薦標記（Recommended）隱性把「未推薦」貶為次優
• 結合「位置偏誤」（推薦選項放第一）效果加倍
• DarkBench 已將此類設計列為 LLM 暗黑模式（dark pattern）

自我暴露範本

提供建議時的標準格式：

1## 我的偏好暴露（不標推薦（Recommended））
2
3| 方向 | 我的偏好 | 暴露的理由與風險 |
4|------|---------|---------------|
5| 方案 A | 強偏好 | 理由是 [Y]；但這偏好可能反映我的 [Z] 立場 |
6| 方案 B | 中等 | 理由是 [Y2] |
7| 方案 C | 低 | 理由是 [Y3]，但你可能因 [W] 反而選此 |
8| 反方向 | 開放 | 我可能未考慮的角度 |

反模式

與既有 WRAP 章節的關係

應用情境

相關規則

• iterative-research — 多輪迭代如何揭露悖論

學術依據

以下為概念來源；本檔引用的是其觀點框架、非逐項實證複製。使用時若要當論據，建議回查原文確認語境與年份。

• 善意家長主義（benevolent paternalism）4 條件框架 — 來源為 AI 倫理文獻（Frontiers 期刊系列）；本檔未綁定特定論文，引用時請回查。
• Anthropic Constitutional AI：「balance user wellbeing against user autonomy and excessive paternalism」（Anthropic 公開 CAI / HHH 論述）。
• Lifton《Thought Reform and the Psychology of Totalism》(1961) 8 條件：第 7「教義凌駕個人（Doctrine over Person）」作為反例。
• Chris Voss《Never Split the Difference》：「intent decides」（influence vs manipulation 的區分）自陳。
• DarkBench 30-61%（iterative-research 引）：為該基準的暗黑模式偵測率區間、依模型 / 指標而異，引用時需標明指標與樣本限制。

Last Updated: 2026-04-17 Source: 規則設計過程的悖論揭露與自我暴露實踐

核心判準

真正的擴增選項（Widen）會提出不同根因假設或不同達成路徑。偽擴增選項（pseudo-Widen）只是在同一假設下列出多個變體，表面上有選項，實際上仍被單一框架鎖住。

步驟

1. 寫出目前假設

1我目前假設問題是由 ______ 造成。

2. 列出相反假設

1如果問題由其他原因造成，最可能是什麼？

3. 檢查選項層級

4. 現實檢驗（Reality Test）

每個候選假設至少要有一個可驗證訊號。缺少可驗證訊號的選項保留為待驗假設，並在補齊證據後再進入方案比較。

警告信號

可複製提示

1先做偽擴增選項（pseudo-Widen）檢查：
21. 我現在假設的根因是什麼？
32. 相反假設是什麼？
43. 目前選項是否都接受同一根因？
54. 哪個證據能讓我放棄目前最相信的假設？

Last Updated: 2026-04-30 Version: 2.0.0 — 可攜偽擴增選項（pseudo-Widen）防護模板。

來源：《零偏見決斷法》— 自動駕駛模式讓人忽略機會、堅持註定失敗的計畫。

絆腳索總覽

防護型（防止壞事）

決策路徑型子型詳表

本表提供 WRAP 觸發時的查表入口；各專案可把這些子型映射到自己的掛鉤（Hook）或任務系統。

正面型（捕捉好事）

自動駕駛失敗模式

決策者進入自動駕駛的兩種表現：

切割機制

切割把連續的資源變成不連續的區塊，每個區塊結束時強迫問「是否繼續？」

WRAP 階段間的切割點

每個切割點都是「是否繼續」的有意識決定。

絆腳索的哲學

命名效應

給認知偏誤命名，就更容易注意到它：

核心提醒

Skill 不需要每次都跑完整 WRAP 流程。

有時只需要一句：「注意，你可能在自動駕駛。你是有選擇的。」

與專案系統整合

絆腳索是通用概念，各專案會有各自的實作方式：

• 期限型 — 計時器 / 掛鉤（Hook）監測 / 決策者自律
• 失敗型 — CI 失敗計數 / 重複 dispatch 偵測 / Bug tracker 標記
• 偏離型 — 任務追蹤系統的 label / milestone 統計
• 切割 — Atomic work unit / 階段性 checkpoint 機制
• 正面捕捉 — 學習捕捉 / retrospective / 知識庫記錄

各專案的具體整合（掛鉤（Hook）訊號對應、CLI 提醒訊息、狀態追蹤、自動觸發機制、規則系統對應）應放在該專案自己的落地層文件。

Last Updated: 2026-04-28 Version: 2.1.0 — 防護型新增「決策路徑型」分類，含 4 子型詳表（CLI 自動駕駛（autopilot） / 既有結論錨定（Anchor） / 草率改規則 / 多步驟成功率盲點）。 Version: 2.0.0

適用：寫互動 UI、JS reparent / hide 元素、自製 component（modal / dropdown / tabs）、客製外部組件後檢查 a11y。 不適用：純後端 / 純資料流（沒有使用者直接互動）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋鍵盤可達性三要素、focus management 模板、aria-live 設計、native HTML 優先原則。

何時參閱本文件

為什麼 a11y 是預設不是補丁

A11y 不是「完整功能後再加上」、是設計時就決定的結構：

• 用 <button> vs <div onclick> → 鍵盤 / focus / a11y tree 自帶 vs 全部要自己補
• modal 用 <dialog> vs 自己組 → focus trap / escape / scrollable / inert 自帶 vs 全部要自己補
• 動態內容變動有 aria-live vs 沒 → screen reader 知道 vs 不知道

事後補 a11y 比事前設計貴 5-10 倍。寫之前先選對結構、後續成本低。

防線 1：靜態鍵盤可達性三要素

鍵盤使用者要能用、三個元素缺一不可：

要素 1：Visible focus indicator

1/* 反例：去掉預設 focus outline */
2button:focus { outline: none; }
3
4/* 對例：可見的 focus indicator */
5button:focus-visible {
6  outline: 2px solid var(--focus-color);
7  outline-offset: 2px;
8}

:focus-visible（鍵盤 focus）跟 :focus（含滑鼠 click 後）區分 — 滑鼠使用者不需要看到 outline、鍵盤使用者必須看到。

要素 2：邏輯 Tab 順序

Tab 順序預設由 DOM tree 決定。如果視覺順序跟 DOM 順序不同（例如用 CSS grid 重排），考慮：

• 重排 DOM 順序對齊視覺
• 用 tabindex="0" 讓元素可 focus（不要用 > 0）
• 不要用 tabindex="-1" 跳過該 focus 的元素

要素 3：Modal / drawer 有 escape 路徑

1dialog.addEventListener('keydown', (e) => {
2  if (e.key === 'Escape') dialog.close();
3});

或用 <dialog> native — Escape 自帶。

防線 2：動態 a11y

Focus management on DOM move

JS reparent / hide 元素時、focus 會跑掉（落到 body）。需要保存與還原：

 1function moveFilter(targetSlot) {
 2  const filter = document.querySelector('.filter');
 3  const focused = document.activeElement;
 4  const wasFilterFocused = filter.contains(focused);
 5
 6  targetSlot.appendChild(filter);  // reparent
 7
 8  if (wasFilterFocused) {
 9    focused.focus();  // 還原 focus
10  }
11}

aria-live 廣播動態變動

Screen reader 預設不會朗讀「DOM 變動」、要明確告訴它：

1<!-- polite：等使用者操作完才朗讀（搜尋結果數量、filter 切換） -->
2<div aria-live="polite" aria-atomic="true">
3  顯示 12 筆結果
4</div>
5
6<!-- assertive：立刻打斷朗讀（錯誤訊息、緊急狀態） -->
7<div aria-live="assertive" role="alert">
8  搜尋失敗、請重試
9</div>

aria-atomic="true" 整段重讀（不只朗讀變動的部分）。

範例：搜尋結果區

1<div class="results" aria-live="polite" aria-atomic="false">
2  <p class="status">顯示 <span id="count">12</span> 筆結果</p>
3  <ul>...</ul>
4</div>

JS 更新 #count 的 textContent 時、screen reader 朗讀「顯示 12 筆結果」。

防線 3：Native HTML > ARIA

為什麼優先 Native

何時用 ARIA

ARIA 是補強、不是替代：

• 用 native 但 a11y tree 還不夠（標 aria-label / aria-describedby 補語意）
• 真的沒有 native 元素（complex composite widget、tabs、tree）
• 動態變動需要廣播（aria-live）

範例：自製 toggle 還是 native checkbox

錯：

1<div class="toggle" role="switch" tabindex="0" aria-checked="false">
2  <span class="track"></span>
3</div>
4<script>
5  toggle.addEventListener('click', ...);
6  toggle.addEventListener('keydown', e => {
7    if (e.key === 'Enter' || e.key === ' ') ...;
8  });
9</script>

對：

1<label class="toggle">
2  <input type="checkbox">
3  <span class="track" aria-hidden="true"></span>
4  <span class="visually-hidden">啟用 dark mode</span>
5</label>

1.toggle input { position: absolute; opacity: 0; }
2.toggle input:checked + .track { background: var(--brand); }

Native checkbox 自帶 keyboard / focus / state、CSS 把它隱藏、視覺用 .track 呈現。

視覺 / Motor a11y

視覺輔助

 1/* 對比度 */
 2:root { --text: #1a202c; --bg: #fff; }
 3/* WCAG AA: 普通文字 4.5:1、大文字 3:1 */
 4
 5/* 字型放大時不破版 */
 6.container { max-width: 60ch; }  /* ch 跟字型同步 */
 7.text { font-size: 1rem; line-height: 1.6; }  /* rem 跟使用者設定同步 */
 8
 9/* prefers-reduced-motion */
10@media (prefers-reduced-motion: reduce) {
11  * { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; }
12}

Motor / Hit target

1/* 觸控 hit target 最小 44×44 px (WCAG AAA) */
2button, a, [role="button"] {
3  min-height: 44px;
4  min-width: 44px;
5}
6
7/* 兩個 hit target 之間留 8px+ 間距、避免誤點 */
8.toolbar > * + * { margin-left: 8px; }

Wrong vs Right 對照

範例 1：自製 dropdown

錯：

1<div class="dropdown" tabindex="0">
2  <span>選單</span>
3  <div class="menu">
4    <div class="item">選項 1</div>
5    <div class="item">選項 2</div>
6  </div>
7</div>

問題：no native focus、no keyboard、no a11y role、screen reader 不知道是 menu。

對：

1<button aria-haspopup="menu" aria-expanded="false" aria-controls="menu1">
2  選單
3</button>
4<ul id="menu1" role="menu" hidden>
5  <li role="menuitem"><button>選項 1</button></li>
6  <li role="menuitem"><button>選項 2</button></li>
7</ul>

或如果是「選擇一個」 → <select> native。

範例 2：filter 切換沒 a11y broadcast

錯：

1button.addEventListener('click', () => {
2  document.querySelectorAll('.result').forEach(r => {
3    r.style.display = r.dataset.tag === currentFilter ? 'block' : 'none';
4  });
5});
6// screen reader 不知道結果變了

對：

1<div class="results" aria-live="polite">
2  <p class="status">顯示 <span id="count">12</span> 筆結果（filter: <span id="filter">全部</span>）</p>
3</div>

1button.addEventListener('click', () => {
2  // ... filter logic
3  document.getElementById('count').textContent = visibleCount;
4  document.getElementById('filter').textContent = currentFilter;
5  // aria-live 自動朗讀
6});

範例 3：JS 移動元素 focus 跑掉

錯：

1// resize 時把 filter 從 mobile drawer 移到 desktop sidebar
2mediaQuery.addEventListener('change', () => {
3  if (mediaQuery.matches) {
4    sidebar.appendChild(filter);
5  } else {
6    drawer.appendChild(filter);
7  }
8});
9// 如果 filter 內的某個 input 有 focus、reparent 後 focus 落到 body

對：

 1mediaQuery.addEventListener('change', () => {
 2  const focused = document.activeElement;
 3  const wasInFilter = filter.contains(focused);
 4
 5  if (mediaQuery.matches) {
 6    sidebar.appendChild(filter);
 7  } else {
 8    drawer.appendChild(filter);
 9  }
10
11  if (wasInFilter) focused.focus();  // 還原 focus
12});

自檢清單（dogfooding）

寫互動 UI 時：

• 用 <button> <dialog> <details> <fieldset> 取代自製 ARIA 結構？
• visible focus indicator 沒被 outline: none 拿掉？
• Tab 順序符合視覺順序（沒用 tabindex > 0）？
• Modal / drawer 有 Escape 關閉路徑？
• JS reparent / hide 時保存與還原 focus？
• 動態變動內容用 aria-live 廣播？
• 對比度 ≥ 4.5:1（普通文字）？
• Hit target ≥ 44×44 px？
• prefers-reduced-motion 時關掉動畫？

延伸閱讀

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

• focus-management-on-dom-move — 動態 DOM 移動時的 focus 管理
• aria-live-for-dynamic-content — Screen reader 與動態內容變動的 live region 設計
• native-html-over-aria-role — Native HTML element 優先於 ARIA role 的取捨
• keyboard-accessibility — 鍵盤可達性：focus indicator、tab 順序、escape 路徑
• motor-accessibility-hit-target — Motor 可達性：hit target、間距、誤點防護
• visual-aids-contrast-zoom-responsive — 視覺輔助：對比度、放大、字型 zoom 的 layout 適配

Last Updated: 2026-04-26 Version: 0.1.0

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

適用：寫 / 改 CSS 規則、決定 styling 該放 CSS 還是 JS、跟 vendor CSS 共存、檔案組織。 不適用：純 logic JS（沒涉及 styling）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋 CSS-only vs JS-assisted 判準、class toggle 模式、CSS layers、variable 單一位置、檔案拆分。

何時參閱本文件

為什麼 CSS / JS 邊界要清楚

樣式邏輯散落在 inline style + CSS file + JS setProperty + !important 的後果：

1. 改一個顏色要 grep 三個地方、其中一個改不到
2. DevTools 看不出「為什麼這個值在這裡」（inline style 沒 class hint、important 是核武）
3. 升級 vendor 後 specificity 戰失敗、自家規則失效

清楚的邊界 = CSS 描述「在某狀態下長什麼樣」、JS 切換狀態（toggle class / 寫 var）。樣式定義集中在 CSS、JS 不直接操作 inline style。

邊界判準：值能不能 build-time 定下來

CSS-only：值能 build-time 定下來

• Design token（--brand-color、--gap-base）
• 固定 breakpoint / aspect ratio
• 元件預設尺寸
• 跨狀態的視覺差異（.expanded、.loading）

寫成 CSS variable + class toggle、JS 只負責加減 class。

JS-assisted：必須 runtime 才能知道

• Form 高度（隨字型 / line-height 變動）
• Container 寬度（隨 viewport / sidebar 變動）
• Scroll position
• 元素的 bounding rect

JS 量測後寫回 CSS variable、CSS 仍然只讀變數：

1const formHeight = form.getBoundingClientRect().height;
2document.documentElement.style.setProperty('--form-height', `${formHeight}px`);

1.scope { top: calc(var(--form-height) + var(--gap)); }

CSS 不知道值怎麼來的、只知道讀 var — 換 framework / 換量測方式時、CSS 不動。

模式 1：Class toggle 取代 inline style

反例

1// JS 直接設 inline style + important
2function showScope() {
3  scope.style.setProperty('display', 'block', 'important');
4}
5function hideScope() {
6  scope.style.setProperty('display', 'none', 'important');
7}

DevTools 看到 inline style + important、不知道為什麼、難 debug。

對例

1function setScope(visible) {
2  scope.classList.toggle('is-visible', visible);
3}

1.scope { display: none; }
2.scope.is-visible { display: block; }

樣式留在 CSS、JS 只 toggle state。改視覺只動 CSS、改 logic 只動 JS。

模式 2：CSS Layers 取代 specificity 戰

反例

自家規則被 vendor 的 .pagefind-ui .target 蓋過、寫 .parent .container .target 加 specificity、再不行加 !important。

對例

1@layer vendor {
2  @import url('vendor/pagefind.css');
3}
4
5/* 自家規則 unlayered → 自動贏所有 layered 規則 */
6.target { color: var(--brand); }

@layer vendor 把 vendor CSS 放進低優先級的 layer、自家 unlayered 規則自動贏。再也不用打 specificity 戰。

@layer 在 Chrome 99+ / Firefox 97+ / Safari 15.4+ 全部支援（2022+）。

模式 3：CSS Variable 單一定義位置

反例

1:root { --gap: 16px; }
2.results { --gap: 16px; padding: var(--gap); }
3.scope { --gap: 16px; margin-top: var(--gap); }
4/* 三處定義、改一個地方漏改 */

對例

1:root { --gap: 16px; }
2.results { padding: var(--gap); }
3.scope { margin-top: var(--gap); }

定義集中 :root（global）、.page-search（page-scoped）、或 .pagefind-ui（component-scoped）— 挑最窄能涵蓋所有用途的 selector。其他地方只引用、不重新定義。

JS 寫 variable 也寫到同個 selector：

1document.documentElement.style.setProperty('--form-height', '...');
2// 而不是 form.style.setProperty(...) 在 form 上設

模式 4：Inline 程式碼超過 30 行就拆檔

反例

1<style>
2  .scope { ... }
3  .results { ... }
4  /* ... 50 行 */
5</style>
6<script>
7  function decorate() { ... }
8  /* ... 80 行 */
9</script>

問題：沒 syntax highlight、沒 minify、沒 fingerprint cache-bust、改一行整個 HTML reload。

對例

1{{ $css := resources.Get "css/search.css" | minify | fingerprint }}
2<link rel="stylesheet" href="{{ $css.RelPermalink }}">
3
4{{ $js := resources.Get "js/search.js" | minify | fingerprint }}
5<script src="{{ $js.RelPermalink }}" defer></script>

獨立檔案 → IDE 支援、build pipeline 處理 minify / fingerprint、cache-bust 自動。

模式 5：Runtime 量測模式統一

對齊基準上的尺寸值要嘛全寫死、要嘛全量測、不要混搭。

反例

1/* form 高度寫死、gap 寫死、scope 用 measured 值 */
2.scope {
3  top: calc(72px + 16px + var(--scope-measured));
4}

Form 高度其實會隨字型變動 → 70px 或 76px → scope 跑位。

對例 A：全寫死

1.form { height: 72px; }  /* 強制固定高度 */
2.scope { top: calc(var(--form-h) + var(--gap)); }

Form 強制固定高度、所有變數都是已知。

對例 B：全量測

1function recalc() {
2  const fH = form.getBoundingClientRect().height;
3  const gap = parseFloat(getComputedStyle(form).marginBottom);
4  document.documentElement.style.setProperty('--form-h', `${fH}px`);
5  document.documentElement.style.setProperty('--gap', `${gap}px`);
6}
7new ResizeObserver(recalc).observe(form);

1.scope { top: calc(var(--form-h) + var(--gap)); }

全部 runtime 算、CSS 只讀變數。

Wrong vs Right 對照

範例 1：搜尋框背景色客製

錯：

1input.style.setProperty('background', '#fff', 'important');
2input.style.setProperty('color', '#000', 'important');

對：

1@layer vendor { @import 'pagefind.css'; }
2
3.pagefind-ui__search-input { background: var(--bg); color: var(--text); }

JS 不需要參與、純 CSS 解。

範例 2：跨 viewport 的 sidebar 切換

錯：

1window.addEventListener('resize', () => {
2  if (window.innerWidth >= 1400) {
3    sidebar.style.display = 'block';
4  } else {
5    sidebar.style.display = 'none';
6  }
7});

對：

1.sidebar { display: none; }
2@media (min-width: 1400px) {
3  .sidebar { display: block; }
4}

值（1400）能 build-time 定下來 → CSS media query 直接寫、不需要 JS resize listener。

自檢清單（dogfooding）

寫樣式相關 code 前：

• 我有沒有問「這個值能不能 build-time 定下來」？
• 我有沒有用 !important / inline setProperty(..., 'important')？（如果有 → 換成 class toggle）
• 我有沒有跟 vendor CSS 打 specificity 戰？（如果有 → 用 @layer）
• CSS variable 是不是只在一個地方定義？
• Inline <style> / <script> 是不是 < 30 行？（超過就拆檔）
• Runtime 量測跟 hardcoded 值在同一個對齊基準上、是不是只用了一邊？

延伸閱讀

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

• css-only-vs-js-assisted — 排版精度的工具選擇
• class-toggle-over-important — class toggle 取代 inline display:none !important
• css-layers-over-specificity — CSS Layers 取代 specificity 戰
• css-variable-single-location — CSS 變數定義位置統一
• extract-css-js-files — CSS / JS 拆出獨立檔案
• runtime-measurement-unification — runtime 量測模式統一

Last Updated: 2026-04-26 Version: 0.1.0

適用：前端 paginated UI 加 filter、後端 API + middleware filter、演算法 pipeline 加 transform、map-reduce 加 post-filter、資料庫 materialized view 加 query。 不適用：純運算演算法（沒有 stream / 沒有 materialization 概念）、純 React state 管理（沒有外部 source）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋層錯位識別、五策略選擇、跨領域範例、playwright 驗證方法。

何時參閱本文件

為什麼 filter × source 是個結構性議題

Filter 操作的定義是「從 stream 中過濾出符合條件的元素」 — stream 是隱含的對象。當 stream 被分層 materialize 時、filter 套在哪一層、決定它能「看見」的元素範圍：

使用者 / 呼叫者意圖的「filter」通常是第一層（stream 全集）— 但寫程式當下手邊的對象通常是第三層（已 materialize 的 subset）。寫起來最便利的位置 ≠ 對齊意圖的位置。

這是 #67 寫作便利度跟意圖對齊反相關 在 stream 操作上的具體展現。

跨領域：同個結構、五個情境

情境 1：前端 UI + Pagefind paginated search

1// 反例：post-filter on view layer
2const all = await pagefind.search(query);
3all.results.slice(start, start + 10).forEach(render);
4document.querySelectorAll('.result').forEach(el => {
5  el.hidden = !matches(el);  // view 層 filter
6});
7// 第二批全 hidden、使用者看到「load more 沒效果」

情境 2：後端 API + ORM middleware

1# 反例：middleware 在 pagination 之後 filter
2@app.route("/posts")
3def posts():
4    page = Post.objects.paginate(page=1, per_page=10)
5    return [p for p in page.items if p.author == "author_x"]
6    # 漏掉沒在這頁的符合項

情境 3：Async iterator + take(N)

1# 反例：先 take 後 filter
2items = list(itertools.islice(stream(), 100))
3filtered = [x for x in items if matches(x)]
4# stream 後面可能還有符合的、但被 take 100 切斷了

情境 4：Map-reduce + post-reduce filter

1[shards] → [map output] → [reduce]
2                              ↓
3                         [filter]  ← 已是 reduce 後的結果

Filter 應該在 map 階段（per-shard）或 reduce 內、不是 reduce 後。

情境 5：Materialized view + SELECT

1-- 反例：在 stale view 上 filter
2SELECT * FROM posts_summary WHERE author_id = 42;
3-- view 可能是某個時點的 snapshot、漏掉之後寫入的 posts
4
5-- 對例：filter 推進原表
6SELECT * FROM posts WHERE author_id = 42;

五個情境共用結構：source 是分層 materialize 的、filter 套在下游 → silent 缺口。

五種解法策略

詳細展開見 #59 Filter × Source 合成策略五選一。本卡只列總覽：

選擇順序：A → C → B → D → E（不寫不告知的 silent 縮小、那是反模式）。

對應的 pattern 卡片：#60 自動續抓 / #61 推進 query / #62 誠實進度 UX / #65 多 index / #66 明示語意縮小

三變數決定策略選擇

選 A / B / C / D / E 看三個變數：

變數 1：Source capabilities

Source 支援哪些 server-side filter？

• 支援該 filter 條件 → A 最優
• 不支援、能控 build → 評估 C
• 都不行 → B / D / E

變數 2：Match 密度

每抓一批、預期多少筆 match？

• 高密度（每批 ≥ 1 個 match）→ B 自動續抓 OK
• 稀疏（要抓很多批才湊到一個）→ B 會拉爆、用 D / E
• 不可預期 → 加上限保護的 B + fallback 到 D

變數 3：UX 容忍度

使用者能接受多顯眼的「掃描範圍」UX？

• 完全不行（filter 是核心互動）→ A / C
• 可以顯示三數字 → D
• 一次性文字告知就行 → E

Playwright 驗證 filter × source 行為

寫完 filter 後、用 playwright 驗證是否有層錯位 silent 缺口。

驗證 1：「Load more 後 filter 後是否該有結果」

 1async ({ page }) => {
 2  await page.goto('/search/?q=pre');
 3  await page.click('[data-scope="title"]');  // 選 title-only
 4
 5  // 載入第一批、量已掃 / 命中
 6  const before = {
 7    loaded: await page.$$eval('.result', els => els.length),
 8    visible: await page.$$eval('.result:not([hidden])', els => els.length),
 9  };
10
11  await page.click('button.load-more');
12  await page.waitForTimeout(500);
13
14  const after = {
15    loaded: await page.$$eval('.result', els => els.length),
16    visible: await page.$$eval('.result:not([hidden])', els => els.length),
17  };
18
19  // 層錯位徵兆：loaded 增加、visible 沒增加
20  return {
21    deltaLoaded: after.loaded - before.loaded,
22    deltaVisible: after.visible - before.visible,
23    isSilentGap: after.loaded > before.loaded && after.visible === before.visible,
24  };
25}

驗證 2：「稀疏 case 是否拉爆」

1// 用一個極少 match 的 query 觸發 B 策略
2await page.goto('/search/?q=very_rare_keyword');
3await page.click('[data-scope="title"]');
4const startTime = Date.now();
5await page.waitForSelector('.scan-status', { timeout: 10000 });
6// 應該在 5s 內顯示「已掃完、共命中 K 個」、不該無限續抓

驗證 3：「使用者能否區分四狀態」

1const statusVisible = await page.locator('.filter-status').textContent();
2// 應該明示 loading / partial / end / empty 之一、不只是 spinner

寫成 playwright test 固化 — 未來架構改動時 CI 立刻發現 regression（#15 layout-tests-with-playwright）。

設計決策的 checklist

寫 filter 之前、跑這份 checklist：

• Source 是不是分批 / streaming / cached / lazy？（#63 資料源形狀）
• Filter 的定義域是已載入子集還是 source 全集？（使用者意圖三問、見 #58）
• Source 是否支援 server-side filter？（決定能不能用 A）
• Match 密度可預期嗎？（決定 B 是否可行）
• 三狀態（loading / empty / end）UX 怎麼區分？（#57）
• 對於「filter 後 0 筆」的情境、使用者能否區分「沒命中」vs「還沒抓到」？

Wrong vs Right 對照

範例 1：搜尋頁 title-only filter

錯：

 1// pagefind 分批載入、view 層 post-filter
 2input.addEventListener('input', async () => {
 3  const results = await pagefind.search(input.value);
 4  results.results.slice(0, 10).forEach(render);
 5});
 6
 7document.querySelector('.scope-title').addEventListener('click', () => {
 8  document.querySelectorAll('.result').forEach(el => {
 9    const title = el.querySelector('.title').textContent;
10    el.hidden = !title.includes(query);
11  });
12});

第二批 8 筆 title 不含 query → 全 hidden、使用者看到「load more 沒效果」。

對（策略 C：多 index + 切換）：

1# Build 階段
2pagefind --site public --output-subdir _pagefind-all
3pagefind --site public --root-selector "article h1, article h2" --output-subdir _pagefind-title

 1const indexes = {
 2  all: await import('/_pagefind-all/pagefind.js'),
 3  title: await import('/_pagefind-title/pagefind.js'),
 4};
 5
 6input.addEventListener('input', async () => {
 7  const pf = currentScope === 'title' ? indexes.title : indexes.all;
 8  const results = await pf.search(input.value);
 9  // results 已是「該 scope 的全集」、無層錯位
10  results.results.slice(0, 10).forEach(render);
11});

對（策略 D：誠實進度 UX、保留 view 層 filter）：

1<div class="filter-status">
2  已掃 <strong>24</strong> / <strong>~150</strong> 筆 — 命中 <strong>3</strong>
3  <button>再掃一批</button>
4</div>

1// view 層 filter 保留、但 UI 顯示掃描範圍 + 提供續抓
2function updateStatus() {
3  const all = document.querySelectorAll('.result');
4  const visible = document.querySelectorAll('.result:not([hidden])');
5  document.querySelector('.scanned').textContent = all.length;
6  document.querySelector('.matched').textContent = visible.length;
7}

範例 2：後端 API filter