自包含聲明：本文件不依賴其他 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。保留事實、分離原作者判讀、重建目標讀者可理解的推導，最後交付可遷移框架。

本檔位置：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 的核心是確認語言轉換後，句子仍在說同一件事。

compositional-writing 是一套寫作方法論 skill，原生位置在 .claude/skills/compositional-writing/ 供 Claude runtime 呼叫；這份是同內容的文章版本，讓人類讀者也能直接在 blog 閱讀。

核心是把寫作看成「原子卡片組合」：每段文字只承載一個概念、可獨立閱讀、可跨情境重用。適用情境涵蓋程式碼註解、文件、log、prompt、欄位設計、完整長篇技術文章與外部分析材料轉教學文章。

閱讀順序

場景 1：第一次接觸

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

直接依觸發情境跳對應 reference：

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

與 blog 專案其他資料的關係

Last Updated

2026-05-20 — 同步到 .claude/skills/compositional-writing/ @ v0.9.2：

• v0.9.2 — 新增 source-to-teaching-analysis.md，處理外部分析材料轉教學型分析文章

歷史版本：

• v0.4.0 — 新增 managing-article-collections.md（跨多篇文章結構）

• v0.5.0 — 機會成本語氣補強（選項數由議題決定、idiom 庫、三類 structure 模板）

• v0.6.0 — references 拆分減少過載 + 規則八「自我應用 (dogfooding)」

• 2026-04-24 — 初版文章化：v0.3.0 同步

自包含聲明：本文件不依賴其他 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+ 篇文章、整理跨篇結構心得）

為什麼獨立成篇：欄位設計的錯誤會被模板放大。一個設計不良的 ticket 模板會產生上百個混淆 ticket、上千則語意空洞的資料。欄位一旦上線就難以撤回，因為後續所有資料都已按此格式寫入。

自包含聲明：閱讀本文件不需要先讀其他 reference。核心原則的精要在本文件內展開於「欄位設計」情境；需要跨情境套用時，才去讀對應的 writing-*.md。

TL;DR（30 秒版本）

1. 每個欄位承載一個維度，不同欄位描述同一件事的不同面向（what 描述動作、why 陳述動機、acceptance 定義可驗證條件）。
2. frontmatter 欄位為程式化查詢服務，ID 格式、enum 值、布林命名要穩定可 grep。
3. 欄位名稱暗示其問什麼問題（why 問動機，how 問策略，blockedBy 問阻塞關係）。
4. 欄位值格式一致，enum 有限集優於自由文字，複合值用穩定分隔符。
5. 新增欄位前問七個問題（見「新增欄位的決策框架」章節），避免欄位膨脹。

目錄

1. 原子化 × 欄位：每個欄位承載一個維度
2. 索引 × 欄位：程式化查詢、ID 格式、frontmatter 設計
3. 意圖顯性 × 欄位：欄位名稱即提問
4. 可查詢性 × 欄位：值格式一致性、enum 命名
5. 欄位設計 meta：新增欄位的決策框架
6. Ticket 六欄位角度解析（六欄位總表 + 詳細範例連結）
7. 非 ticket 情境：YAML 配置、API response

1. 原子化 × 欄位：每個欄位承載一個維度

原則：每個欄位只回答一個問題。若一個欄位同時承載兩個維度，填寫者會混淆，查詢者會誤讀。

判斷標準

一個欄位的內容若出現以下徵兆，代表「承載太多維度」，應拆分：

反例：一個欄位承載兩個維度

1# 錯誤：status 同時表達「進度」和「阻塞原因」
2status: "in_progress_waiting_for_api_team"

問題：

• 查詢「所有 in_progress 的 ticket」需要字串前綴比對，不穩定。
• 改阻塞對象時，狀態字串也要改，污染查詢歷史。
• 報表無法分別統計「進度分佈」和「阻塞分佈」。

正確：兩個維度各自一個欄位

1status: in_progress
2blockedBy:
3  - team: api
4    reason: "等待 /v2/users 端點上線"

每個欄位只回答一個問題：status 回答「目前在哪個階段」，blockedBy 回答「被什麼擋住」。

原子化測試

拿一個欄位問三個問題：

1. 這個欄位回答什麼問題？ — 若答案需要「和」連接兩個問題，必須拆分。
2. 這個欄位的值能獨立變更嗎？ — 若必須連動其他資訊，代表混在一起了。
3. 能用此欄位單獨做統計/排序嗎？ — 若不能，代表它混入了其他維度。

2. 索引 × 欄位：程式化查詢、ID 格式、frontmatter 設計

原則：frontmatter 欄位存在的理由之一是讓程式能查詢。人眼看不出結構，程式才看得出。所以 ID 格式、enum 值、布林欄位的命名要為「程式化查詢」服務。

ID 格式設計

好的 ID 同時對人和程式友善。以下是穩定 ID 格式的檢查點：

frontmatter 為查詢服務

frontmatter 的目的是「讓特定查詢變快」、不是「把資訊塞進去」 — 因為光把資訊塞進去只是換個地方存、查詢仍然要 scan；要查詢變快、欄位要做特定設計（穩定鍵名、可索引的值類型、前綴命名空間）才能匹配查詢工具的索引機制。把目的搞錯會做出「資訊完整但查詢仍要全文掃」的 frontmatter、讀者得到結果但工具拿不到效益。

1---
2id: ticket-001
3title: "修復登入崩潰"
4status: in_progress
5priority: P0
6blockedBy: []
7version: v1.2.0
8wave: 3
9---

每個欄位服務一種查詢需求：

欄位不服務的查詢就不要存。例如「建立者的辦公座位」放在 frontmatter 只會污染欄位密度。

為「程式能看」優先，為「人能看」是加分

frontmatter 的值優先讓程式 grep/parse，再由顯示層（UI、報表）翻譯給人。

若需要給人看的補充描述，用獨立的自由文字欄位承接（如 blockedByReason），frontmatter 主欄位保持結構化。

3. 意圖顯性 × 欄位：欄位名稱即提問

原則：欄位名稱本身就是一個問題。填寫者看到欄位名，應立刻知道要填什麼答案。若欄位名需要額外文件解釋，代表命名不夠顯性。

好欄位名 = 好問題

反例：名稱無法暗示問題

布林欄位用 is_ / has_ / can_ 開頭

欄位名稱體現抽象層

一份文件內的欄位應處於同一抽象層。混層會讓讀者不知道該看哪個。

1# 錯誤：混抽象層
2what: "修 bug"                           # 業務層
3implementationDetail: "修改 auth.py 第 42 行"  # 實作層

改善：what 留在業務層，實作細節進 how 或 where.files。

4. 可查詢性 × 欄位：值格式一致性、enum 命名

原則：同一個欄位的值要有穩定格式，讓 grep/filter/sort 可預測。格式不一致會讓查詢需要 N 個 regex 才能覆蓋，最終退化成「用肉眼翻」。

enum 優於自由文字

有限集合的欄位應列出所有合法值：

1# 正確：status 有固定集合
2status: in_progress    # 僅限 pending / in_progress / blocked / completed / cancelled
3
4# 錯誤：狀態用自由文字
5status: "進行中，但有點卡"

enum 的三個好處：

1. grep 精確（status: in_progress 無歧義）
2. 值變更能被編譯器/驗證器捕捉
3. 統計時不用做語意聚類

enum 命名規則

複合值的穩定分隔符

若欄位必須承載複合值，用穩定的分隔符讓 regex 可拆。

1# 正確：用 : 分隔方向和目標
2direction: "to-sibling:ticket-045"
3
4# 錯誤：自由文字
5direction: "指向兄弟 ticket 045"

常見分隔符慣例：

禁止混用分隔符。若一個欄位用 :，整個系統都要用 :。

欄位值前綴做分類

當同類型但需細分時，用固定前綴而非混在自由文字中。

1# 正確：ID 前綴暗示類別
2id: PROP-042    # proposal (portability-allow: teaching example)
3id: UC-007      # use case
4id: SPEC-012    # spec
5
6# 錯誤：自由文字描述類別
7id: "proposal 42"

日期時間統一 ISO 8601

1# 正確
2createdAt: "2026-04-16"
3startedAt: "2026-04-16T09:30:00+08:00"
4
5# 錯誤
6createdAt: "2026/4/16"       # 分隔符不穩
7createdAt: "April 16, 2026"  # 不可排序
8createdAt: "昨天"             # 不可重複解析

5. 欄位設計 meta：新增欄位的決策框架

原則：欄位一旦加入就難以撤回。新增前必問以下七個問題，避免欄位膨脹、語意重疊。

新增欄位前必問清單

欄位語意重疊檢查

新增欄位時最常見的錯誤是「與既有欄位語意重疊」。檢查方式：

1. 列出新欄位的提問（它要回答什麼問題）。
2. 對照既有欄位的提問，找是否有重複。
3. 若有重複，選其一：
   • 合併：新增的維度其實可以塞進既有欄位（若不違反原子化）。
   • 改名：讓兩個欄位的提問有明確區別。
   • 捨棄：若既有欄位已能滿足，不新增。

欄位膨脹的警訊

6. Ticket 六欄位角度解析

ticket 模板的 what / why / when / where / how / acceptance 六欄位是刻意設計的多角度描述系統。每個欄位從不同角度描述同一個 ticket，合起來才是完整規格。

六欄位角度總表

詳細範例（每個欄位各 1 個正確 + 1 個混淆共 12 項）：designing-fields-ticket-6w.md

7. 非 ticket 情境：YAML 配置、API response

核心原則不只適用 ticket。以下兩個情境示範同樣的思維。

7.1 YAML 配置檔案

原則應用：

範例（正確）：

 1database:
 2  host: "db.internal"
 3  port: 5432
 4  pool:
 5    minSize: 5
 6    maxSize: 50
 7    acquireTimeoutSeconds: 10
 8
 9retry:
10  maxAttempts: 3
11  initialDelayMs: 100
12  backoffMultiplier: 2
13  retryableErrors:
14    - connection_timeout
15    - transient_network_error

範例（常見混淆）：

1# 錯誤：單位混亂、命名模糊、enum 變自由文字
2db:
3  timeout: 10          # 秒？毫秒？
4  retry: true          # 布林還是次數？
5  errors: "timeout,network"  # 為何不用列表？
6  mode: "production, maybe"  # enum 還是形容詞？

混淆分析：

• timeout 沒標單位 → 應為 timeoutSeconds 或 timeoutMs
• retry: true 語意不清 → 改為 retry.isEnabled + retry.maxAttempts
• errors 用字串列表 → 應為 YAML 陣列以利 parse
• mode 含「maybe」 → enum 必須是有限集合

7.2 API Response Schema

原則應用：

範例（正確）：

 1{
 2  "status": "success",
 3  "data": {
 4    "users": [
 5      { "id": "usr_001", "email": "alice@example.com", "role": "admin" }
 6    ]
 7  },
 8  "pagination": {
 9    "hasMore": true,
10    "nextCursor": "eyJpZCI6InVzcl8wMDEifQ==",
11    "totalCount": 1247
12  },
13  "meta": {
14    "requestId": "req_abc123",
15    "serverTime": "2026-04-16T09:30:00Z"
16  }
17}

範例（常見混淆）：

1{
2  "ok": 1,
3  "data": {
4    "result": "...",
5    "error": null,
6    "nextPage": "yes"
7  },
8  "info": "取得 10 筆資料，還有更多"
9}

混淆分析：

• ok: 1 數字當布林 → 應為 status: "success" enum
• data 同時放業務資料與錯誤（result + error）→ 原子化違反，應分開
• nextPage: "yes" 字串當布林 → 應為 hasMore: true
• info 為自由文字夾帶結構資訊 → 拆成 totalCount: 10 + hasMore: true

可攜性自檢

本文件可獨立閱讀，不引用任何特定專案的路徑、ticket ID、commit hash 或 hook 系統。核心原則與 ticket 六欄位範例皆為通用概念，可套用於任何採用多欄位結構的文件系統。

速查表

前置閱讀：先讀 designing-fields.md「六欄位角度總表」，理解六個欄位的角色分工後再閱讀本文件。

what 欄位

正確範例

欄位提問：這個 ticket 要做什麼？（描述動作/內容，不含動機）

1what: "在使用者設定頁新增「雙因素驗證（2FA）」開關，支援 TOTP 與 email 驗證碼兩種方式"

為什麼正確：

• 描述「做了什麼」（新增開關、支援兩種方式）
• 不解釋為什麼做（動機屬於 why）
• 不描述怎麼做（實作策略屬於 how）
• 範圍具體（使用者設定頁、TOTP + email），閱讀者能立刻想像成品

常見混淆：把動機寫進 what

1# 錯誤
2what: "因為最近有用戶帳號被盜，所以要加強安全，做一個 2FA"

為什麼混淆：

• 「因為…所以」的結構顯示這是動機（why），不是動作（what）
• 讀者需要剝離「因為…」才能看到真正的動作
• 與 why 欄位內容重複，降低欄位密度
• 查詢「做了什麼」時會讀到動機雜訊

改善：動機搬到 why，what 只留動作：

1what: "新增 2FA 設定開關，支援 TOTP 與 email 驗證碼"
2why:  "最近三個月有 N 起帳號盜用事件，2FA 可降低風險"

why 欄位

正確範例

欄位提問：為什麼需要做這件事？（業務動機，不含實作原因）

1why: "過去三個月登入頁崩潰影響 8% 活躍用戶，平均每位受影響用戶嘗試 3 次才成功登入。修復後預期可提升首週留存 1.5 個百分點，並減少客服工單量（當前每週 40 張與登入相關）"

為什麼正確：

• 陳述業務動機（用戶影響、留存、客服成本）
• 含具體數字讓重要性可衡量
• 不解釋「怎麼修」（那是 how 的責任）
• 不描述「做什麼」（那是 what 的責任）

常見混淆：把 what 寫進 why

1# 錯誤
2why: "要修復登入頁的崩潰 bug，會修改 auth.py 第 42 行並加 try-catch"

為什麼混淆：

• 「修復崩潰 bug」是 what，不是 why
• 「修改 auth.py 第 42 行」是 how（實作細節）
• 完全沒回答「為什麼要修」的業務問題
• 讀者讀完 why 仍不知道這個 ticket 的價值在哪

改善：動機與實作各歸各位：

1why:  "登入崩潰導致 8% 用戶流失，每週產生 40 張客服工單"
2what: "修復登入頁 authentication flow 的 null pointer"
3how:  "在 auth.py token 解析前加 guard clause；補 unit test 覆蓋 null token 情境"

when 欄位

正確範例

欄位提問：什麼時候觸發/執行這個 ticket？（條件/時機，不是動作內容）

1when: "v1.2.0 發佈前（預計 2026-05-10），依賴 W03-021 架構草案完成後即可啟動" # portability-allow: educational when-field example

為什麼正確：

• 回答「什麼時候」的問題（版本截止、前置依賴）
• 條件可被驗證（檢查 W03-021 狀態即可）
• 不混入「要做什麼」或「為什麼」

常見混淆：把 what 重述一遍

1# 錯誤
2when: "當使用者點擊登入按鈕時，系統會驗證帳密並嘗試登入"

為什麼混淆：

• 這描述的是產品行為的觸發時機，不是 ticket 執行的時機
• 把 what（驗證流程）用時序包裝後重述
• 真正的 when（ticket 啟動條件）完全缺失
• 讀者不知道何時該開始做這個 ticket

改善：分清「ticket 啟動時機」與「產品行為時機」：

1when: "登入崩潰回報量超過每週 20 起即啟動；最遲在下一個 minor 版本發佈前完成"
2what: "修復登入流程：驗證帳密 → 產生 session → 導向首頁"

where 欄位

正確範例

欄位提問：影響哪些檔案/模組/層級？（範圍定位，不是做什麼）

1where:
2  layer: Application
3  files:
4    - src/auth/login_service.py
5    - src/auth/session_manager.py
6    - tests/auth/test_login_flow.py

為什麼正確：

• 明確列出修改範圍（檔案 + 層級）
• 讓驗收者知道要檢查哪些檔案
• 協作者能預判 merge 衝突
• 不混入動作描述

常見混淆：寫抽象功能而非具體位置

1# 錯誤
2where: "使用者登入流程相關的所有地方"

為什麼混淆：

• 「所有地方」無法定位，等於沒說
• 驗收者無法確認範圍是否完整
• 協作者無法預判衝突
• 若未來 refactor，沒有具體檔案可追溯

改善：改為具體檔案清單與層級：

1where:
2  layer: Application + Infrastructure
3  files:
4    - src/auth/login_service.py        # 主邏輯
5    - src/auth/token_validator.py      # token 驗證
6    - src/infra/redis_session_store.py # session 儲存

how 欄位

正確範例

欄位提問：用什麼策略/順序實作？（實作計畫，不是業務內容）

1how:
2  task_type: Implementation
3  strategy: |
4    1. 在 token_validator 加 guard clause 處理 null/malformed token
5    2. 將 session_manager 的錯誤處理改為 Result 模式而非例外
6    3. 補 unit test 覆蓋 6 種失敗情境（null / expired / malformed / revoked / ip_mismatch / ua_mismatch）
7    4. 跑 integration test 驗證與 Redis 互動正確

為什麼正確：

• 提供實作步驟與順序
• 選擇具體技術方案（guard clause、Result 模式）
• 不重述業務需求（那是 what）
• 不寫動機（那是 why）

常見混淆：把 acceptance 寫進 how

1# 錯誤
2how:
3  strategy: "做完要通過所有單元測試，且 login 成功率回到 99.5% 以上"

為什麼混淆：

• 「通過測試」「成功率 99.5%」是驗收條件（acceptance），不是實作策略
• 沒回答「怎麼做」的問題
• 讀者不知道實際要改什麼
• 驗收與實作責任混淆

改善：分離「做法」與「驗收標準」：

1how:
2  strategy: "先加 guard clause → 改為 Result 模式 → 補單元測試 → 跑整合測試"
3acceptance:
4  - "[ ] 所有單元測試通過"
5  - "[ ] Staging 環境 login 成功率 ≥ 99.5%（觀察 24 小時）"

acceptance 欄位

正確範例

欄位提問：怎樣算完成？（可驗證的條件清單）

1acceptance:
2  - "[ ] auth 模組所有單元測試通過（含新增的 6 個失敗情境測試）"
3  - "[ ] Staging 環境連續 24 小時 login 成功率 ≥ 99.5%"
4  - "[ ] 客服工單中「登入無法使用」類別在部署後 7 天內下降 ≥ 50%"
5  - "[ ] Code review 由另一位後端工程師核可（需涵蓋錯誤處理章節）"

為什麼正確：

• 每條都可驗證（有明確判斷標準）
• 每條都可觀察（測試結果、指標、核可紀錄）
• 數字具體（99.5%、24 小時、50%、7 天）
• 不抽象（沒有「讓系統更穩定」這種不可驗證的描述）

常見混淆：不可驗證的模糊條件

1# 錯誤
2acceptance:
3  - "[ ] 使用者體驗變好"
4  - "[ ] 程式碼品質提升"
5  - "[ ] 沒有引入新的 bug"

為什麼混淆：

• 「體驗變好」無法量測（多好算好？）
• 「品質提升」主觀（誰評？）
• 「沒有新 bug」無法證明（只能證偽）
• 驗收者無法勾選，ticket 永遠完不成或隨意完成

改善：每條都要能「勾得下去」：

1acceptance:
2  - "[ ] 登入完成時間 p95 從 3.2s 降至 ≤ 1.5s（1 週平均）"
3  - "[ ] Linter 無新增 warning；cyclomatic complexity 不增加"
4  - "[ ] 迴歸測試套件（237 個）全數通過，且新增至少 6 個測試"

速查表

來源：從 designing-fields.md Ticket 六欄位角度解析段獨立拆出，保留全部詳細範例 Last Updated: 2026-04-18 Version: 1.0.0

Phase 2 的核心問題：形式合規不代表內容可理解。本流程解答「Skill 內容品質是否足以讓陌生讀者自立運作」。

適用時機

前置條件

執行 Phase 2 前，以下條件必須已成立：

• Phase 1 通過：./scripts/portability-check.sh exit 0
• SKILL.md 和所有核心 reference 均已完成（writing-code-comments / writing-documents / writing-logs / writing-prompts / writing-articles / translation-review / designing-fields）
• meta-metrics.md 已完成（M1-M2 量測方式已定義）

測試人員要求

Phase 2 測試人員必須符合：

若找不到完全陌生的測試人員，可使用「情境隔離法」：測試者在全新 session 中（不帶任何框架記憶），只閱讀指定文件後完成場景。

測試場景（3 個基本場景）

每個場景設計原則：

• 輸入：只給測試人員 SKILL.md + 1 個對應 reference
• 任務：測試人員獨立完成寫作任務
• 時限：每個場景 10 分鐘

場景 A：撰寫程式碼 doc comment

對應 reference：writing-code-comments.md

任務描述（給測試人員的指示）

你有一個 JavaScript 函式，功能是「驗證使用者輸入的書名是否符合格式（非空、長度 1-200 字元）」。

請只閱讀 SKILL.md 和 writing-code-comments.md，為以下函式撰寫一則 doc comment：

1function validateBookTitle(title) {
2    if (!title || title.trim().length === 0) return false;
3    if (title.trim().length > 200) return false;
4    return true;
5}

輸入限制

• 可讀：SKILL.md、references/writing-code-comments.md
• 不可讀：其他任何文件

預期產出

符合以下條件的 doc comment：

• 說明業務意圖（為什麼驗證，不是程式碼在做什麼）
• 說明輸入語意和邊界條件
• 說明回傳值的含義
• 不描述實作語法

評估標準

通過判定：4 項中達到 3 項以上 = 通過。

場景 B：起草技術文件段落

對應 reference：writing-documents.md

任務描述（給測試人員的指示）

你需要為一份「書庫同步錯誤處理設計」文件撰寫開頭章節（Introduction 或 Overview）。

背景資訊（只有這些）：

• 系統名稱：Readmoo 書庫管理器
• 問題：書庫同步會遇到網路中斷、資料格式不符、API 限流三種錯誤
• 讀者：接手此模組的開發者（假設有基礎 JavaScript 能力，不熟悉 Readmoo 平台）

請只閱讀 SKILL.md 和 writing-documents.md，撰寫一個 150-300 字的開頭段落，讓讀者第一眼就知道「這份文件解決什麼問題、讀它能得到什麼」。

輸入限制

• 可讀：SKILL.md、references/writing-documents.md
• 不可讀：其他任何文件

預期產出

符合以下條件的開頭段落：

• 第一句說清楚文件解決的問題（不從背景鋪陳）
• 指明讀者是誰
• 列出文件涵蓋的三種錯誤類型
• 不超過 300 字

評估標準

通過判定：4 項中達到 3 項以上 = 通過。

場景 C：設計 YAML 欄位命名

對應 reference：designing-fields.md

任務描述（給測試人員的指示）

你正在設計一份 YAML 格式的「書籍匯出任務」結構，需要包含以下資訊：

1. 任務的唯一識別碼
2. 任務被建立的原因（是使用者手動觸發，還是排程自動觸發）
3. 任務的目標輸出格式（CSV 或 JSON）
4. 任務目前的執行狀態（待執行、執行中、完成、失敗）
5. 任務完成後通知的方式（email 或 webhook）

請只閱讀 SKILL.md 和 designing-fields.md，設計上述 5 個欄位的名稱與值的格式（用 YAML 示例呈現即可）。

輸入限制

• 可讀：SKILL.md、references/designing-fields.md
• 不可讀：其他任何文件

預期產出

一段 YAML 示例，每個欄位有名稱和示例值，並附一行說明「此欄位承載什麼維度的資訊」。

評估標準

通過判定：4 項中達到 3 項以上 = 通過。

通過標準（量化）

整體 Phase 2 通過條件：

通過計算式：

1Phase 2 通過 = (所有場景通過) AND (所有場景在 10 分鐘內完成)
2
3場景通過 = 評估項通過率 >= 75%

評估問卷（測試後請測試人員回答）

每個場景完成後，請測試人員回答以下問題（1-5 分，5 分最高）：

問卷通過標準：Q1 + Q2 平均分 >= 4 分，Q3 無未解答的名詞。

執行步驟

11. 確認前置條件：執行 ./scripts/portability-check.sh，exit 0 才繼續
22. 找到測試人員（符合「對本框架陌生」條件）
33. 依序執行場景 A → B → C，記錄每個場景的完成時間和評估項結果
44. 場景結束後請測試人員完成評估問卷
55. 計算通過率（場景 + 問卷）
66. 填寫下方結果記錄表
77. 若有場景 FAIL，記錄根因並提交修正 Ticket

結果記錄表（執行後填寫）

 1Phase 2 Dry-Run 結果（日期：_____ / 執行者：_____）
 2
 3場景結果
 4
 5| 場景 | 完成時間 | 評估項通過數 | 通過判定 |
 6|------|---------|------------|---------|
 7| A：程式碼 doc comment | ___ 分鐘 | ___/4 | PASS / FAIL |
 8| B：技術文件段落 | ___ 分鐘 | ___/4 | PASS / FAIL |
 9| C：YAML 欄位設計 | ___ 分鐘 | ___/4 | PASS / FAIL |
10
11問卷結果
12
13| 問題 | 分數（1-5） | 備註 |
14|------|-----------|------|
15| Q1 觸發路由清晰度 | ___ | |
16| Q2 reference 獨立理解率 | ___ | |
17| Q3 不理解的名詞 | N/A（列出：_____） | |
18| Q4 整體可遷移性 | ___ | |
19
20整體結論：PASS / FAIL
21FAIL 時的修正清單：
22- （列出需要修正的 reference 或章節）

常見失敗根因與對應修正

Last Updated: 2026-04-18 Version: 1.0.0

核心理念：Metric 是自評工具，不是硬性 KPI。目的是讓「達成/未達成」可被重複驗證，並在 Skill 演化過程中守住設計底線。

何時參閱本檔

Metric 總覽

認知負擔類（M1-M2）為本版正式 metric；Token 類（M3-M5）為候選，待 references/ 內容穩定後再定最終閾值。

M1 — 找到答案路徑長度

定義

讀者帶著一個寫作問題從 SKILL.md 開始，需要開啟幾個檔案才能解決問題。路徑長度 = SKILL.md 外額外開啟的 reference 檔案數。

• 路徑 1：只讀 SKILL.md 就解決（極罕見，只適用於速查表即可回答的問題）
• 路徑 2：SKILL.md 指引 → 開啟 1 個 reference（預期主流）
• 路徑 3+：SKILL.md → reference A → reference B（違反本 metric）

目標值

≤ 2（SKILL.md + 1 個 reference 即解決）。

量測方式

針對本 Skill 支援的 6 個觸發情境，逐一演練：

1. 模擬讀者帶著該情境的問題進入 SKILL.md
2. 依照 SKILL.md 觸發路由表選擇 reference
3. 計算需開啟的檔案總數（含 SKILL.md）
4. 任一情境路徑長度 > 2 即 M1 FAIL

6 個觸發情境的預期路徑

預期總平均：2（所有情境都是 SKILL.md + 1 個 reference）。

量測通過條件

• 6 個情境逐一演練，每個路徑長度 ≤ 2
• 無需開啟 reference 後再被引導到另一個 reference（禁止鏈式引用）
• SKILL.md 的觸發路由表涵蓋 6 個情境，且每個情境對應唯一 reference

量測失敗的典型訊號

M2 — reference 獨立理解率

定義

隨機挑選一個 reference，讀者不看其他 reference、不看 SKILL.md 的情況下，能否獨立理解該 reference 的完整意義並套用到寫作情境。

目標值

100%（每個 reference 都必須能獨立理解）。

量測方式

對每個 reference 執行「獨立閱讀檢查」：

1. 隨機挑一個 reference（不提供 SKILL.md 和其他 reference）
2. 讀完後自問以下四個問題：
   • 我能否說出這份 reference 在講什麼情境？
   • 我能否判斷自己遇到的問題適不適合用這份 reference？
   • 我能否直接套用它給出的原則到我的寫作？
   • 我是否需要去翻其他檔案才能理解某個名詞或規則？
3. 任一問題答案為「否」（第 4 題為「是」也算否）即 M2 FAIL

量測注意事項：必須讀實際內文。大綱式 review（只看標題、目錄、frontmatter 描述）無法判讀：

• 議題是否切了一半（標題用「+」綁兩概念但內文機制完全不同）
• 語氣是否絕對主義（「正確概念是 X」vs「比較好的做法是 A、因為 [情境]」）
• 各段落是否服務同一個 focus（內文段落離題、與標題承諾不符）
• 引用是否有實質說明（「另見 X」vs「具體做法由 X 完整展開、本篇要記住的是 […]」）

M2 評估必須讀完整內文、不能只看標題與大綱。

量測通過條件

• 每個 reference 內部有完整的「情境說明」章節，讀者不看 SKILL.md 也能判斷適用性
• 所有核心原則（原子化、索引、意圖顯性與商業邏輯、可查詢性、欄位設計）在該 reference 需要時就地說明（不引用其他 reference）
• 專有名詞（Zettelkasten/MOC/原子化等）在首次出現時給出就地定義或連結到外部公認資源
• reference 間無內部交叉引用（禁止 A→B→C 鏈式）

獨立理解率計算

1獨立理解率 = 通過檢查的 reference 數 / reference 總數 × 100%

目標 100%，任一 reference 失敗即整體 M2 FAIL。

量測失敗的典型訊號

M3 — SKILL.md 主檔 token 上限（候選，未決）

定義

SKILL.md 主檔被 Claude 載入時的 token 消耗總量。

候選目標值

≤ 5000 tokens（對齊 Anthropic 官方建議：SKILL.md body < 5k tokens）。

量測方式（候選）

1. 用 Anthropic tokenizer 或 Claude Code 內建計數計算 SKILL.md 全文 token 數
2. 扣除 YAML frontmatter（frontmatter 常駐 system prompt，另計）
3. body token 數須 ≤ 5000

狀態

未決。實際閾值待 SKILL.md 與各 reference 完成後，量測實際 token 數再定最終值。可能調整方向：

• 若實際 SKILL.md 穩定在 2000 tokens 內，閾值可降為 3000 tokens 作為緩衝
• 若 SKILL.md 接近 5000 tokens，需拆分更多內容到 references 而非放寬閾值

M4 — 單一 reference 觸發載入 token（候選，未決）

定義

單一 reference 被 Claude 按需載入時的 token 消耗量。

候選目標值

≤ 3000 tokens（避免單一 reference 過大，讓讀者/Claude 只能全讀）。

量測方式（候選）

1. 對每個 reference 計算 token 數
2. 任一 reference > 3000 tokens 即 FAIL
3. 超標的 reference 應檢討：是否混入多個情境？是否能切分？

狀態

未決。實際閾值待所有 reference 完成後依分佈定案。候選分級：

• 嚴格（< 2000）：強制 reference 高度原子化
• 寬鬆（< 4000）：允許情境 reference 包含更多實例
• 最終選擇依 Skill 各 reference 完成後的實測資料定

M5 — grep 定位問題的 token 成本（候選，未決）

定義

讀者/AI 用 grep + 關鍵字在 Skill 內定位到答案時，所讀取的 token 總成本。

候選目標值

< 500 tokens（grep 結果片段 + 關鍵命中行的上下文即能回答問題）。

量測方式（候選）

1. 挑選 10 個代表性寫作問題
2. 用對應關鍵字 grep 全 Skill 內容
3. 取前 N 個命中（N=3），計算閱讀命中上下文所需 token
4. 任一問題 > 500 tokens 即 FAIL

狀態

未決。此 metric 需要：

• 先建立「代表性問題」清單（10-20 個）
• 實測 grep 命中品質（關鍵字設計是否到位）
• 依實測結果決定 500/1000/2000 tokens 哪個是可行閾值

自評流程

何時執行

由誰執行

• 撰寫者自評：寫完立即跑 M1 + M2
• 審查者覆核：Skill PR/Ticket 驗收時跑全 metric
• 跨專案使用者：在 marketplace 下載 Skill 後，建議跑 M2 確認獨立理解率

用什麼工具

自評產出格式

建議自評結果以下表記錄（貼到 Skill 或相關 ticket 的驗收區）：

 1Metric 自評結果（日期 / 執行者）
 2
 3| Metric | 結果 | 備註 |
 4|--------|------|------|
 5| M1 | PASS (所有情境 ≤ 2) | — |
 6| M2 | PASS (6/6 reference 獨立理解) | — |
 7| M3 | N/A（未決） | SKILL.md 實測 XXXX tokens |
 8| M4 | N/A（未決） | 最大 reference XXXX tokens |
 9| M5 | N/A（未決） | 待關鍵字清單定案 |
10
11整體結論：PASS / FAIL + 須修正項目清單

Metric 間的優先級

當 metric 之間出現張力時，依下列順序取捨：

1. M2 > M1：若為了降低路徑長度而讓某 reference 依賴另一個 reference，優先維持獨立理解（M2），重新設計路由而非犧牲獨立性
2. M1 > M3/M4：若為了壓 token 而切得太細導致路徑長度 > 2，優先維持 M1，放寬單檔 token 閾值
3. M2 > M5：若為了 grep 定位成本而在多處重複同一關鍵說明，優先維持 M2（獨立理解），允許 grep 命中多個檔案但每個命中都能獨立看懂

核心排序：M2 > M1 > M5 > M3 ≈ M4

這個排序反映：獨立理解是 compositional writing 的命脈（卡片盒核心），路徑長度是讀者體驗，token 是工程成本；若三者衝突，優先守住可理解性。

與上層原則的對應

變更歷史

自包含聲明：閱讀本文件不需要先讀其他 reference。品質驗收 metric（M1-M2）見 meta-metrics.md；本文件聚焦「如何寫出符合品質的 reference」。

何時參閱本文件

一份合格 Reference 的五項必要要素

要素 1：情境聲明（何時讀這份文件）

每份 reference 的開頭必須有明確的「情境說明」段落，讓讀者在 30 秒內判斷適用性。

必須回答的問題：

• 這份 reference 服務哪種寫作情境？
• 讀者帶著什麼問題進來？
• 不適用的情境是什麼？

範本：

1本 reference 為「撰寫 prompt / instruction / Agent 派發」情境。
2
3適用：給 AI 模型的指令；Ticket Context Bundle；結構化派發 prompt。
4不適用：文件（見 writing-documents.md）；程式碼註解（見 writing-code-comments.md）。

反例（情境不明確）：

1本文件說明寫作原則的應用。

要素 2：職責單一性（原子化測試）

每份 reference 只服務一個讀者群體、回答一類問題。

判斷方法（原子化測試）：

反例（雙重職責）：

一份 reference 同時說明「如何撰寫 prompt」AND「如何撰寫其他 reference」——兩個讀者群體、兩種產出，必須拆分。

要素 3：自包含性（M2 通過）

讀者不看 SKILL.md 和其他 reference 的情況下，能獨立理解並套用。

自包含清單：

• 開頭有情境說明（不依賴 SKILL.md 判斷適用性）
• 文件內所有原則在本文件內展開（不引用其他 reference）
• 專有名詞在首次出現時給出就地定義
• 無「見 writing-xxx.md」的交叉引用（禁止鏈式）

可接受的外部引用：

• 引用外部公認資源（Anthropic 官方文件、業界標準）
• 引用 SKILL.md 觸發路由（只在「閱讀決策」表格中）
• 引用 meta-metrics.md 的量測方式（品質驗收場景）

要素 4：結構一致性

本 Skill 的所有 reference 遵循相同的段落骨架，便於讀者跨文件快速定位。

標準骨架：

 1# [Reference 名稱]
 2
 3[1-3 行情境說明，含適用/不適用聲明]
 4
 5> **自包含聲明**：[說明閱讀本文件是否需要其他前置文件]
 6
 7---
 8
 9## 何時參閱本文件（或：情境定位）
10[觸發情境表格]
11
12## 為什麼 [情境] 需要獨立指引
13[說明此情境的特殊性，與一般文件的差異]
14
15## [核心原則 × 情境] 的應用
16（依情境選擇相關原則展開，每個原則含判斷標準 + 反例 + 正確做法）
17
18## [情境特有章節]
19（例如：Token 節省策略、結構化範例、自檢清單、反模式速查）
20
21## 延伸閱讀（可選）

允許調整：

• 章節名稱可隨情境調整（「Token 節省策略」僅適用 prompt；「Log 結構化格式」僅適用 logs）
• 字數無硬性上限，但每個章節應只承載一個概念（M4 候選閾值 ≤ 3000 tokens）

要素 5：范例的具體性

範例必須足夠具體，讀者能「複製後略作修改直接套用」。

範例品質標準：

新增 Reference 的決策流程

在建立新 reference 前，先回答以下問題：

 11. 此情境是否已有 reference 覆蓋？
 2   是 → 擴充現有 reference（不新增）
 3   否 → 繼續
 4
 52. 此情境的讀者群體是否唯一（原子化測試）？
 6   否 → 拆分或重新定義情境邊界
 7   是 → 繼續
 8
 93. 此情境是否需要對核心原則的「情境翻譯」？
10   否 → 考慮是否應放入 SKILL.md 核心原則速查表（不需要獨立 reference）
11   是 → 建立新 reference
12
134. 新 reference 加入後，SKILL.md 路由表的每個情境是否仍然唯一對應？
14   否 → 情境切分重疊，重新設計邊界
15   是 → 確認可新增

驗收清單

新增或修改 reference 後，逐項確認：

職責單一性

• 原子化測試通過（一個讀者群體、一類問題）
• 無在標題或聲明中宣稱承擔多重職責

自包含性（對應 M2）

• 情境說明段落存在，30 秒內可判斷適用性
• 核心原則的必要內容在本文件內就地展開
• 無交叉引用其他 reference（只允許外部公認資源引用）

結構一致性

• 遵循標準骨架（情境說明 → 為什麼獨立 → 原則應用 → 情境章節 → 自檢清單）
• 所有原則有反例 + 正例對照

路由一致性（對應 M1）

• SKILL.md 觸發路由表已更新
• Directory Index 已更新
• 新情境與現有情境無重疊

范例品質

• 每個原則有至少一組「錯 vs 對」
• 正例使用 snake_case 佔位符，可直接套用

與 meta-metrics.md 的分工

兩者互補：先用本文件的標準寫，再用 meta-metrics.md 的方法量測。

Last Updated: 2026-04-18 Version: 1.0.0 — 從 writing-prompts.md 雙職責拆分：Skill 品質規範獨立為本檔，writing-prompts.md 保留 prompt 寫作情境

content/skills/ 收錄從 .claude/skills/ 轉成文章的 skill 版本。

同一份 skill 有兩種存在形式，各自負責不同角色：

兩處內容相同、結構略有差異：.claude/ 版本保留原始 SKILL.md + references/ 巢狀結構以配合 Claude 的路徑解析；content/ 版本扁平化（references 內容升級到同層），以契合 blog 的單層文章呈現。

目前收錄的 skill

把新 skill 轉成文章的標準流程

以下步驟假設新 skill 已經放在 .claude/skills/<name>/，包含 SKILL.md 和（可能的）references/ 子資料夾。

Step 1：複製一份到 content/skills/

1cp -R .claude/skills/<name> content/skills/<name>

Claude 版保持原樣、不再動它；所有後續修改都只改文章版。

Step 2：扁平化 references/

Blog 的文章層級為單層，不保留 references 子資料夾。把所有 reference 移到跟 SKILL.md 同一層：

1cd content/skills/<name>
2git mv references/*.md .
3git rm references/.gitkeep       # 如果有
4rmdir references

Step 3：把 SKILL.md 改成小寫 skill.md

Hugo pretty URL 會把檔名小寫輸出（SKILL.md → /skills/<name>/skill/），但 mdtools cards 連結檢查以檔名大小寫敏感的方式解析 URL 回檔案位置。若檔案是 SKILL.md，cards 嘗試開啟 skill.md 找不到，就會報 L1-broken-link。

避免這個陷阱，把 content 版本的檔名直接改成小寫：

1git mv content/skills/<name>/SKILL.md content/skills/<name>/skill.md

.claude/ 版保留原本的 SKILL.md（符合 Claude skill 慣例）。兩邊檔名不同是刻意的：runtime 讀 .claude/SKILL.md、Hugo 渲染 content/skill.md、cards check 能解析。

Step 4：修改 skill.md 的內部連結

skill.md 裡原本的 references/X.md 引用要改。有兩種合法寫法擇一：

• Markdown 相對路徑：./X.md — 最無痛，Hugo render hook 會自動解析到對應頁面
• Hugo content-root 絕對路徑：/skills/<name>/<slug>/ — 最穩，跟 blog 其他文章遷移後的寫法一致

批次替換範例（將 references/ 前綴整串刪除）：

1sed -i '' 's|references/|./|g' content/skills/<name>/skill.md

記得同時更新 ## Directory Index 區塊那張 ASCII tree — 刪掉 └── references/ 那一層、所有 reference 檔案縮排提到 skill.md 同層。

Step 5：建立 _index.md（section 索引）

content/skills/<name>/_index.md 是 Hugo section 的 landing page，URL 是 /skills/<name>/。

必備欄位（Hugo + mdtools 要求）：

1---
2title: "<Skill 名稱中英對照>"
3date: <YYYY-MM-DD>
4description: "<一句話描述 skill 做什麼>"
5tags: [...]
6---

內容建議包含：

1. 簡述：這個 skill 是什麼、解決什麼問題
2. 閱讀順序：場景 1（第一次接觸）與場景 2（已熟悉、直接解決任務）兩個切入點
3. 觸發路由表：複製 SKILL.md 的「When to Consult This Skill」表，但把檔案路徑替換成 Hugo 絕對 URL（/skills/<name>/<slug>/）
4. 與 blog 其他資料的關係：對照表（.claude/skills/<name>/、相關 content/posts/...）
5. Last Updated：同步日期與 .claude/ 版 SKILL.md 的 version

可參考 compositional-writing 的 _index.md 當範本。

Step 6：補 Hugo frontmatter 到 skill.md 與每份 reference

原始 skill.md 與 reference 的 frontmatter 是為 Claude runtime 設計的（欄位多為 name/license/metadata），Hugo 與 mdtools 需要的是 title + date。每份檔案：

1. 把原 frontmatter 保留或替換成 Hugo 規格（title、date、description、tags）
2. 刪掉 body 開頭的 # H1（Hugo 會從 title 自動生成 H1，保留會觸發 MD025-no-body-h1）

Step 7：跑 make check 與 hugo 驗收

1make check    # fmt + lint + cards，三個閘門全綠
2hugo          # 確認無 WARN/ERROR，page count 多了對應檔數

幾個常見訊號與對應的修補點：

Step 8：更新本 content/skills/_index.md 的「目前收錄」表

把新 skill 加入上方的表格，含主題一句話與 Hugo URL。

Step 9：commit

單一 commit 收尾：

1git add .claude/skills/<name> content/skills/<name> content/skills/_index.md
2git commit -m "docs(skills): import <name> skill"

設計決策備忘

為什麼 .claude/ 保留 references/、content/ 扁平？

.claude/ 是 Claude runtime 的 SKILL 執行環境，SKILL.md 的路徑解析（references/X.md）是 skill 原生協議的一部分 — 改了會破壞 Claude 讀取行為。

content/ 是 blog 文章，Hugo 的 pretty URL 傾向單層結構（/skills/name/page/ 比 /skills/name/references/page/ 乾淨）。扁平化也讓 render hook 的 tooltip 與 mdtools 的 card graph 不必穿一層目錄。

兩種結構並行、各自最佳化、用 step 1 的複製動作維持同步。

為什麼不直接 symlink content/skills/ → .claude/skills/？

Symlink 會讓兩邊共用 frontmatter 與路徑規範。.claude/ 版的 frontmatter 是 skill protocol（name/license/metadata），與 Hugo 要的（title/date）相衝；body 開頭的 # H1 是 Claude 讀者的 context signpost，但在 Hugo 會跟 title 生的 H1 重複。結構上看似省事，語意上兩邊是不同受眾的產出，應該允許各自演化。

Last Updated

2026-04-24 — 初版：compositional-writing 轉文章完成，記錄標準流程。

自包含聲明：本文件不依賴其他 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 + 補充與核心原則的映射）

核心命題：註解是業務需求和設計意圖的守護者。註解的認知依賴必須跟著程式依賴一起降低——介面的註解只寫契約，不洩漏實作；實作的註解說明業務規則，不描述語法選擇。

適用時機

當你準備寫 / 改 / 審查以下任一註解時，應用本指引：

不適用：commit message、PR description、ticket context（另見其他情境 reference）。

原則一：原子化 × 註解

一則註解只解釋一個概念。 一個函式若需要註解說明多個不相關的關注點，應先拆分函式，再為每個函式寫獨立註解。

正例

1/// 【需求】UC-003 書籍狀態轉換
2/// 書籍從「閱讀中」改為「已完成」時，自動將進度設為 100%
3/// 約束：不可覆蓋使用者手動設定的進度值
4void markBookCompleted(BookId id) { /* ... */ }
5
6/// 【需求】UC-003 書籍狀態轉換
7/// 書籍從「未開始」改為「閱讀中」時，初始化進度為 0%
8/// 約束：不重置已有的閱讀時間紀錄
9void markBookReading(BookId id) { /* ... */ }

每則註解只描述一個狀態轉換規則，閱讀者不需同時記住兩條規則才能理解一個函式。

反例

1/// 【需求】UC-003 書籍狀態轉換
2/// 處理所有狀態變化：未開始→閱讀中時進度設 0%、閱讀中→完成時進度設 100%、
3/// 完成→未開始時清空進度、任何狀態→暫停時保留進度並記錄暫停時間
4/// 約束：不覆蓋使用者手動進度，除了清空場景
5/// 例外：管理員可跳過轉換規則直接設定任何狀態
6void handleBookStatusChange(BookId id, Status from, Status to) { /* ... */ }

註解承擔 4 種狀態轉換的全部規則，閱讀者認知負擔爆表（規則數 × 例外數 = 複合爆炸），函式本身也違反單一職責。

判斷標準

• 註解超過 5 行且包含 2+ 個「且」「或」「除了」「同時」？→ 拆分函式
• 同一註解內有多個無關的約束條件？→ 拆分函式

原則二：索引 × 註解

需求編號（UC-XXX、BR-XXX、TKT-ID）是註解的「連結卡」，讓註解與規格文件、ticket、worklog 之間建立可追溯的索引。

正例

1/// 【需求】UC-004 書籍搜尋功能
2/// 【規格】docs/spec/search.md#fuzzy-match
3/// 支援書名、作者、標籤的模糊搜尋
4/// 擴展指引：新增搜尋條件時必須更新 SearchCriteria 值物件
5List<Book> searchBooks(SearchCriteria criteria) { /* ... */ }

閱讀者可從 UC-004 跳到需求文件，從規格路徑跳到設計細節。三者互為索引卡片。

反例

1/// 實作書籍搜尋功能，根據某些條件查找
2List<Book> searchBooks(SearchCriteria criteria) { /* ... */ }

沒有需求索引，閱讀者無法回溯「這個函式為什麼存在」「規格在哪」。

索引內容建議

禁止：註解內放 ticket ID（如 v1.2.3-W5-001、TKT-1234），ticket 是臨時追蹤編號，會被搬移歸檔；需求編號（UC/BR）才是穩定索引。

原則三：意圖顯性與商業邏輯 × 註解

Doc comment 描述業務情境，不解釋語法選擇。 閱讀者想知道「這段程式解決什麼業務問題」「什麼情境下會觸發」「如果不這樣做會發生什麼產品層面後果」；語法細節（while vs if、async、late 變數）讀者看 code 就能推斷，不需要 doc comment 佔用最靠近視線的位置解釋。

3.1 語法 vs 業務情境區分

註解的語法層 vs 業務層區分：

反例：語法選擇解釋

1/// 使用 while 迴圈而非 if，因為 job queue 可能有多筆任務需要依序處理
2/// 使用 async 以避免阻塞 UI thread
3/// 使用 late 變數因為 printer 物件在建構時尚未就緒
4Future<void> processPrintJobs() async {
5  while (jobs.isNotEmpty) { /* ... */ }
6}

這三行都在解釋語法選擇，讀者看 code 已能推斷 async、late、while 的技術動機。沒有任何業務資訊。

正例：業務情境聚焦

1/// 【需求】UC-008 列印佇列管理
2/// 印表機一次只能處理一份任務；若同時送出多份會造成頁面交錯（使用者投訴 #234）。
3/// 此函式確保所有 pending 任務依送出順序依序處理，直到佇列清空。
4/// 約束：佇列處理期間不可接受新任務（由呼叫端的鎖保證）
5/// 【相依】[PrinterLockService]
6Future<void> processPrintJobs() async { /* ... */ }

讀完可理解：業務情境（印表機獨佔）、觸發條件（多份任務同時送出）、失敗後果（頁面交錯 + 使用者投訴）、約束（外部鎖）。技術細節（async/while）由 code 自明。

3.2 Doc comment 聚焦業務情境

Doc comment 是函式、類別、介面的契約說明，應回答三個問題：

1. 解決什麼業務問題：此程式存在的商業原因
2. 什麼情境觸發：使用者的哪個動作、系統的哪個狀態會進入此路徑
3. 不這樣做的產品後果：錯誤實作會造成什麼使用者可見的問題

反例：純技術描述

1/// 將 Book 物件序列化為 JSON 字串並寫入 SharedPreferences
2/// 使用 jsonEncode 和 keyPrefix = 'book_'
3void saveBook(Book book) { /* ... */ }

只描述「怎麼做」，沒說「為什麼做」「什麼時候該做」。

正例：業務情境驅動

1/// 【需求】UC-002 離線書庫
2/// 使用者關閉 app 後重開仍能看到書庫清單（不需重新從 Readmoo 抓取）。
3/// 觸發時機：使用者匯入新書、編輯書籍標籤、標記進度時。
4/// 若未持久化，使用者每次開 app 都要等網路載入，離線時完全無法使用。
5void saveBook(Book book) { /* ... */ }

3.3 禁止 Doc comment 寫 TODO / placeholder

Doc comment 描述穩定契約，不應包含「等等要做 X」「暫時這樣」「未來會改」等臨時性內容。TODO/placeholder 應該：

反例

1/// 【需求】UC-005 閱讀進度同步
2/// TODO: 之後要加入衝突解決邏輯
3/// 暫時實作：直接覆蓋本地值，不處理同時間多裝置修改
4/// 注意：此函式還沒寫單元測試（placeholder）
5Future<void> syncProgress(Book book) { /* ... */ }

Doc comment 是契約，卻充滿「之後」「暫時」「還沒」——讀者無法判斷哪些是契約、哪些是待辦。

正例

1/// 【需求】UC-005 閱讀進度同步
2/// 將本地進度寫入雲端。同時間多裝置修改時，採 last-write-wins。
3/// 約束：網路失敗時本地變更會留在 outbox 等待重試（呼叫端不需處理失敗）
4Future<void> syncProgress(Book book) { /* ... */ }
5
6// TODO(<ticket-id>): last-write-wins 是暫時策略，實作 vector clock 衝突解決
7// 暫時不寫測試，<ticket-id> 追蹤

Doc 只描述當前契約（LWW 策略是當前的契約，不是「暫時」），TODO 放 inline 並指向 ticket。

3.4 註解貼合抽象層級

介面的註解只寫契約，不洩漏實作。 程式刻意解耦（介面 vs 實作、模組 vs 模組）是為了讓讀/改某一層時不需通盤理解其他層；若註解又把實作細節拉回介面裡，讀介面等於要先認識實作，抽象帶來的好處被註解抵消掉。

核心原則：註解的認知依賴必須跟著程式依賴一起降低。

反例：介面 doc 洩漏實作

1abstract class OrderRepository {
2  /// 取得訂單清單。
3  /// 資料來源由實作層決定（目前為定時輪詢 [IOnlineOrderService]），
4  /// 消費端不需關心來源為輪詢或推播。
5  Future<List<Order>> fetchOrders();
6}

既說「不需關心」又主動告知「目前是輪詢」，自相矛盾且洩漏實作。讀者看完反而被迫知道實作是輪詢，介面的抽象價值被註解抵消。

正例：只寫契約 + 命名引用

1abstract class OrderRepository {
2  /// 取得訂單清單。
3  /// 保證按建立時間由新到舊排序。空結果回傳空陣列（不拋例外）。
4  /// 資料來源：[IOnlineOrderService]
5  Future<List<Order>> fetchOrders();
6}

讀者想知道資料來源細節可跳轉到 IOnlineOrderService；不想知道可跳過。註解的認知依賴和程式的依賴方向一致（介面 → 服務命名引用，不反向揭露實作）。

同理適用範圍

例外：當行為細節本身就是契約的一部分時（例如「保證冪等」「保證依序處理」「保證不阻塞」），這些細節就是契約，必須寫在 doc 中。關鍵判斷：消費端會因此細節而改變使用方式嗎？是 → 寫進 doc；否 → 留給實作層。

原則四：可查詢性 × 註解

註解的關鍵字設計讓 grep / AI 能定位。 當維護者搜尋「哪個函式處理書籍狀態轉換」時，註解應包含讓搜尋命中的詞彙。

關鍵字設計建議

正例

1/// 【需求】UC-006 借閱到期提醒
2/// 【事件】ReminderTriggeredEvent 消費端
3/// 當借閱書籍距離到期日 < 3 天時觸發提醒。
4/// 【約束】同一本書 24 小時內只提醒一次（由 ReminderDebouncer 處理）
5/// 【維護】修改提醒閾值需同步更新 ReminderDebouncer.windowHours
6Future<void> sendDueReminder(Loan loan) { /* ... */ }

搜尋「到期提醒」、「ReminderTriggeredEvent」、「ReminderDebouncer」都能命中；【事件】 標記讓過濾所有事件消費端變可能。

反例

1/// 檢查並處理到期相關的事情
2Future<void> sendDueReminder(Loan loan) { /* ... */ }

「相關的事情」是語意黑洞，grep 搜尋業務詞彙無法命中。

分隔符規範

使用一致的分隔符讓結構可被 regex 解析：

• 【XXX】 全形方括號：語義標記（需求、事件、約束、維護、相依）
• [ModuleName] 半形方括號：類別 / 模組命名引用（可被 LSP 跳轉）
• UC-XXX、BR-XXX、#section：索引格式固定，便於全專案統一搜尋

原則五：欄位設計 × 註解（不同抽象層的註解寫法）

不同抽象層的註解寫法不同——這是「欄位設計精神」在註解的應用：同一概念在不同位置用不同角度描述，避免重複。

抽象層級對照表

正例：同一業務概念的多層寫法

 1// 介面層：只寫契約
 2abstract class OrderSearcher {
 3  /// 【需求】UC-004 訂單查詢
 4  /// 依關鍵字搜尋訂單。結果按建立時間新到舊排序。
 5  /// 無結果回傳空陣列（不拋例外）。
 6  Future<List<Order>> searchByKeyword(String keyword);
 7}
 8
 9// 實作層：解釋策略選擇
10class DbOrderSearcher implements OrderSearcher {
11  /// 【需求】UC-004 訂單查詢
12  /// 使用資料庫全文索引（非記憶體 filter），因訂單量可能達十萬級。
13  /// 【相依】[FullTextIndex]
14  @override
15  Future<List<Order>> searchByKeyword(String keyword) async {
16    // ... 實作
17    // 先 normalize 輸入（小寫 + 移除標點），否則索引無法命中
18    final normalized = _normalize(keyword);
19    // ... 查詢
20  }
21}

• 介面註解：讀者想知道契約即足夠
• 實作註解：讀者想知道「為什麼用 DB 不用記憶體」
• Inline 註解：讀者想知道「這行 normalize 為什麼不可刪」

三處註解從不同角度描述同一業務概念，不重複。

反例：三層寫相同內容

 1abstract class OrderSearcher {
 2  /// 使用資料庫全文索引搜尋訂單，依建立時間排序
 3  Future<List<Order>> searchByKeyword(String keyword);
 4}
 5
 6class DbOrderSearcher implements OrderSearcher {
 7  /// 使用資料庫全文索引搜尋訂單，依建立時間排序
 8  Future<List<Order>> searchByKeyword(String keyword) async {
 9    // 使用資料庫全文索引搜尋訂單，依建立時間排序
10    // ...
11  }
12}

介面洩漏實作（違反原則 3.4）、三層內容重複（違反 DRY）、實作沒解釋策略選擇（讀者看不到「為什麼用 DB」）。

禁止模式清單

以下註解模式禁止使用，CR 時應要求修改：

自檢清單（寫完註解問自己）

• 這則註解描述的是業務問題還是語法選擇？（若是後者，刪除或改寫）
• 若這是 doc comment，讀者不看實作能理解契約嗎？
• 若這是介面註解，有洩漏任何「目前實作用什麼」嗎？
• 註解包含 TODO / placeholder / 暫時 嗎？（若是，移到 inline + ticket）
• 一則註解只解釋一個概念嗎？（若不是，拆函式）
• 有需求索引（UC/BR）讓閱讀者能回溯嗎？
• 關鍵字設計讓 grep / AI 能找到嗎？（業務詞彙而非通用詞彙）
• 註解貼合所在抽象層嗎？（介面寫契約、實作寫策略、inline 寫決策）

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

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

註解用的核心三輪 + 兩輪程式碼專屬：

Naming 子場景：四輪 review（naming-as-iterated-artifact）

註解寫完該 review 一次「這段程式碼涉及的命名」。命名是 iterated artifact、第一版幾乎不對：

跳輪規則：

• Loop counter / close-up var：跑輪 1
• Test code 內部 helper：1 + 4
• 跨 team API / DB schema：每輪都跑、跑兩遍
• Production-facing URL / endpoint：不可跳

詳見 naming-as-iterated-artifact。

常見意外場景

場景 1：改 bug 時順手改壞註解

修 bug 改了實作，忘記檢查 doc 是否仍成立。SOP：改實作前先讀 doc comment；改完後回檢「doc 描述是否仍準確」。若契約變了，doc 必須同步修。

場景 2：抄別的函式的 doc comment

抄來的 doc 描述可能來自另一個業務情境。SOP：抄完後必須重寫需求索引和業務描述，確認「這個函式解決的問題」與原函式相同才能保留 doc。

場景 3：用 AI 產生 doc comment

AI 傾向產生「語法翻譯式」註解（使用 while 因為…）。SOP：AI 產出後必須人工審查，把「語法理由」全刪，補「業務理由」。

場景 4：介面加新方法時 copy 實作的 doc

實作的 doc 可能包含策略細節，直接 copy 到介面會洩漏實作。SOP：新增介面方法時，只保留契約描述部分（做什麼、輸入輸出、使用情境），刪除策略細節（用什麼演算法、為什麼用 DB）。

回顧總結

寫合格的註解是讓每個維護者（包括你自己三個月後）能在最短時間內理解業務意圖、避免破壞設計、安全地擴展功能。

Situation: You are about to compose any markdown document — worklog, README, spec, methodology, error-pattern record, or ticket — where both human cognitive load and downstream AI token consumption matter.

Before You Start: Identify Document Type

Different document types have different readers, lifespans, and structural demands. Pick the type first; the rest of this reference applies the five compositional principles to each.

Two rules follow from the table:

1. High-volatility documents (worklog, ticket) must stay append-only; rewriting history breaks the record.
2. Permanent documents (methodology, error-pattern, spec) must be distilled; every paragraph earns its keep.

Principle 1 — Atomization × Documents: Section granularity and when to split

Core question

How much content belongs in a single file, and when do you cut?

Decision table

Split heuristics by document type

• Worklog: Stays single per version. Append chronologically. Do not split by Wave unless the file exceeds ~2000 lines (rare).
• README: Always single file per directory. Route outward via links; do not fork README for sub-topics.
• Spec: Split by use case (one UC per file). Do not bundle multiple UCs for “efficiency”.
• Methodology: One methodology per file. If a second concept appears, it is a second methodology.
• Error-pattern: One pattern per file. Multiple root causes → multiple files, cross-linked.
• Ticket: One ticket per file is the atomic contract. Splitting a ticket means creating child tickets, not subdividing the file.

Anti-patterns

Principle 2 — Indexing × Documents: MOC, directory structure, cross-document references

Core question

Given many atomic documents, how does a reader find the right one?

Three indexing mechanisms

1. Directory layout — the physical grouping implies a taxonomy. Keep depths shallow (≤ 3 levels); deeper trees hide documents.
2. MOC (Map of Content) — a landing document that lists siblings with one-line summaries. Every directory with more than 5 documents earns an MOC (README.md or index.md).
3. Inline cross-reference — when one document must point to another, use a stable relative path and describe why the reader should click, not just that they can.

Cross-reference format

A reference without intent (“see X.md”) is a broken signpost. Always say what the reader gains by clicking.

Reference anchors: semantic titles, not positional numbers

引用另一個章節 / 階段 / 條列項時、錨點用語意標題、不用位置編號（「見核心問題」、不是「見 Stage 3」；「如『底線告知協議』所述」、不是「如第 4 點」）。編號是結構排列的 derivation — 插入或搬移一個單位、後續編號全部位移、引用句字面完好、語意卻 silent 指向錯的內容（misdirected 比 broken link 難偵測：連結斷掉會報錯、編號錯位會成功解析到錯的東西）。對應要求：每個結構單位的標題要承載核心意義（「Stage 3：核心問題」、編號只是排序前綴）、引用一律取語意半邊。例外是發布方凍結的編號（RFC 段號、法條）— 那是 fact、可引用。重排結構的 commit 要全 repo 掃編號式引用。完整判準與失效案例見 reference-by-semantic-title-not-number。

標題要能當穩定錨、名稱本身得先是純 fact：集合命名（問題清單 / 階段序列 / 原則組）只承載角色與層級、把成員數量留給清單呈現 —「核心七問」加一問就在每個複製過名稱的地方失真、「核心問題」承受任意成員增減。判準與邊界（外部凍結品牌 / 概念閾值可留數字）見 name-collections-by-role-not-count。

Indexing by document type

• Worklog: The worklog itself is an index of tickets. Each ticket row points into a detail file.
• README: Is the MOC for its directory. Must list every sibling one-line.
• Spec: Indexed by use case ID. Use cases form a flat catalogue; requirements nest under them.
• Methodology: Indexed by methodologies/README.md. Methodologies do not cross-reference methodologies-of-methodologies; keep one hop deep.
• Error-pattern: Indexed by a stable ID prefix scheme (e.g. category abbreviation + running number). The ID itself is the index key.
• Ticket: Indexed by worklog + ticket track list. CLI is the primary index, not a markdown TOC.

Anti-patterns