Episode Details

Claude Code 工作流的文件選 md 或 html，別再選邊。@the_smart_ape 提了三個問題：受眾、生命週期、時間視野。再做 30 秒可逆性測試，多數文件其實想當 markdown。

⭐ 文章深度讀：完整拆解了 Claude Code 工作流的格式決策框架
→ https://heymaibao.com/smart-ape-md-html-format-framework/

⚡ 章節重點
別再吵 md 還是 html，問三個問題就好 00:00
三個問題的決策框架 00:51
第 1 題 受眾：Claude 才是真正的讀者 01:35
第 2 題 編幾次：標籤飄移的隱性腐爛 03:33
第 3 題 活多久：grep 與 3 年存活測試 05:36
真正的 wedge：一份 md，多種 html 視圖 06:13
30 秒可逆性測試與三個合理例外 06:48

📝 懶人包
∙ md vs html 是錯題目。對的問題是 audience (誰來讀)、lifecycle (要編幾次)、horizon (活多久)。三個問題的答案如果一致，格式自動勝出；如果分裂，就走 hybrid。

∙ Claude 會反覆讀回自己寫的文件。html 在 token 成本 (約 3 倍)、retrieval 切 chunk (相關性下降 15-25%)、編輯 diff (5 行對 40-100 行) 三個維度同時懲罰你，這些都是 @the_smart_ape 自己測出來的數字。

∙ 真正帶得走的招式是 hybrid：一份 md 當 source of truth，按受眾用 10 行 script 生成多個 html view。md 留長壽性，html 做呈現工作，source of truth 永遠是文字。

∙ 我的觀點：多數 Claude Code 工作流的文件其實想當 markdown，html 反而是少數例外。下次想用 html 之前，先做 30 秒可逆性測試，能擋掉 90% 的格式誤判。

📚 參考資料
md or html? — @the_smart_ape on X
→ https://x.com/the_smart_ape/status/2053034897514660074