本文件處理「一個主題累積多篇相關文章後、如何維持可導航、可組合、不發散」的情境。適用於開發檢討集（report folder）、系列 blog post、技術知識庫、產品文件群。

自包含聲明：本文件不依賴其他 reference。讀完即可獨立判斷一個 article collection 該怎麼結構化。

與 writing-articles.md 的分工：那篇處理「單篇文章內部如何寫」、本篇處理「多篇文章之間如何組合」。兩篇互補、各管不同 scale。

適用範圍

當以下任一條件成立、考慮讀本檔：

• 同一主題下已有 ≥ 5 篇文章、且預期還會增加
• 多篇文章之間發現「重複的概念、重複的範例、重複的引用」
• 索引（MOC / TOC）變得龐大、超過 200 行仍無法路由清楚
• 寫第 N 篇時發現「我這條原則已經在前幾篇講過了、但讀者每次都要重讀」

三層結構

跨多篇的 article collection 自然呈現三層、每層職責不同。寫作前先判斷你要寫的篇章屬於哪一層、避免層級混淆。

各層的內容邊界

抽象原則層：

• 不寫具體 case（具體 case 在情境檢討層）
• 寫「機制 / 為什麼這條規則成立 / 跨情境如何辨識」
• 結尾列出對應的情境檢討篇、各自示範這條原則的哪個面向
• 不寫「跟其他原則的關係」（那是 MOC 的責任）

情境檢討層：

• 寫「這次的具體任務、當時的限制、選了什麼、為什麼」
• 用機會成本語氣描述方案（A/B/C/D 多選項、不用「正確 vs 不足」）
• 取捨段落中可引用 Pattern 卡片
• 結尾可援引抽象原則層、但不重述

Pattern 卡片層：

• 寫「這個 pattern 的核心動作、適合 / 不適合的情境、設計細節」
• 結尾列出「跟其他做法的取捨」（橫向比較同維度的其他 pattern）
• 不寫該 pattern 在某個具體任務的應用（那是情境檢討層）
• 卡片可被多篇情境檢討篇共同引用

層級混淆的失敗模式

寫之前自問：「這篇是給『遇到同類問題的讀者』看、還是給『要套用某個 pattern 的讀者』看、還是給『要學一條跨情境原則的讀者』看？」答案決定該寫哪一層。

抽象層辨識訊號

抽象層卡片不是隨意添加的、有明確觸發訊號：

反訊號（不該抽抽象層）：

• 只有兩篇看似相關 — 證據不足、可能只是巧合相似
• 抽出來後讀者沒有獨立 grep 該抽象層的需求
• 抽象層內容會跟某篇實作篇高度重疊（表示原則跟情境綁太緊、抽不出真正的抽象）

抽象層是精煉、不是分類 — 必須有獨立的「機制 / 為什麼」可寫、不只是把幾篇實作篇的標題列在一起。

Pattern 卡片辨識訊號

Pattern 卡片從情境檢討的「設計取捨段落」中抽出。判讀訊號：

反訊號（不該抽 Pattern 卡片）：

• 該選項只在「容忍度」這類單一參數上跟其他選項不同 — 留 inline、抽出收益低
• 該選項是反模式、沒有獨立應用情境 — 留 inline 當對比
• 該選項只在這一篇出現、未來不太可能被其他篇引用 — 留 inline

核心判準：抽出後是否多篇受惠？只有一篇用到、抽出純粹是 fragmentation。

素材庫與情境比例設計

跨多篇文章需要同時管理「讀者會看到的情境」與「作者用來支撐情境的素材」。文章情境負責教讀者推演，素材庫負責支撐反向驗證、壓力變體與後續擴寫；兩者的數量不必相同。

比例原則

當一組文章要靠真實案例、研究來源或事件材料支撐時，採「少情境、多素材」比例。文章只選 4-5 個主情境，素材庫保留約 2-3 倍的 field cases 或 source cards。

比例的核心是讓每個主情境背後至少有 2-3 個來源可支撐。這樣文章能保持可讀，素材庫也能提供足夠的反例、變體與後續延伸材料。

Source-first 規則

Field case 的責任是保存可回溯材料。案例型素材先找來源，再抽出觀察、壓力、控制缺口、判讀訊號與可轉譯情境。

Scenario card 的責任是把來源轉譯成可演練情境。情境可以把多個來源合成中性服務壓力，但每個主要壓力點都要能回查到 field case 或 source card。

Pattern card 的責任是歸納。模式可以比單一案例更抽象，但要保留支撐來源、適用邊界、判讀訊號與下一步路由。

何時補素材庫

何時停止補素材

素材庫達到「每個主情境 2-3 個來源、每個 pattern 至少 1-2 個支撐案例」後，就先停止擴充。繼續補素材的收益會下降，下一步應轉向寫文章、跑 review，或把素材回寫到 MOC。

MOC（Map of Content）設計

跨多篇 collection 的入口（collection index / README / TOC）是 MOC、不是內容。

入口的職責邊界

每條索引條目格式

1- [#N 標題](slug/) — 一句話 hook（≤ 150 字）

關鍵約束：

• 一行為限、不超過 150 字
• Hook 講「這篇講什麼問題」、不重述「該怎麼做」
• 連結用 slug、不用標題（grep 友善）

場景導讀

按任務情境列出多篇路徑、是 MOC 的合理擴展：

1### 路徑 N：[任務情境]
2`#A 標題` → `#B 標題` → `#C 標題`
3
4[一兩句說明這條路徑的閱讀邏輯]

每條路徑長度 3-5 篇、長度超過表示「這條情境本身需要一篇 master」。

MOC 該避免的內容

跨篇引用 protocol

多篇 collection 內互相引用是常態、但要有紀律：

引用要說明「為什麼」

好的引用：

具體做法（@import url(...) layer(...)）與升級兼容性、其他外部組件的 layer 策略，由 [#24 CSS Layers 取代 specificity 戰] 完整展開。在邊界辨識上、本篇要記住的是：遇到 specificity 30+ 的覆寫戰、改去看 layer 維度。

不好的引用：

另見 #24。

差別是：好引用告訴讀者「為什麼引這個、引去看什麼」、不好引用要讀者自己猜。

引用最多一層深

A 引 B、B 引 C — 讀者從 A 出發、要看完 A + B + C 才能理解、認知負擔過大。

修正方式：

• 把 C 的關鍵點濃縮進 B、B 自包含
• 或把 B 從引用鏈中移除、A 直接連 C

引用方向避免循環

A 引 B、B 也引 A — 讀者在兩篇之間來回跳、永遠不知道哪篇是「主」。

通常這表示抽象層缺漏 — A 跟 B 都在援引一個沒寫出來的共同概念、那個概念該抽成抽象層。

引用 idiom 庫

從實際 corpus 累積的引用句型、各有適用情境。讀者看到這些句型就知道引用的責任分工：

Idiom 1：抽象 ← 情境（情境檢討引用抽象層）

1> 本篇是 [#42 2 次門檻](path/) 抽象原則在「驗證工具切換」這個面向的應用。

• 位置：情境檢討文章開頭、核心原則段落之後
• 效果：讀者一眼知道「這篇是某抽象原則的具體應用」、可以選擇先讀抽象層理解 mechanism、或直接讀本篇學具體做法
• 適用：情境檢討文章、有對應的抽象層原則時

Idiom 2：責任分工（拆分後篇章互相聲明範圍）

1> 本篇焦點：客製 UI 該放哪。
2> - **framework 元件本身需要動時的安全規則**由 [#13 JS 操作 framework 元件](path/) 處理

• 位置：核心原則段落之後、為什麼段落之前
• 效果：明確劃分「本篇 vs 相關篇」的責任邊界、避免讀者期待錯
• 適用：拆分過的篇章群（例如 #5/#13 拆分後互相聲明）

Idiom 3：內聯引用（段落內援引另一篇處理細節）

1具體做法（`@import url(...) layer(...)`）與升級兼容性、其他外部組件的
2layer 策略、由 [#24 CSS Layers](path/) 完整展開。在邊界辨識上、
3本篇要記住的是：遇到 specificity 30+ 的覆寫戰、改去看 layer 維度。

• 位置：段落正文中、講到引用篇主題的地方
• 效果：讀者拿到「為什麼引、引去看什麼、本篇仍要記住什麼」三件資訊
• 適用：段落主題跟引用篇高度重疊、不適合在本篇重述

Idiom 4：MOC 連結（索引條目）

1- [#42 2 次門檻：第一次是運氣、第二次是訊號](path/) — 串 #11 / #15 / #20 / #23、跨工具/測試/思路/溝通四面向

• 位置：collection index / MOC
• 效果：標題 + 一句話 hook、讓讀者選擇要不要進入該篇
• 格式：- [#N 標題](slug/) — hook（≤ 150 字）

Idiom 5：跨原則的關係表（抽象層之間互相對位）

1| 抽象層原則 | 跟本原則的關係 |
2|---------|-------------|
3| [#43 最小必要範圍](path/) | 「最小必要範圍」聚焦「縮影響範圍」、本篇聚焦「縮值來源數」、兩者都是「讓行為可預測」的不同面向 |

• 位置：抽象層原則篇的「跟其他原則的關係」段落
• 效果：讀者看到原則網的形狀、知道哪些原則可以一起援引

Idiom 6：對應的實作篇表（抽象 → 情境 / pattern）

1| 篇 | 議題 | 範圍對象 |
2|----|------|---------|
3| [#13 元件邊界與 JS 操作](path/) | JS 元件邊界 | 「我可以動什麼」契約 |
4| [#14 Selector 精準度](path/) | DOM query 範圍 | 起點 / 範圍 / 過濾三維度 |

• 位置：抽象層原則篇結尾
• 效果：讀者依議題挑實作篇、不需要逐篇讀

三層 structure 詳細對照

跨多篇 collection 中、三類文章各有不同的 standard structure。對照表先給快速判斷依據、之後是各類完整模板。

段落對照表

分類錯了、structure 也錯。寫文章前先判斷：

• 「這篇是某次任務的紀錄嗎？」→ 情境檢討
• 「這篇是跨多情境的元規則嗎？」→ 抽象層原則
• 「這篇是某做法的深入指引嗎？」→ Pattern 卡片

情境檢討 structure 模板

 1## 核心原則
 2[一句話、加粗]
 3
 4## 為什麼 [這個議題重要]
 5### 商業邏輯
 6### [可能的子議題]
 7
 8## 這次任務的實際情境
 9### 觀察
10### 判讀
11### 執行
12
13## 設計取捨：[維度]
14### A：[做法]（這個專案的預設）
15### B：[替代]
16### C：[另一條路]
17### D：[極端 / 反模式]
18
19## 跟其他原則的關係（選用）
20
21## 判讀徵兆

抽象層原則 structure 模板

 1## 核心原則
 2[一句話、加粗]
 3
 4## 為什麼 [這條原則成立]
 5### [機制：為什麼這條規則在多情境都成立]
 6
 7## [這條原則的多個應用面向]
 8### 應用 1：[情境名]（→ 實作篇 #N）
 9### 應用 2：[情境名]（→ 實作篇 #M）
10### 應用 3：...
11
12## 不該套用 [本原則] 的情境
13[適用邊界]
14
15## 跟其他原則的關係
16[本原則跟其他抽象層原則的關係]
17
18## 對應的實作篇
19[一個表、列出每篇示範的面向]
20
21## 判讀徵兆

抽象層的取捨在情境邊界、不在方案選項。抽象層讀者面對的決定是「我這次的情境該不該套用這條原則」 — 答案在「適用 vs 不適用的情境邊界」、不在「四個並列方案中選一個」。所以抽象層的對應段落是「不該套用 X 的情境」（邊界釐清）、而非「設計取捨 A/B/C/D」（方案選擇）。

Pattern 卡片 structure 模板

 1## 核心做法
 2[做法簡述、code 範例]
 3
 4## 這個做法存在的價值
 5[為什麼這個做法獨立存在、什麼是它獨有的]
 6
 7## 適合的情境
 8[表格：情境 / 為什麼合理]
 9
10## 不適合的情境
11[表格：情境 / 為什麼不夠 / 改用 #N 其他 pattern]
12
13## 設計細節
14[實作的具體技巧、邊界 case 處理]
15
16## 跟其他 pattern 的關係
17[橫向比較同維度的其他 pattern、引用情境檢討的設計取捨段落]
18
19## 應用範例
20[具體 code 範例]
21
22## 判讀徵兆

Pattern 卡片的取捨在橫向對照、不在自家 A/B/C/D。Pattern 卡片本身是某情境檢討「設計取捨 A/B/C/D」中的一個選項（例如某「document query」就是「起點選擇」中的選項 A）。它的讀者面對的決定是「什麼時候用這個 pattern」 — 答案在「跟同維度其他 pattern 的橫向對照」、而非「自家內再分 A/B/C/D」。所以 Pattern 卡片的對應段落是「跟其他 pattern 的關係」（橫向）、而非「設計取捨 A/B/C/D」（縱向）。

structure 分類錯誤的徵兆

拆分判準：focus 是議題完整度

當不確定一篇該不該拆、判讀的核心問題是：「這篇文章聚焦在什麼問題？有沒有議題切了一半？」

兩個常見誤判

寫作 / review 雙階段自問

寫作時、寫完先自問三題：

1. 這篇聚焦的問題用一句話能說完嗎？
2. 內文每段都服務這個問題嗎？
3. 有沒有段落像是「順便提一下」的離題內容？

任一題答否、檢視該段是否該拆 / 移除 / 補進其他篇。

review 時、讀完先問三題：

1. 這篇實際聚焦在什麼問題（不看標題、看內文判斷）？
2. 標題與內文焦點對得起來嗎？
3. 有沒有兩個獨立議題各佔半篇？

兩階段共同特徵：都需要讀完內文、不能只看大綱。大綱式 review 看不出議題切了一半、看不出語氣絕對主義、看不出 focus 發散。

議題切了一半的辨識訊號

• 標題用「+」「與」「以及」綁兩個獨立概念
• 內文有兩段獨立的「為什麼這個機制成立」、各對應一個概念
• 讀者通常一次只 grep 其中一個關鍵字
• 列出讀者最可能 grep 的 3 個關鍵字、發現一個關鍵字無法涵蓋全文
• 即使不衝突、仍該拆

反例 vs 正例

反例：標題「Selector + Observer 精準度」、合在一篇

• 雖然都用「精準度」這個傘綁、機制完全不同（同步查詢 vs 非同步監聽）
• 讀者來查「我的 selector 撈太多」只關心 selector 半邊
• 讀者來查「我的 observer 觸發太頻繁」只關心 observer 半邊
• 沒有人會兩個問題同時問

正例：拆成兩篇「Selector 精準度」+「Observer 範圍與觸發頻率」、各自完整深入。

拆分後的次要判準

議題完整度（focus）通過後、再看共用價值與獨立可讀性：

不該當判準的偽指標

• 行數多寡：8KB 的文章可能 focus 緊、3KB 的文章可能議題切兩半
• 篇章邊界是否清晰：兩篇沒衝突 ≠ 各自完整
• 寫的時候是否方便：方便不是優先序

完成標準

寫完後讀者能用一句話說出「這篇在講什麼問題」、且這句話精確到「換成同義不同詞也能說清楚」。若讀者要用兩句話才能涵蓋、表示有兩個議題、該拆。

review 與重構訊號

定期回顧 collection、看下列訊號：

大綱式 review 的限制

只看標題與大綱、無法判讀：

• 文章內議題是否切了一半
• 語氣是否絕對主義
• 各段落是否服務同一個 focus
• 引用是否有實質說明

review 必須讀實際內文 — 大綱只能看「topic 對不對」、不能看「議題完整度 / 語氣 / focus」。

自檢清單

跨多篇 collection 提交前自檢：

• 三層結構就位（抽象原則 / 情境檢討 / Pattern 卡片各層該有的有）
• 各篇的層級不混淆（抽象層不寫具體 case、情境層不寫成 pattern 完整指引）
• MOC 入口只做路由、無大綱式冗餘
• MOC 每條索引一行、不超過 150 字
• 跨篇引用都說明了「為什麼引用、引去看什麼」
• 沒有 A→B→C 多層跳躍引用
• 沒有 A↔B 雙向循環引用（若有、抽抽象層）
• 沒有議題切了一半的篇章（標題與內文焦點一致）
• 機會成本語氣跨篇一致（沒有混用「正確概念」與「預設選擇」）
• 「待補完」狀態標記都更新或移除

與核心原則的映射

Last Updated: 2026-04-30 Version: 0.4.0 — 補「素材庫與情境比例設計」：文章主情境維持 4-5 個、field/source 素材維持約 2-3 倍；新增 source-first、scenario 轉譯與 pattern 歸納規則，避免以自行生成情境取代可回溯素材 Version: 0.3.0 — 從 writing-articles.md 過載反思整合內容：「拆分判準（focus 是議題完整度）」完整搬入（含寫作 / review 自問三題、議題切一半的辨識訊號、反例 vs 正例、完成標準）+「三層 structure 詳細對照」展開為完整模板（情境 / 抽象 / Pattern 各一份）+「structure 分類錯誤的徵兆」清單。現在這份 reference 完整涵蓋「跨多篇相關文章的結構設計」、不需要回 writing-articles.md 找 Version: 0.2.0 — 從批量改寫 35 篇的經驗回流：補「跨篇引用 idiom 庫」（6 種句型 + 適用情境）+「三層 structure 對照」（quick reference、詳細在 writing-articles.md 規則九） Version: 0.1.0 — 初版（從 report folder 累積 50+ 篇文章、整理跨篇結構心得）