tarrragon/compositional-writing

Compositional Writing

以 Zettelkasten（卡片盒筆記法）為核心的寫作方法論。將每段文字視為可重複組合的原子卡片，讓人類讀者與 AI 代理人都能以最小認知負擔找到答案。

---

Core Pillars（三大支柱）

| 支柱 | 意義 | | -------------------------------------- | ---------------------------------------------------------- | | Atomization 原子化 | 一段文字只承載一個概念，可獨立閱讀與重用 | | Explicit Intent 意圖顯性與層級貼合 | 讀者第一眼就看懂「為什麼在這裡、屬哪個抽象層級、該做什麼」 | | Searchability 可查詢性 | 人和 AI 都能用關鍵字 / grep / regex 快速定位 |

---

Six Principles（六大原則速查）

讀者能在本區塊完成快速複習；需要具體應用時，依下方「觸發路由」讀對應情境 reference。

1. 原子化（Atomization）

一張卡一個概念：能獨立理解、可跨情境重用。拆分依據是認知負擔與情境匹配度 — 讀者要同時記住的概念數、以及這張卡是否符合讀者當下的情境需求。常見的誤判依據是「行數」（卡太長就拆）、行數只反映表面字數、不反映概念數：一張 200 行的卡可能只講一個概念、一張 30 行的卡可能塞了三個概念。判別問題是「讀者要同時 hold 幾個概念才讀得懂這張卡」、超過 7 個就要拆。

拆分判準的核心問題：「這張卡聚焦在什麼問題、議題切完整了嗎？」— 判準是 focus 完整度。常見的次級訊號是「卡之間是否衝突」「邊界是否清晰」、兩者都不夠：兩張卡互不衝突、仍可能各切了一半同樣議題；一張卡邊界清晰、仍可能塞了兩個獨立議題。focus 完整度問的是「這張卡有沒有把它聲稱要解決的議題講完」、是 contrast 上面那兩個訊號抓不到的死角。

2. 索引建立（Indexing）

用 MOC（Map of Content）、tag 層級與反向索引把卡片串成可導航的網。入口文件只做路由、把細節留給目標卡；引用深度最多一層、讓讀者一跳就到答案（避免 A→B→C 的多層跳躍）。

3. 意圖顯性與層級貼合（Explicit Intent & Layer Alignment）

寫作前先標記本文所在抽象層級（實作 / 工具 / 協作 / 認知 / 架構）、論述停在該層。素材取自哪個層級、論述就收斂在哪個層級 — 因為跨層提升等於用 X 層的詞彙描述 Y 層的議題、讀者拿到規則但對不到自己當下的情境。要把實作層素材抽象到認知層、先補對應抽象層的支撐文件（讓論述有對應層的詞彙跟 case 可引用）、再做跨層提升。

寫「為什麼」和「要達成什麼」、把「程式碼在做什麼」留給程式碼自身（程式碼讀一次就知道做什麼、寫進註解只是冗餘）。主詞與動詞直接、段落開頭即表達意圖。TODO / placeholder 留給 inline 註解、文件本體只放當前契約 — 因為文件常被當成「契約 SSoT」引用、混入未完成事項會讓讀者誤判契約範圍。同一篇文字貼合它在系統裡的抽象層級、把下層實作藏在介面後面。

機會成本語氣優先：程式設計大多是多目標取捨、討論的是「在什麼情境下哪個選項較划算」。把絕對二元語氣（「正確概念是 X / 替代方案不足 / 應該這樣做」）翻成情境化敘述：「比較好的做法是 A、因為 [情境] / B 在 [其他情境] 合理 / D 的成本特別高、只在 [極端情境] 才划算」。機會成本教讀者「思考方式」（能套用到新情境）、絕對主義教讀者「規則」（壓力下會忘）— 所以前者是預設語氣。例外保留給物理 / 法律事實（安全性、數據完整性、合規）。

選項數由議題本身的合理選項數決定：機會成本的精神是「教思考方式」 — 議題有幾個合理選項就寫幾個（2 個寫 A/B、3 個寫 A/B/C、4 個寫 A/B/C/D）。強湊到固定數量會把「教思考」退化成「填格式」、生出「實務上幾乎不存在」的低品質假反模式。真正的反模式直接標「D：反模式 — 違反 X 原則」、給讀者明確的「為什麼這條路該避開」、保持誠實。

Case 引用段落的三段式結構：三段式是案例引用段落的順序紀律 — 把「概念 → 案例 → 操作」三層分開承擔（段首給概念定義、case 引用居中、通用工程知識展開）、讓段落結構跟讀者學習新概念的認知順序對齊。LLM 從 case 反推內容容易把 case 揭露當概念出發點、實證觀察 11/12 段都犯這個錯。詳見 case-citation-three-part-structure。

4. 可查詢性（Searchability）

關鍵字前置、使用可 grep 的分隔符（: | → ==）、欄位名稱使用 regex 友善格式。命名讓 AI 能以單次 grep 命中，不需要語意推理。

5. 欄位設計（Field Design）

同一份文件的不同欄位，從不同角度觀察同一件事，不重複撰寫。what 描述動作、why 陳述動機、acceptance 定義可驗證條件；混淆欄位會讓讀者在多處讀到相同內容。

6. 多輪 Re-read Pass（Multi-pass Review）

寫完不是 done — 是進入 review 階段。一次寫對全部維度違反 working memory、實際結果是「每維度都做一半」。設計 N 輪 re-read、每輪用不同 frame：

| 輪 | Frame | 抓什麼 | | --- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | 1 | 生成 | idea → 字、預期會有錯 | | 2 | 對意圖（ease-of-writing-vs-intent-alignment） | 正文、title、description、MOC hook 都跟原意對齊 | | 3 | 機會成本語氣 | 全 surface 的絕對詞翻成 trade-off | | 4 | Grep-ability / 命名 / 術語 | title、slug、link label、段首關鍵字可單次 grep 命中；術語保留原文錨點與完整名詞頭 | | 5 | 反例 / 邊界 | 「何時不適用」段、反模式列表 |

Surface enumeration 是 multi-pass 的固定前置步驟。寫作產物包含 body surface 與 metadata / navigation surface：title、description、tags、heading、link label、MOC / index entry、slug / filename。每輪 frame 都掃這份 surface 清單，讓正文與讀者入口共用同一個概念錨點。

核心：「再仔細一次」≠ multi-pass — 同 frame 重看 catch 不到新問題。每輪換 frame、才能 catch 不同層。各 reference（writing-articles / writing-code-comments / writing-documents / writing-prompts）依 output 類型有特化的輪次組合。

Naming 是這條原則最容易跳的子場景 — 第一版命名幾乎不對、四輪 review（第一版 / grep / cross-call-site / impl 洩漏）才收斂、見 naming-as-iterated-artifact 跟 writing-code-comments 的 naming review 段。術語是 naming 的高歧義子場景：翻譯術語第一次出現保留原文錨點，中文壓縮術語保留完整名詞頭，中文名詞頭要保留來源中的概念角色，見 terminology-keeps-original-anchor、compressed-chinese-terms-need-head-noun 與 translation-must-preserve-concept-role。

高 stakes 內容追加輪 E（epistemic rigor、conditional opt-in）：reader 照做後錯誤不可逆的內容（資安 / concurrency 正確性 / distributed consistency / financial / medical）在 5 輪基本 frame 之外、追加 stakes 軸的 epistemic rigor pass——比照學術 peer review 跑 claim / evidence / method / threats / citation 五個 sub-check、加上 audit recommendation tier（accept / minor / major / withdraw）。一般內容 5 輪夠、不跑輪 E；高 stakes 內容兩軸都跑。詳見 references/auditing-articles.md 跟 references/principles/writing-multi-pass-review.md 的「stakes-conditional 追加輪」段。

Production 教學文章追加輪 8-10（字句層 catch、跑 N 輪仍漏時觸發）：跑了 5 輪基本 frame 仍系統性漏 catch 字句層問題（口語修辭 / 廢話前綴 / 地區漂移 / 依賴 code）時、追加三個換軸機制——輪 8 keyword bank（換工具）、輪 9 reader simulation（換視角）、輪 10 self-criticism（換層次、審視 framework 本身覆蓋度）。短文 / 即時 note 不需要、production 教學文章在跑 5 輪後仍漏同類問題時 opt-in。詳見 multi-pass-review-frame-granularity 跟 references/writing-articles.md 輪 8-10 段。

Instance 軸：跨 reviewer instance 隔離：Instance 軸是 multi-pass review 的另一條擴展軸 — N 個獨立 reviewer instance 各自獨立 context、各自跑 background、解「單一 reviewer 同時看多維度容易維度盲點 + context 污染」的問題。Instance 指獨立 reviewer 程式實體（如 agent tool spawn 出的 subagent）、跟同一 reviewer 換輪次 frame（frame 軸）正交可疊加。適用 production 教學文章 / 高 stakes 內容 / 跨章節教學模組這類維度複雜度高的審查場景。詳見 agent-team-context-isolation。

詳見 Writing 的 multi-pass review、Methodology 的 multi-pass 該 embed 在 pillar、Metadata surface 要納入寫作 review 範圍、False sense of security 是高 stakes 寫作的主要失敗模式、Risk-asymmetric audit standard、colloquial-rhetoric-erodes-technical-precision、prose-self-contained-without-code-reference、regional-terminology-alignment、multi-pass-review-frame-granularity、design-flaw-by-current-axes-not-hindsight、agent-team-context-isolation。

---

When to Consult This Skill（觸發路由）

| 觸發情境 | 讀哪份 reference | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | 要寫或改一段程式碼註解 / doc comment | references/writing-code-comments.md | | 要起草 / 改寫一份文件（worklog、spec、README） | references/writing-documents.md | | 要設計 log / 錯誤訊息 / 結構化輸出 | references/writing-logs.md | | 要撰寫給 AI 的 prompt / instruction / Agent 派發 / Ticket Context Bundle | references/writing-prompts.md（為 .claude/rules/core/ai-communication-rules.md 的詳細版庫，portability-allow） | | 要撰寫完整長篇技術文章（blog post / post-mortem / 架構決策 / 除錯復盤 / 技術評估） | references/writing-articles.md | | 要翻譯 / 轉譯文章、把英文材料改寫成中文、檢查術語誤譯或中文譯名放回句子後是否成立 | references/translation-review.md | | 要管理多篇相關文章的結構（系列、文集、知識庫、素材庫比例、MOC、跨篇引用、何時抽抽象層 / Pattern 卡片） | references/managing-article-collections.md | | 要對既有高 stakes 內容（資安 / concurrency / distributed / financial / medical）做 reviewer-style audit、找 false sense of security / 對位失效 / context 缺 / citation 過時 | references/auditing-articles.md | | 要設計 ticket 欄位 / schema frontmatter / 表單欄位 | references/designing-fields.md | | 想驗證寫作品質（認知負擔、獨立理解率） | references/meta-metrics.md | | 要新增或修改一份 Skill reference（撰寫品質規範、結構標準） | references/reference-authoring-standards.md | | 要驗收 Skill 發布品質（語意層驗收、Phase 2 dry-run） | references/dry-run-guide.md |

每份 reference 自包含：以該情境為核心，把六大原則翻譯成可直接套用的檢查項與範例。閱讀任一 reference 不需要回來看其他 reference。

---

Success Criteria（M1-M2 認知負擔類）

| Metric | 定義 | 目標 | | ----------------------------- | ----------------------------------------------------- | ---- | | M1 — 找到答案路徑 | 讀者從 SKILL.md 出發，需要開啟幾個檔案才能解決問題 | ≤ 2 | | M2 — reference 獨立理解率 | 隨機挑一份 reference，不讀其他 reference 能否獨立套用 | 100% |

詳細量測方式與自評表見 references/meta-metrics.md。M3-M5（token 類）保留未定，待實際範例累積後補足。

---

跟特化寫作流程的分工

本 skill 是 單篇 寫作的基礎方法、覆蓋 articles / comments / logs / prompts / fields 五大 surface。當寫作對象是 跨多章節的教學模組（5+ 章、有案例庫支撐、跨章引用密集）、屬特化情境、有專屬的 跨章節生產流程：案例庫 audit 抽 findings、SSoT 對應規劃、agent team 平行 review、跨檔修正循環、跨章 polish pass。

兩類流程的分工：

| 流程 | 適用 | 核心紀律 | | ------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | 本 skill（compositional-writing） | 單篇文字（articles / comments / logs / prompts / fields） | 6 原則（原子化 / 索引 / 意圖顯性 / 可查詢 / 欄位 / 多輪 review）+ 各 surface 特化 reference | | 跨章節教學模組生產流程 | 跨 5+ 章、有 case 庫的教學模組 | 五階段流程：案例 audit → 基於 findings 寫稿 → agent team 平行 review → 修正循環 → polish pass、加 case 引用四 axis 紀律（深度 / 分層 / 合成 / 結構） |

兩類流程互補疊加 — 教學模組的每章內部寫作仍套本 skill 6 原則、case 引用段落用 case-citation-three-part-structure、agent team review 用 agent-team-context-isolation。當下游專案沒有跨章節教學模組需求、本 skill 即可獨立運作；當有需求、教學模組生產流程是本 skill 的擴展層、不取代本 skill。

---

Directory Index

compositional-writing/
├── SKILL.md                              # 本檔：六大原則速查 + 觸發路由
└── references/
    ├── writing-code-comments.md          # 情境 1：程式碼註解
    ├── writing-documents.md              # 情境 2：文件撰寫
    ├── writing-logs.md                   # 情境 3：log 輸出
    ├── writing-prompts.md                # 情境 4：prompt 撰寫
    ├── writing-articles.md               # 情境 5：完整長篇技術文章
    ├── translation-review.md             # 情境 5a：文章翻譯 / 轉譯的句內邏輯 review
    ├── managing-article-collections.md   # 情境 5b：跨多篇文章的結構（三層、素材庫比例、MOC、Pattern 卡片）
    ├── designing-fields.md               # 情境 6：欄位設計（含六欄位角度總表）
    ├── designing-fields-ticket-6w.md     # 六欄位詳細範例：正確 + 混淆共 12 項（按需讀取）
    ├── meta-metrics.md                   # 品質量化驗收（M1-M5）
    ├── reference-authoring-standards.md  # Skill reference 撰寫品質規範
    ├── dry-run-guide.md                  # Skill 發布前語意層驗收（Phase 2 dry-run 流程）
    └── principles/                       # Skill 內部支撐型原則卡（含 terminology / naming / review / case-citation / agent-team 等原則）

---

Reading Order（建議閱讀順序）

1. 第一次接觸 → 從本 SKILL.md 的「三大支柱 + 六大原則」讀起
2. 進入實際寫作情境 → 依觸發路由讀對應 reference（只讀一份）
3. 想驗證成果 → 讀 meta-metrics.md 做自評

---

Last Updated: 2026-05-13 Version: 0.9.1 — Stage 4 修正 3-reviewer 抓的 33 issue：(1) #120 mirror 縮 scope 解過載（移除四 axis 表 / 句構分流 / polish pass 段、聚焦三段式結構 axis）+ 結論段首改概念定義句解 dogfooding 失敗；(2) #121 mirror 結論表三欄重設計（設計選擇 / 解決問題 / 失敗模式）+ 實作 pattern 縮成 abstract pattern；(3) 兩 mirror 角色段引用點改措辭（移除虛假引用宣告）；(4) SKILL.md 原則 3/6 兩補強段段首改概念定義句、原則 6「詳見」list 補新 mirror、Directory Index 補；(5) Portability leak 修：「Stage 2 自查清單」→「寫稿後段落自查清單」、「Stage 1-5」→「五階段流程」；(6) 五大 / 六大原則 drift 對齊（line 105 / 160）；(7) 既有 principles（writing-multi-pass-review / multi-pass-review-frame-granularity / ease-of-writing-vs-intent-alignment）補回引新 mirror、形成雙向 cross-link Version: 0.9.0 — 從跨章節教學模組生產經驗回流：原則 3 補「Case 引用段落三段式結構」段（詳見 case-citation-three-part-structure）；原則 6 補「Instance 軸：跨 reviewer instance 隔離」段（詳見 agent-team-context-isolation、跟 frame 軸正交可疊加）；新增「跟特化寫作流程的分工」段（明示本 skill 是單篇基礎方法、跨章節教學模組生產流程是擴展層）；principles/ 新增兩張 mirror 卡（case-citation-three-part-structure / agent-team-context-isolation）、自包含、不引用外部 skill 或 blog content Version: 0.8.1 — 第 6 原則同步 writing-articles v0.8.1：補「Production 教學文章追加輪 8-10」段（換工具 / 換視角 / 換層次三機制處理「跑 N 輪仍漏」字句層問題）；「詳見」連結加 5 張新 principle（colloquial-rhetoric / prose-self-contained / regional-terminology / multi-pass-review-frame-granularity / design-flaw-by-current-axes） Version: 0.7.4 — 新增 translation-review.md 路由：翻譯 / 轉譯文章時，用句內邏輯檢查譯名是否跟主詞、動詞、修飾語、因果與讀者追問方向對位。 Version: 0.7.3 — managing-article-collections 補「素材庫比例」路由：多篇文章需要案例 / source / scenario / pattern 支撐時，主文章情境維持少量、素材庫保留 2-3 倍來源做反向驗證 Version: 0.7.2 — 補 multi-pass 的 surface 軸：review 先列 body / metadata / navigation surface（title、description、tags、heading、link label、MOC hook、slug / filename），每輪 frame 都掃同一份 surface 清單；新增內部 principle metadata-surface-in-writing-review.md Version: 0.7.0 — Phase B1 結構升級：加第 6 原則「多輪 Re-read Pass」（明示 5 輪 frame）、引用 #83 / #84 / #85 multi-pass 系列。後續 Phase B2 會把各 reference 結尾加「第 2 輪 review checklist」段 Version: 0.6.0 — 從 references 過載的反思：writing-articles.md 從 780 行瘦身到 ~530 行（拆分判準 / 三類 structure 模板搬到 managing-article-collections.md、focus 集中在「單篇文章內部」）；新增規則八「自我應用 (dogfooding)」（教某條規則的段落本身遵守該規則）；managing-article-collections.md 整合「拆分判準」+「三層 structure 詳細對照 + 模板」；meta-metrics.md M2 加 dogfooding 失敗訊號 Version: 0.5.0 — 從批量改寫 35 篇的經驗回流：原則 3 補「選項數由議題決定、不強湊」（避免 A/B/C/D 強迫症與「實務上幾乎不存在」的假反模式）；writing-articles.md 新增規則九（三類文章 structure 模板）；managing-article-collections.md 新增「跨篇引用 idiom 庫」與「三層 structure 對照」 Version: 0.4.0 — 新增 managing-article-collections.md（跨多篇文章結構：三層、MOC、Pattern 卡片）；強化原則 1「原子化」（focus 是議題完整度、不是邊界清晰）；強化原則 3「意圖顯性」（機會成本語氣、不用絕對主義） Version: 0.3.0 — 新增 dry-run-guide.md 於 Directory Index 與觸發路由（Skill 發布前語意層驗收 Phase 2 dry-run）