本文件為「撰寫完整長篇技術文章」情境的指引。適用於 blog post、post-mortem、架構決策文件、技術評估報告、概念深度說明等需要保留思考過程的長篇內容。

自包含聲明：本文件不依賴其他 reference。讀完本文件即可獨立寫出合格技術文章。

來源：methodology 骨架整合自 tarrragon/blog 的 tech_writing_structure.md（2026-04-17）；與 compositional-writing 核心原則的映射由本檔補充。

與原子化寫作的分工

compositional-writing 的核心主張是「寫原子卡片」，但完整文章是另一種產物：卡片是最小重用單元，文章是把多張卡片用思考過程組織起來。兩者分工如下：

核心目標的差異：

• 原子化：讓讀者「用最小認知負擔找到答案」
• 完整文章：讓讀者「能複製思考過程，不只複製結論」。結論一行就能給；思考過程才是文章主體。

適用範圍

本 reference 適用於下列技術文章類型：

八條核心規則

規則一-七 處理「單篇文章內部怎麼寫」的不同層面（段落結構、句子層級、方案對照）。規則八是 meta-level、跨所有規則。規則九指向 managing-article-collections.md 處理跨多篇的議題。

規則一：階段分層（觀察 → 判讀 → 策略 → 執行）

規則的商業邏輯

技術文章的內容從「事實或需求」推導到「動作或結論」，這個過程有四個功能不同的階段。每個階段處理的問題不同、失敗模式不同：

四階段若混著寫，讀者無法區分「這一段失敗是哪個階段」，也無法判斷自己的類似情境卡在哪一步。文章只能被原封不動複製，不能被理解後套用。

做法

每個主題段落應包含四階段。不同文章類型中四階段的對應：

反例（跳過判讀，觀察直接進執行）

1## 錯誤
2
3flutter_broadcasts_4m：Kotlin 1.8 vs Java 17 mismatch
4
5## 解法
6
7在 subprojects 加上：
8tasks.withType(KotlinCompile).configureEach { jvmTarget = '17' }

問題：讀者能複製貼上，但無法回答「為什麼是 configureEach 不是其他方式」「遇到下一個類似問題怎麼想」。思考過程沒有被保存。

正例

每個節點顯式展開成六個子段落：當下看到 → 判讀 → 可選策略 → 選擇與理由 → 結果 → 事後檢視。讀者看完後即使遇到不同錯誤訊息，也能套用同一個四階段推導。

反模式（避開）

• 從觀察直接跳執行，省略判讀與策略
• 判讀留下未解問題就進策略
• 文章中出現「選擇」卻只列一個選項

例外

純介紹性段落（例如 API 參數說明）可省略「策略」階段，但不得省略判讀。

規則二：商業邏輯先於 CASE

規則的商業邏輯

技術文章的內容包含兩種資訊層次：

CASE 單獨存在沒有意義。「jvmTarget = 17」這個值需要「為什麼 JVM target 要一致」這個概念當容器才能被理解。

順序顛倒（先 CASE 後商業邏輯）等於讓讀者先記一組沒有脈絡的資料，再倒推抽象概念。這條認知路徑是反向的，多數讀者在倒推失敗後會放棄，即使專業讀者能勉強跟上也會覺得閱讀成本偏高。

做法

每個主題段落包含兩層，順序不得顛倒：

商業邏輯層：

• 主題涉及的系統層概念
• 該概念為什麼存在、解決什麼問題
• 該類內容的共通本質
• 此層不討論具體數值、路徑、屬性名

CASE 層：

• 訊息或規格中的關鍵字對應商業邏輯的哪個位置
• 具體數值或內容
• 從 CASE 推論的結論

反例（直接給 CASE，預設讀者懂背景）

1### 判讀
2
3- 這個子專案的 Java task 產出 bytecode target = 17
4- 同一個子專案的 Kotlin task 產出 bytecode target = 1.8
5- 兩者不一致觸發 Kotlin 2.2 的 strict validation

專業人士看了懂，但讀者若不知道「bytecode target」「strict validation」在系統中代表什麼，只能抓到字面字串，無法建立模型。

正例（加上商業邏輯層當容器）

 1### 判讀
 2
 3**這類錯誤的本質（商業邏輯）**：
 4
 5Android 每個 module 會分別編譯 Java 跟 Kotlin 原始碼，各自產出
 6JVM bytecode。每個 bytecode 有 target version，決定能在哪些 JVM
 7runtime 上跑。同 module 內若兩種語言產出不同 target，runtime
 8可能觸發 API 相容性問題。Kotlin 2.2 把這個從 warning 提升為 error。
 9
10**這次訊息具體說了什麼（CASE）**：
11
12- compileDebugJavaWithJavac (17) → Java 產出 target 17
13- compileDebugKotlin (1.8) → Kotlin 產出 target 1.8
14- 符合上面「module 內不一致」的 pattern

完成標準

段落結束前，讀者應能回答：

1. 這個主題在系統中為什麼重要？
2. 這個主題的具體案例對應商業邏輯的哪個位置？

若只能回答第二題，商業邏輯層不足。

規則三：評估用內在屬性（用品質維度、把時間成本留給排程）

規則的商業邏輯

技術文章經常包含選擇或比較：選 A 不選 B、用 X 不用 Y、選這個架構不選另一個。選擇的優劣取決於方案的內在屬性，不取決於執行者的時間消耗：

時間消耗是執行者的資源考量，跟方案本身的正確性無關。用時間當評估維度會造成結構性偏差：投資型方案（擴大影響、建立基礎）看起來總是比消費型方案（解當前問題）差，但兩者能力的性質不同，不應以同一量度比較。

讀者讀到時間評估會誤以為「這個方案比較好」，但真正該學到的是「兩個方案各自適合什麼情境」。

做法

每個方案比較必須包含下列維度中至少三項：

反例（用時間成本換算划不划算）

1這一步多 2 分鐘掃一遍 pub-cache，但可以省下後來約 30 分鐘的
2build-炸-修循環。明顯划算。

讀者學到的是「划不划算」這個執行層結論，沒學到兩個方案的結構性差異。

正例（用內在屬性列出方案差異）

1若當下選擇「A2 + 同步盤點 pub-cache」：
2
3- 優點：一次盤點所有同類地雷，修復範圍完整；避免之後
4  遇到一個修一個的反應式除錯
5- 缺點：盤點結果可能含假陽性；擴大修復範圍可能引入新變數
6
7當下漏掉這個選項的本質問題是：
8單點錯誤修復後沒有主動擴大搜尋同類問題。
9這是決策是否涵蓋完整問題面的問題，不是執行層的快慢考量。

反模式（避開）

不得以時間成本作為主要評估維度，包含：

• 「這方案比較快」
• 「多花 X 分鐘省下 Y 分鐘」
• 「立即可完成」

規則四：事後檢視看判讀品質

規則的商業邏輯

技術文章的品質檢視（review、事故檢討、復盤）常只看「結論對不對」，但多數失敗的根源在判讀階段：

這類問題會表現成「結論失敗」的樣子，但改善方向完全不同：

• 結論失敗 → 下次多列幾個選項
• 判讀失敗 → 下次判讀要更嚴謹、更廣、更實證

兩者混為一談會得到「要更仔細」這種無法行動的結論。

做法

文章或決策完成後，必須回答下列四題：

1. 判讀階段的「需要確認」項目是否全部解答？
2. 觀察範圍是否涵蓋同類情境，或僅處理當前一個？
3. 推論中的類比假設是否驗證？
4. 策略列舉是否完整？

任一題答「否」，對應失敗類型必須明確標示：

反例（只檢視結論，歸因模糊）

1這次修復走了彎路，下次應該更仔細。

無法行動。下次遇到類似情境仍會犯同樣錯誤。

正例（分類失敗類型，對應不同改善方向）

 1七個節點中四個失敗，分類：
 2
 3| 節點    | 失敗類型                     | 根本來源                                  |
 4| ------- | ---------------------------- | ----------------------------------------- |
 5| 節點 C  | 需要新資訊（toolchain 時機） | 節點 B 判讀留下「需要確認」但沒補         |
 6| 節點 D1 | 對稱假設                     | 節點 D 判讀用「結構對稱」取代「機制驗證」 |
 7| 節點 F  | 方法呼叫時機                 | 節點 E 判讀沒展開 API 的兩階段行為        |
 8
 9三個失敗都源自判讀未完成就進策略。不是策略選錯，是判讀階段
10進入策略時，還帶著未解決的問題。

這樣的檢視產出具體改善方向：「判讀完成標準要收緊」、「機制差異需實證」，而不是模糊的「要更仔細」。

進階：避免 hindsight 論述汙染判讀記錄

事後檢視類文章（post-mortem / 設計缺陷分析 / retrospective）有一個常見的失敗模式：論述依賴「結局已發生」的視角、產出的判斷工具只在 case 已出問題後才能用。

例：「[工具] 預設為 [限制版本]、被當 [通用版本] 用了一段時間沒事、後來才爆發問題 → 設計缺陷」——這個論述需要讀者知道結局、且歸因落在個人預見性。換成當下三軸論述「在零成本差異 + 強領域先驗下選了限制更高的選項 → 設計缺陷」、判斷不依賴結局、歸因轉到工具預設與制度。

寫設計檢討時、輪 5「反例 / 邊界」要加掃這個 frame：

• 論述是否需要「後來」「最終」「結果」這類時序詞才站得住？
• 歸因是否落在「沒預見」「沒考慮」這類個人能力？
• 結論是否寫成 case-bound 規則（「下次要記得 X」）而不是 portable 工具（「下次跑三軸」）？

詳細展開、修法、跨情境多面向應用見 design-flaw-by-current-axes-not-hindsight。

規則五：最重要的話優先說（資訊優先序）

規則的商業邏輯

技術說明包含三種資訊：核心原則（是什麼）、示例（長什麼樣）、提醒（不可如何）。AI 產出的技術文章傾向先給觀察或示例，再補「這不是任意的，而是…」的後置定義，導致讀者讀完整句才能理解首句的意義。

做法

每個技術解釋段落完成後，自問：「如果讀者只讀第一句，他知道這個概念是什麼嗎？」若答案是「不知道，他只看到一個例子」，把核心原則移到第一句。

反例（示例先，定義後）

1`omitempty` 表示欄位為零值時可以不輸出。它不是單純省字，而是宣告
2「這個欄位在某些訊息類型中不是必要資料」。

讀者先記住「為零值時可以不輸出」，才得知這是一個「可選欄位語義標記」——認知路徑反向。

正例（定義先，行為描述後）

1`omitempty` 宣告「這個欄位在某些訊息類型中不是必要資料」——它不是
2單純省字，而是可選欄位的語義標記；欄位為零值時 JSON 序列化會跳過輸出。

反模式（避開）

• 「X 是 Y。它不是單純的…，而是…」（觀察在前，定義在後）
• 「Go 欄位用 A，JSON 欄位用 B。這不是任意轉換…」（示例在前，原則在後）

結構推論：尾端「重點 / 總結」段是資訊優先序失敗的訊號

資訊優先序講「核心原則放段首」、它的結構對偶是「文章不需要尾端重述」。若一篇文章要靠尾端「重點 / 小結 / 結論 / TL;DR」段重述前文才能讓讀者記住、訊號不是「需要總結」、是正文發散 —— 概念沒在它該出現的位置講清、被攤散、所以尾端要再收一次。把概念補回正文的對應位置（即本規則的 front-load）、尾端重述就失去存在理由。

判準是「刪掉尾端總結段、看正文站不站得住」：

• 站得住 → 總結本就冗餘、刪是淨減負擔。
• 站不住 → 問題在正文組織、該重拆正文段落、不是靠總結救。

兩種結果都指向不留尾端重述段。處理段內容時分兩類：純提醒（「養成 X 習慣」「記得回頭確認」）刪 —— 提醒不傳遞新概念、讀者需要時自己回前文；有概念價值的（某設計選擇的理由）併回它在正文該出現的段落、強化 front-load。

位置決定性質、不是「有沒有摘要」：放文首的摘要（一段 abstract、文件的 description 欄位）服務「讀者決定要不要讀、先建全局框架」、在讀者還沒讀正文時提供導航；放文尾的重述在讀者讀完之後把已知內容再講一次、無導航功能。同一句「本文講 X 的三個取捨」放文首是合理摘要、放文尾是重述補丁。

例外：跨章模組 / 長篇的導覽型結尾（串連各章、給下一步路由、列模組地圖）傳遞「結構關係」這個正文沒有的新資訊、不是重述、保留。真實內容裡最常見的是「一段重述 + 一句路由」的混合型 —— 修法是外科式：切重述段、留路由句、別整段刪。

規則六：反例段落用正向陳述建立概念

規則的商業邏輯

「常見錯誤」「反模式」「禁止事項」段落的寫作目標是讓讀者建立正確概念，不是讓他記住禁止清單。

讀者在壓力情境下不會回想「規則 4：資料庫不是狀態邊界的替代品」——他只會應用「狀態邊界是程式碼架構的責任」這個概念。負面陳述只告訴讀者什麼是錯的，沒有給讀者正向的概念錨點；沒有錨點的規則記憶壽命短，在新情境中也無法套用。

做法

每個錯誤或反模式段落包含三層，順序不得顛倒：

反例（只有負面陳述，沒有概念錨點）

1### 錯誤四：過早把 memory repository 換成 ORM
2
3資料庫不是狀態邊界的替代品。即使使用資料庫，仍然需要清楚的方法、
4交易語意、copy/DTO 邊界與測試。

讀者拿到的是「資料庫 ≠ 狀態邊界」這個排除式定義。沒有正向錨點，無法內化，壓力下會遺忘。

正例（正向概念先，錯誤作對比，說明原因）

1### 錯誤四：過早把 memory repository 換成 ORM
2
3狀態邊界是程式碼架構的責任；資料庫只負責持久化。換成 ORM 只解決
4「資料去哪裡存」，沒解決「誰有權利寫、怎麼寫才一致」——後者是持久化層
5無法代勞的架構責任。
6
7引入資料庫之後，清楚的寫入方法、交易語意、copy/DTO 邊界與測試仍需
8顯式設計。

讀者拿到「狀態邊界 = 程式碼架構責任」這個概念。即使忘了這條規則，概念仍能指引新情境的判斷。

反模式（避開）

• 「X 不是 Y 的替代品」作為段落的唯一說明
• 「仍然需要 A、B、C」但沒解釋為什麼這些屬於程式碼而非資料庫的責任
• 錯誤列表只有禁令，沒有對應的正向概念

完成標準

讀者讀完後能回答：「這個主題正確的責任劃分是什麼？」若只能回答「不能用 X 替代」，正向概念層不足。

規則七：用機會成本語氣（多選項並列、各標適用情境）

規則的商業邏輯

技術文章涉及方案選擇、選擇本身有成本與收益。用「正確 / 錯誤」「應該 / 不應該」「正確概念 / 替代方案不足」這種絕對二元語氣描述方案、會誤導讀者：

絕對主義教讀者「規則」、機會成本教讀者「思考方式」。前者壓力下會忘、後者能套用到新情境。

程式設計極少有絕對正確 — 大部分選擇都是在多目標（覆蓋完整性、風險、可逆性、維護成本、可理解性、依賴前提）之間取捨。把這個事實顯現在語氣上。

做法

設計取捨段落用 A/B/C/D 多選項並列、不用「正確 vs 不足」二元。樣板：

 1## 設計取捨：[維度名]
 2
 3[情境簡述、為什麼這個維度有取捨]
 4
 5### A：[做法名]（這個專案的預設）
 6
 7- **機制**：[做法的核心動作]
 8- **選 A 的理由**：[依賴前提 / 維護成本 / 風險容忍度]
 9- **適合**：[情境特徵]
10- **代價**：[換到的東西要付的成本]
11
12### B：[替代做法]
13
14- **機制**：[...]
15- **跟 A 的取捨**：[B 換到什麼 / 失去什麼]
16- **B 比 A 好的情境**：[具體 case]
17
18### C：[另一條路]
19
20[同上]
21
22### D：[極端做法 / 反模式]
23
24- **機制**：[...]
25- **成本特別高的原因**：[...]
26- **D 才合理的情境**：[極特殊情境、若有；若無則寫「實務上幾乎不存在」]

關鍵設計原則：

1. 預設選項標「（這個專案的預設）」、不是「正確」
2. 每選項都有「適合情境」+「代價」
3. 選項數由議題決定、不強湊到 4 個（見下節）
4. 多取捨情境分多區塊、不混在一起

設計取捨的選項數由議題本身決定

機會成本框架的核心是「呈現議題的真實取捨空間」 — 議題有 N 個合理選項就寫 N 個。A/B/C/D 是這個 corpus 中常見的形態（多數技術議題確實有 3-4 個合理選項）、不該倒推成必須遵守的格式：

強湊 4 個的徵兆：

• 反覆出現「實務上幾乎不存在」 — 這是「湊不出 D 的合理情境」的承認、不是有用的描述
• 「D 才合理的情境」內容很模糊（「極特殊情境」「罕見」） — 表示 D 是強湊的
• B / C 的「比 A 好的情境」高度重疊 — 表示 B 與 C 其實是同一選項的兩種表述

真反模式直接標明

當某選項真的是反模式（在所有可預期情境都壞）、不要套「才合理的情境：實務上幾乎不存在」的格式、直接標：

1### D：[反模式名]（反模式）
2
3- **為什麼是反模式**：違反 [X 原則] / 在 [Y 情境] 造成 [Z 後果]
4- **看起來吸引人的原因**：[為什麼有人會選這個 — 通常是「看似省時間」「看似簡單」]
5- **實際發生的代價**：[具體後果]

這個格式比「假裝有合理情境」更誠實 — 讀者拿到「為什麼不該用」的明確理由、而不是模糊的「幾乎不存在」。

反模式（避開）

• 「正確概念是 X」/「應該用 X」/「不應該用 Y」
• 把規則六（反例段落）的「正向概念 vs 替代方案不足」直接套到方案對照、變成偽機會成本（仍然絕對主義）
• 用「最佳實踐」「業界標準」當論證依據（常常是個人偏好的包裝）
• 強湊 4 個選項導致「實務上幾乎不存在」的低品質 D
• 抽象層原則 / Pattern 卡片硬寫「設計取捨 A/B/C/D」（這兩類有不同 structure、見規則九）

例外

絕對主義語氣只在以下情境合理：

• 安全性（SQL injection、XSS — 是物理層原則、不是工程取捨）
• 數據完整性（race condition、ACID 違反 — 不該在 production 容忍）
• 法律 / 合規（GDPR 個資處理、accessibility 法規）

這些是「物理 / 法律事實」、不是工程取捨。可以用絕對語氣。

規則七與規則六的關係

規則六處理「反例段落」這個 special case — 當段落只在說「不要做 X」時、要有正向概念當錨點。規則七處理「方案對照段落」這個更廣的情境 — 多選項都有適用範圍、不能用「正確 vs 不足」二元描述。兩規則不衝突：

• 反例 / 常見錯誤段落 → 規則六（正向概念 + 對比錯誤）
• 多方案對照段落 → 規則七（A/B/C/D 機會成本）

規則八：自我應用 (dogfooding) — 文章在說明某條規則時、自己也遵守該規則

規則的商業邏輯

教某條規則的文字、本身就是該規則的最自然示範。違反時讀者拿到的訊號是「教學者自己都不信這條規則、那為什麼我要信」 — 比規則內容寫得不好還傷害可信度。

這條規則是 meta-level、跨所有 object-level 規則：

• 教「最重要的話優先說」（規則五）→ 教學文字本身的句首就要寫核心定義
• 教「反例段落用正向陳述」（規則六）→ 教學文字本身遇到反例也用正向陳述
• 教「機會成本語氣」（規則七）→ 教學文字本身討論做法選擇時也用 A/B 並列、不用「正確 vs 不足」
• 教「focus 是議題完整度」→ 教學文字本身的 focus 也要單一

做法

寫完每段教學文字後、自問：

1. 這段教學的規則 X 適用於這段文字本身嗎？
2. 適用 → 這段文字符合規則 X 嗎？
3. 不符合 → 改寫到符合

特別常見的違反：

反例

寫規則七（機會成本語氣）時、用句型「A/B/C/D 不是格式要求、是工具」當小節標題。這個句型本身就違反規則五（最重要的話優先說）— 否定先、定義後。

讀者看到的是：「教我用機會成本語氣的人、自己用絕對主義句型」 — 規則的可信度受傷。

正例

同一個小節改寫成「A/B/C/D 是工具：選項數由議題決定」 — 定義先、用法明確。讀者看到的是：「教這條規則的文字本身遵守上一條規則」 — 規則網互相補強、可信度上升。

反模式（避開）

• 教「最重要的話優先說」的段落本身、定義被推到後面
• 教「反例段落用正向陳述」的段落本身、純列禁止事項沒有正向錨點
• 教「機會成本語氣」的段落本身、用「正確 vs 不足」二元對立描述方案
• 教某條規則的範例本身違反該規則（看起來像 placeholder 或臨時寫的）

完成標準

讀者讀完每段教學後、不會察覺「這段文字違反了它教的規則」。每段是該規則的可工作示範。

規則九：拆分判準與三類文章 structure → 由 managing-article-collections.md 處理

跨多篇 collection 的議題（拆分判準、三類文章 structure 模板、跨篇引用 idiom）由 managing-article-collections.md 統一處理。本 reference 聚焦「單篇文章內部怎麼寫」、不重複展開：

• 拆分判準（focus 是議題完整度）：見 managing-article-collections.md → 拆分判準
• 三類文章 structure 模板：見 managing-article-collections.md → 三層 structure 詳細對照

當寫的是多篇 collection 中的一篇、先讀那邊判斷文章類型（情境檢討 / 抽象層原則 / Pattern 卡片）、再回本 reference 套用對應規則。

判讀徵兆對照

撰寫過程常見的徵兆與對應的判讀要求。看到徵兆時，作者必須回答對應問題，才能讓判讀階段完成。

用法：把徵兆欄當 grep key，文章寫到該徵兆時展開對應的判讀問題，不得跳過。

術語

提交自檢清單

提交文章前自檢：

• 四階段（觀察／判讀／策略／執行）完整，或已說明可省略的階段
• 每個主題段落先商業邏輯後 CASE
• 技術解釋的資訊優先序正確：核心原則在前，示例居中，提醒在後
• 無「X 是 Y。它不是單純的…，而是…」這種定義後置句型
• 尾端無重述型「重點 / 小結 / 結論 / TL;DR」段（刪掉它正文仍站得住=冗餘該刪、站不住=正文要重組；導覽型路由結尾除外）
• 判讀中所有「需要確認」項目已解答或註明可暫不確認
• 每個方案比較至少三個評估維度
• 未以時間成本為主要評估維度
• 事後檢視四題已回答
• 失敗類型已標示（若有）
• 判讀徵兆對照表中出現的徵兆都已展開對應問題
• 反例／常見錯誤段落有正向概念層（能回答「正確的責任劃分是什麼」）
• 無純負面陳述段落（「X 不是 Y」沒有對應正向錨點）
• Title / description / heading / link label / MOC 索引條已跟正文跑同一輪正向陳述、對意圖、grep-ability review
• 方案對照段落用機會成本語氣（A/B/C/D 多選項並列、不用「正確 vs 不足」二元）
• 沒有「正確概念是 X」「應該用 X」「不應該用 Y」這類絕對主義語句（除非是安全 / 合規 / 數據完整性等物理 / 法律事實）
• 文章聚焦的問題能用一句話說完
• 沒有「+」「與」「以及」綁兩個獨立概念的標題（議題切了一半的訊號）
• 設計取捨段落的選項數由議題決定（不強湊到 4 個、避免「實務上幾乎不存在」的假反模式）
• 真反模式直接標「反模式 — 違反 X 原則」、不假裝有合理情境
• 教某條規則的段落本身遵守該規則（規則八 dogfooding）
• 文章類型分類正確（情境檢討 / 抽象層原則 / Pattern 卡片、見 managing-article-collections.md）、用對應的 structure
• 開頭語氣：把「你」換成「我們」後語句仍自然嗎？（彆扭 = 恐嚇式、改分享式）
• 每段補充：這段消失後讀者的閱讀體驗會變差嗎？（不會 = meta 資訊或主題偏移、刪除）
• 描述行為的句子：在描述事實、還是在分配責任？（「承認」「暴露」→ 改「信號」「反映」「顯示」）
• 把 pattern 歸因為 AI 特有的句子：這個 pattern 人類作者也會犯嗎？（會 → 改為通用觀察、AI 降為觸發脈絡；「AI 的發生率更高」需要對照證據、沒有就降為假說或刪除）

多輪 Re-read Pass（multi-pass refinement）

寫完上方自檢還不是 done — 自檢是「同 frame 的最後一掃」、不是 multi-pass。Multi-pass 要求每輪用不同 frame catch 不同層的錯（literal-interception-vs-behavioral-refinement / writing-multi-pass-review）。

跑下表前先做 surface enumeration：列出 body surface（段落、表格、範例）與 metadata / navigation surface（title、description、tags、heading、link label、MOC / index entry、slug / filename）。每輪 frame 都掃同一份 surface 清單，讓正文與讀者入口維持同一個概念錨點。細節見 metadata-surface-in-writing-review。

文章用的五輪 + 兩輪文章專屬：

跳輪規則同 writing-multi-pass-review — 短文 / 即時 note 跳 4-7、production 卡片 / 教學文章全跑；輪 8-10 是 production 教學文章專用、catch 字句層問題、跑 N 輪後仍漏 catch 同類問題時觸發。

術語檢查：中文入口 + 原文錨點 + 完整名詞頭

術語檢查屬於輪 4 的命名子場景，production 卡片 / 教學文章要把它當成獨立子 pass。技術文章中的術語同時承擔可讀性、可搜尋性與概念邊界；中文讓 reader 進入段落，原文讓概念可回溯，完整名詞頭讓中文離開原句仍能獨立成立。

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

例：paternalism 在決策 / 倫理脈絡裡較接近「家長主義」；翻成帶 gender 聯想的詞會讓概念漂移。例：中文壓縮詞若只剩「盲」一個字，reader 無法判斷它是盲點、盲區或盲測；補成「多步驟成功率盲點」才有完整分類。

完整翻譯 / 轉譯流程見 translation-review。支撐原則見 terminology-keeps-original-anchor 與 compressed-chinese-terms-need-head-noun。

層次意識：frame 是 horizontal、layer 是 vertical

Multi-pass review 的「N 輪不同 frame」是 horizontal 軸（同一份文字、5 個視角輪流看）。常見的誤區是 5 輪都落在同一個 vertical layer（例如全部在看視覺層）、漏掉語意 / 邏輯層 — frame 換了但 layer 沒換、根本問題不會被觸碰。

技術文章中常見的三個檢查層次（每輪 frame 內、都要掃一次三層）：

關鍵原則：

1. 邏輯和語意錯誤會表現成視覺問題（症狀在淺層、根因在深層）
2. 視覺工具的 ceiling 在語意 / 邏輯層 — 用 CSS / emoji 蓋下游症狀 = false confidence、根因換 context 復發
3. 若多輪都在檢查視覺問題、表示 frame 換了但 layer 沒換、根本問題還沒被觸碰

反例（修錯層次）：

emoji 在容器窄時斷行：

• 第一直覺修視覺：加 white-space: nowrap → 文字溢出 → 加 overflow: hidden → 症狀堆疊、根因（兩個概念擠在一行）更深埋
• 追問層次後修結構：HIGHLIGHT 跟 REVERSE 是兩個獨立概念、不該擠在同一行 — 拆成獨立列表項、所有下游症狀同時消失

判讀層次比修法重要 — 純視覺問題（容器寬度、字體大小、跨瀏覽器）用 CSS 是對的；語意 / 邏輯下游症狀用 CSS 是 false confidence。

與核心原則的映射

本規則四條與 compositional-writing 核心原則對應關係：

反向理解：原子化要求「每張卡一個概念」，完整文章要求「每個階段一個功能」；兩者是同一個認知負擔原則在不同粒度上的體現。

Last Updated: 2026-06-25 Version: 0.9.0 — 從工具 opinion 文章 review 回流：(1) 輪 9 reader-sim 加第三 lens「meta 資訊 vs 內容」— 涵蓋 meta-commentary 殘留（AI 推理過程外露）+ 主題偏移（prompt context 系統知識洩漏）兩個 design gap；(2) 提交自檢清單加 3 個生成端自問句（恐嚇式 hook「你→我們」測試 / meta 刪除測試 / 歸因語氣判斷）。生成端自問句成本低於審查端 grep 擴充、且 4 個 design gap 中 meta-commentary 和 topic-drift 沒有穩定通用關鍵詞不適合 grep。

Last Updated: 2026-05-06 Version: 0.8.1 — WRAP 審視後降 over-claim：5 張對應 report 卡（#110-114）都加「論述基礎與限制」段揭露樣本量限制；補上 regional-terminology-alignment portable principle（地區用語對齊、輪 8 keyword bank 引用）；同步 design-flaw-by-current-axes-not-hindsight 的 WRAP 修補（個人 vs 制度歸因軟化、多面向標假設性對比） Version: 0.8.0 — Multi-pass review 加輪 8-10（keyword bank / reader simulation / self-criticism）、處理「跑了 N 輪、字句層問題仍漏」的盲點；新增三張內部 principle：colloquial-rhetoric（口語修辭 keyword bank）、prose-self-contained（reader simulation 自測）、multi-pass-review-frame-granularity（meta 層、self-criticism 三機制論述） Version: 0.7.6 — 規則四補進階段「避免 hindsight 論述汙染判讀記錄」、輪 5 補設計檢討類另掃 hindsight 論述；新增內部 principle design-flaw-by-current-axes-not-hindsight——把「設計缺陷的精準定義」從「沒預測到後來需求」改成「在當下成本對稱條件下選了限制更高的選項」、用三軸論證代替 hindsight、確保產出 portable 判斷工具 Version: 0.7.5 — 將翻譯 / 轉譯 review 升級為獨立 reference：translation-review.md，聚焦句內邏輯對位、前提檢查、因果檢查與讀者追問方向；writing-articles 保留短檢查表並轉介。 Version: 0.7.4 — 強化術語翻譯的句內邏輯檢查：譯名放回原句後要檢查主詞、動詞、修飾語、因果與讀者追問方向；避免中文順口但讓句子多出原文沒有的前提。 Version: 0.7.3 — 輪 4 補術語檢查：翻譯術語第一次出現保留原文錨點，中文壓縮術語保留完整名詞頭；新增 terminology-keeps-original-anchor 與 compressed-chinese-terms-need-head-noun 兩張內部 principle。 Version: 0.7.2 — 補 metadata / navigation surface review：title、description、heading、link label、MOC / index entry、slug / filename 先列入 surface enumeration，再跟正文跑同一輪對意圖、正向陳述與 grep-ability pass；新增內部 principle 連結，維持 skill 可攜性 Version: 0.7.1 — 修正 0.7.0 的兩個違規：(a) 移除對外部 content path 的跨引用（違反 reference-authoring-standards 自包含性、修正後段內就地展開層次論述）；(b)「不能用視覺修補替代邏輯或語意修正」改機會成本語氣（違反規則七絕對主義）；標題「層次意識」副題改成「frame 是 horizontal、layer 是 vertical」更精準描述兩軸正交；表格「檢查時機」欄改「修法」更實用、修正「對齐」錯字；加反例段落（emoji 症狀堆疊 vs 改結構）。本 reference 自包含、不引用外部內容系統 Version: 0.7.0 — 補強 multi-pass review：第 2 輪檢查清單新增「層次意識」（去掉視覺標記後還能讀嗎、有無依賴 emoji/顏色/圖表）；新增「層次意識」段落說明邏輯層 / 語意層 / 視覺層的區別與優先順序 Version: 0.6.0 — 從 references 過載的反思：把「跨多篇議題」（拆分判準、三類 structure 模板、跨篇引用 idiom）整合搬到 managing-article-collections.md；本 reference 聚焦「單篇文章內部怎麼寫」、瘦身 130 行；舊規則八 / 九 整合到那邊。新增規則八「自我應用 (dogfooding)」 — 教某條規則的段落本身遵守該規則 Version: 0.5.0 — 從批量改寫 35 篇的經驗回流：規則七補強（選項數由議題決定不強湊、真反模式直接標明、抽象層 / Pattern 卡片不寫「設計取捨 A/B/C/D」）；新增規則九「三類文章用三種 structure」（情境 / 抽象 / Pattern 各自的段落 template）；自檢清單新增五項 Version: 0.4.0 — 新增規則七「機會成本語氣」（程式設計極少絕對正確、討論的是多目標取捨；方案對照用 A/B/C/D 多選項並列）；新增規則八「focus 是議題完整度」（拆分判準是 focus、不是邊界清晰；review 必須讀內文）；自檢清單新增四項 Version: 0.3.0 — 新增規則六「反例段落用正向陳述」（排除式定義無法建立概念錨點；反例段落仍需正向概念層）；自檢清單新增兩項 Version: 0.2.0 — 新增規則五「最重要的話優先說」（資訊優先序；對應核心原則 Explicit Intent；針對 AI 生成文章主次不分反模式） Version: 0.1.0 — 初版（整合外部 methodology + 補充與核心原則的映射）