Zettelkasten on Tarragonhttps://tarrragon.github.io/blog/tags/zettelkasten/Recent content in Zettelkasten on TarragonHugo -- gohugo.iozh-TWTarragon (CC BY 4.0)Sat, 25 Apr 2026 00:00:00 +0000Compositional Writing — 組合式寫作方法論https://tarrragon.github.io/blog/skills/compositional-writing/Sat, 25 Apr 2026 00:00:00 +0000https://tarrragon.github.io/blog/skills/compositional-writing/<h2 id="這個資料夾是什麼">這個資料夾是什麼</h2> <p><code>compositional-writing</code> 是一套寫作方法論 skill，原生位置在 <a href="https://github.com/tarrragon/blog/tree/main/.claude/skills/compositional-writing"><code>.claude/skills/compositional-writing/</code></a> 供 Claude runtime 呼叫；這份是<strong>同內容的文章版本</strong>，讓人類讀者也能直接在 blog 閱讀。</p> <p>核心是把寫作看成「原子卡片組合」：每段文字只承載一個概念、可獨立閱讀、可跨情境重用。適用情境涵蓋程式碼註解、文件、log、prompt、欄位設計、完整長篇技術文章與外部分析材料轉教學文章。</p> <h2 id="閱讀順序">閱讀順序</h2> <h3 id="場景-1第一次接觸">場景 1：第一次接觸</h3> <table> <thead> <tr> <th>順序</th> <th>檔案</th> <th>目的</th> </tr> </thead> <tbody> <tr> <td>1</td> <td><a href="https://tarrragon.github.io/blog/skills/compositional-writing/skill/" data-link-title="Compositional Writing" data-link-desc="Composes atomic, intent-revealing, grep-friendly writing (Zettelkasten) for code comments, docs, log">SKILL.md</a></td> <td>核心支柱 + 核心原則速查、觸發路由</td> </tr> <tr> <td>2</td> <td>依情境挑一份 reference（見下表）</td> <td>把原則翻譯成可套用的檢查項與範例</td> </tr> <tr> <td>3</td> <td><a href="https://tarrragon.github.io/blog/skills/compositional-writing/meta-metrics/" data-link-title="Meta Metrics — 寫作品質量化驗收" data-link-desc="compositional-writing reference：M1–M5 指標定義、量測方式、自評表。">meta-metrics.md</a></td> <td>用 M1–M2 自評寫作成果</td> </tr> </tbody> </table> <h3 id="場景-2已熟悉原則想直接解決當前任務">場景 2：已熟悉原則、想直接解決當前任務</h3> <p>直接依觸發情境跳對應 reference：</p> <table> <thead> <tr> <th>觸發情境</th> <th>reference</th> </tr> </thead> <tbody> <tr> <td>要寫或改一段程式碼註解 / doc comment</td> <td><a href="https://tarrragon.github.io/blog/skills/compositional-writing/writing-code-comments/" data-link-title="Writing Code Comments — 程式碼註解撰寫指引" data-link-desc="compositional-writing reference：將核心原則翻譯成程式碼註解 / doc comment 的具體檢查項與範例。">writing-code-comments</a></td> </tr> <tr> <td>要起草 / 改寫一份文件（worklog、spec、README）</td> <td><a href="https://tarrragon.github.io/blog/skills/compositional-writing/writing-documents/" data-link-title="Writing Documents — 文件撰寫指引" data-link-desc="compositional-writing reference：worklog、spec、README 等文件起草與改寫。">writing-documents</a></td> </tr> <tr> <td>要設計 log / 錯誤訊息 / 結構化輸出</td> <td><a href="https://tarrragon.github.io/blog/skills/compositional-writing/writing-logs/" data-link-title="Writing Logs — log 與結構化輸出撰寫指引" data-link-desc="compositional-writing reference：log / 錯誤訊息 / 結構化輸出的欄位設計與措辭。">writing-logs</a></td> </tr> <tr> <td>要撰寫給 AI 的 prompt / instruction</td> <td><a href="https://tarrragon.github.io/blog/skills/compositional-writing/writing-prompts/" data-link-title="Writing Prompts — AI prompt / instruction 撰寫指引" data-link-desc="compositional-writing reference：prompt / Agent 派發 / Ticket Context Bundle 的撰寫規範。">writing-prompts</a></td> </tr> <tr> <td>要撰寫完整長篇技術文章</td> <td><a href="https://tarrragon.github.io/blog/skills/compositional-writing/writing-articles/" data-link-title="Writing Articles — 完整長篇技術文章撰寫指引" data-link-desc="compositional-writing reference：blog post、post-mortem、架構決策、除錯復盤等需要保留思考過程的長篇內容。">writing-articles</a></td> </tr> <tr> <td>要把外部分析材料轉成教學型分析文章</td> <td><a href="https://tarrragon.github.io/blog/skills/compositional-writing/source-to-teaching-analysis/" data-link-title="Source to Teaching Analysis — 外部分析材料轉教學文章" data-link-desc="compositional-writing reference：把分析師文章、投資人備忘錄、產業評論、研究摘要或 AI 轉寫稿，轉成讀者可重用的教學型分析文章。">source-to-teaching-analysis</a></td> </tr> <tr> <td>要管理多篇相關文章的結構（系列、文集、知識庫）</td> <td><a href="https://tarrragon.github.io/blog/skills/compositional-writing/managing-article-collections/" data-link-title="Managing Article Collections — 跨多篇相關文章的結構設計" data-link-desc="compositional-writing reference：跨多篇相關文章的結構設計（三層、素材庫比例、MOC、Pattern 卡片、跨篇引用 idiom）。">managing-article-collections</a></td> </tr> <tr> <td>要設計 ticket 欄位 / schema frontmatter</td> <td><a href="https://tarrragon.github.io/blog/skills/compositional-writing/designing-fields/" data-link-title="Designing Fields — 欄位設計指引" data-link-desc="compositional-writing reference：ticket 欄位、schema frontmatter、表單欄位的六欄位角度總表。">designing-fields</a></td> </tr> <tr> <td>六欄位範例詳查（正確 + 混淆對照）</td> <td><a href="https://tarrragon.github.io/blog/skills/compositional-writing/designing-fields-ticket-6w/" data-link-title="Designing Fields Ticket 6W — 六欄位詳細範例" data-link-desc="compositional-writing reference：正確 &#43; 混淆共 12 項的六欄位範例（搭配 designing-fields 按需閱讀）。">designing-fields-ticket-6w</a></td> </tr> <tr> <td>驗證寫作品質（認知負擔、獨立理解率）</td> <td><a href="https://tarrragon.github.io/blog/skills/compositional-writing/meta-metrics/" data-link-title="Meta Metrics — 寫作品質量化驗收" data-link-desc="compositional-writing reference：M1–M5 指標定義、量測方式、自評表。">meta-metrics</a></td> </tr> <tr> <td>新增或修改一份 Skill reference</td> <td><a href="https://tarrragon.github.io/blog/skills/compositional-writing/reference-authoring-standards/" data-link-title="Reference Authoring Standards — Skill reference 撰寫品質規範" data-link-desc="compositional-writing reference：新增或修改 Skill reference 的結構標準與撰寫品質規範。">reference-authoring-standards</a></td> </tr> <tr> <td>驗收 Skill 發布品質（dry-run）</td> <td><a href="https://tarrragon.github.io/blog/skills/compositional-writing/dry-run-guide/" data-link-title="Dry-run Guide — Skill 發布前語意層驗收" data-link-desc="compositional-writing reference：Phase 2 dry-run 流程 — 驗收 Skill 發布品質的語意層方法。">dry-run-guide</a></td> </tr> </tbody> </table> <p>每份 reference 自包含：讀任一份不需要回頭讀其他 reference。</p>這個資料夾是什麼

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

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

閱讀順序

場景 1：第一次接觸

順序 檔案 目的
1 SKILL.md 核心支柱 + 核心原則速查、觸發路由
2 依情境挑一份 reference（見下表） 把原則翻譯成可套用的檢查項與範例
3 meta-metrics.md 用 M1–M2 自評寫作成果

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

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

觸發情境 reference
要寫或改一段程式碼註解 / doc comment writing-code-comments
要起草 / 改寫一份文件（worklog、spec、README） writing-documents
要設計 log / 錯誤訊息 / 結構化輸出 writing-logs
要撰寫給 AI 的 prompt / instruction writing-prompts
要撰寫完整長篇技術文章 writing-articles
要把外部分析材料轉成教學型分析文章 source-to-teaching-analysis
要管理多篇相關文章的結構（系列、文集、知識庫） managing-article-collections
要設計 ticket 欄位 / schema frontmatter designing-fields
六欄位範例詳查（正確 + 混淆對照） designing-fields-ticket-6w
驗證寫作品質（認知負擔、獨立理解率） meta-metrics
新增或修改一份 Skill reference reference-authoring-standards
驗收 Skill 發布品質（dry-run） dry-run-guide

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

與 blog 專案其他資料的關係

位置 角色
.claude/skills/compositional-writing/ 實際 skill — Claude runtime 呼叫的檔案來源
content/skills/compositional-writing/（本處） 文章版本 — 人類讀者在 blog 閱讀
content/posts/markdown-writing-spec.md Blog 自己的 markdown 寫作規範（mdtools 檢查項目、與本 skill 並行）
content/posts/tech_writing_structure.md 長篇技術文章結構（writing-articles 的來源之一）

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 同步

]]>