小編精選 - 技術文章翻譯 · 05月12日

Claude Code 團隊工程師：我為什麼放棄 Markdown，全面轉向 HTML

> 作者：Thariq（@trq212）原文發表於 2026 年 5 月 9 日

Markdown 已經成為 AI agent 與我們溝通時的主流檔案格式。它簡潔、可攜，具備一定的富文字能力，而且便於編輯。Claude 甚至已經很擅長在 Markdown 檔案中用 ASCII 字元繪製圖表。

但隨著 agent 能力越來越強，我開始覺得 Markdown 變成了一種束縛。超過 100 行的 Markdown 檔案我讀起來就很吃力。我想要更豐富的視覺化效果——色彩、圖表，而且希望能輕鬆分享。

我也越來越少親自編輯這些檔案，而是把它們當作規格說明、參考文件、腦力激盪的產物。當我確實需要修改時，通常也是讓 Claude 來改，這就抹掉了 Markdown 最大的優勢之一。

我現在已經開始更傾向於把 HTML 作為輸出格式，而不是 Markdown。我也看到 Claude Code 團隊越來越多人這麼做。下面就說說為什麼。

如果你想直接看一些範例，可以造訪：thariqs.github.io/html-effect… 不過看完記得回來讀完原因部分。

為什麼選 HTML？

資訊密度

相比 Markdown，HTML 能承載的資訊要豐富得多。它當然能處理文件基本結構，比如標題和格式化文字，還能表達：

表格資料：透過 table
設計資料：透過 CSS
插圖：透過 SVG
程式碼片段：透過 script 標籤
互動：透過 HTML 元素 + JavaScript + CSS
工作流程：透過 SVG 和 HTML
空間資料：透過絕對定位和 canvas
圖片：透過 image 標籤

我甚至想說：幾乎所有 Claude 能讀懂的資訊，都可以用 HTML 有效率地表達出來。這讓 HTML 成為模型向你深入傳達資訊、以及你回顧這些資訊的高效媒介。

我發現，在沒有 HTML 時，模型會做一些 Markdown 裡效率很低的事情，比如畫 ASCII 圖，或者我最愛的——用 unicode 字元來近似呈現顏色（就像下面這張 Claude Code 的截圖）。

視覺清晰度與閱讀體驗

隨著 Claude 能完成的工作越來越複雜，它寫的規格說明和方案也越來越長。實際上我發現，自己很少會真的讀完一個超過 100 行的 Markdown 檔案，團隊裡其他人就更難指望了。

但 HTML 文件讀起來要輕鬆得多。Claude 可以在視覺上組織好結構，使用分頁、插圖、連結等使導航更直觀。它甚至可以做成響應式的，讓你在不同裝置上都有合適的閱讀體驗。

易於分享

Markdown 檔案不太好分享，因為大多數瀏覽器不能原生渲染它們。你常常需要把它作為附件加到郵件或訊息裡。

而 HTML 只要上傳一下（比如到 S3），就能直接分享連結。同事可以在任何地方打開它、隨時引用。

把規格說明、報告或 PR 描述寫成 HTML，別人真的會去讀的機率要高得多。

雙向互動

HTML 讓文件變得可互動。比如，你可以讓它加上滑桿和旋鈕來調整設計，或讓你嘗試演算法中不同選項產生的效果。你甚至可以讓它加一個按鈕，把這些改動複製成 prompt，再貼回 Claude Code。

更多關於這種雙向互動的例子，可以讀我那篇 playground 相關的貼文：x.com/trq212/stat…

資料接入

為什麼是用 Claude Code 來生成 HTML，而不是 ClaudeAI 或 Claude Design？最大的原因之一就是 Claude Code 能接入的上下文實在太豐富了。

舉個例子，寫這篇文章時，我讓 Claude Code 翻遍我的程式碼目錄，找出所有我生成過的 HTML 檔案，做分類整理，然後生成一個用圖表展示每種型別的 HTML 檔案。本文中那些圖表就是這麼來的。

除了檔案系統，Claude Code 還能透過你的 MCP（如 Slack、Linear 等）、瀏覽器（用 Claude in Chrome）、git 歷史等渠道取得上下文。

讓人愉悅

用 Claude 生成 HTML 文件這件事本身就更有趣，讓我感覺自己更深入地參與並投入到創造之中。光這一點，就足夠了。

如何開始

我有點擔心有人讀完這篇文章會去搞個 /html skill 之類的東西。雖然這或許有點價值，但我想強調：你幾乎不需要做什麼就能讓 Claude 這麼幹。直接說「做一個 HTML 檔案」或「做一個 HTML artifact」就行。

關鍵在於你知道自己想要這個 artifact 做什麼，以及怎麼用它。也許你以後會做一個 skill，但目前我建議你先從零開始 prompt，找找在不同場景下使用它的感覺。

使用案例

為了讓討論更具體，我做了大量不同用途的 HTML 檔案。完整範例可以看：thariqs.github.io/html-effect… 這裡我做個概覽。

規格說明、規劃與探索

HTML 是 Claude 深入剖析問題的豐富畫布。開始處理一個問題時，我不再是寫一個簡單的 Markdown 方案，而是期望生成一組 HTML 檔案構成的網路。

比如，我可能先讓 Claude Code 腦力激盪並探索一些不同方案；然後挑一個深入展開，做做原型或程式碼片段；最後覺得滿意了，讓它寫一份實施方案。當我對方案滿意後，開一個新對話，把這些檔案都傳進去讓它實施。

驗證階段，我也會讓驗證 agent 讀取這些檔案，它就能獲得更廣的上下文。

範例 Prompt：

我不確定該往哪個方向做導引介面。生成 6 種截然不同的方案——在版面、調性、資訊密度上都要有差異——把它們排成網格放在一個 HTML 檔案裡供我對比。每個都標注它在做什麼取捨。

寫一份詳盡的實施方案到一個 HTML 檔案裡，要包括一些原型圖、資料流，以及我可能想看的關鍵程式碼片段。讓它易讀易消化。

適用場景：

探索程式實作的不同方式
探索多種視覺設計方案

程式碼審查與理解

程式碼在 Markdown 檔案裡很難讀。但 HTML 可以渲染 diff、註解、流程圖、模組圖等。可以用它來理解 agent 寫的程式碼、做程式碼審查、或者向他人解釋你的 PR。我發現這經常比 GitHub 預設的 diff 檢視更好用，現在我每個 PR 都會附上一個 HTML 程式碼講解。

範例 Prompt：

幫我審查這個 PR，做一個 HTML artifact 來描述它。我對其中的串流／回壓邏輯不太熟，重點關注那部分。把 diff 渲染出來，在側邊欄加上行內註解，按嚴重程度給發現的問題著色，以及任何能更好表達概念所需的內容。

適用場景：

建立 PR
審查 PR
理解程式碼中的某個主題

設計與原型

Claude Design 是基於 HTML 的，因為 HTML 在表達設計方面非常有表現力，即使你最終的目標不是 HTML。Claude 可以先用 HTML 勾勒設計，然後再翻譯成你想用的語言——React、Swift 都行。

你也可以原型化互動，比如動畫、操作等等。可以讓 Claude 加上滑桿、旋鈕，方便你精細調出想要的效果。

範例 Prompt：

我想做一個新的結帳按鈕原型，點擊時先播放一個動畫然後快速變成紫色。做一個 HTML 檔案，提供多個滑桿和選項讓我嘗試這個動畫的不同效果，加一個複製按鈕讓我能複製效果好的參數。

適用場景：

建立設計系統 artifact
調整元件
視覺化元件庫
製作富有趣味的動畫原型

報告、研究與學習

Claude Code 非常擅長綜合多個資料來源的資訊，把它轉化為可讀性極強的報告。你可以讓 Claude 搜尋你的 Slack、程式碼庫、git 歷史、網際網路等等，生成給自己、給主管、給團隊看的報告。

可以做成長篇 HTML 文件、互動式講解，甚至投影片／簡報。讓 Claude 用 SVG 繪圖來輔助視覺化。

比如，寫關於 prompt caching 的貼文時，我讓 Claude 讀完 git 歷史後，準備了一份關於我們對 prompt caching 所做修改的深度 HTML 研究文件。

範例 Prompt：

我搞不懂我們的限流器到底是怎麼工作的。讀相關程式碼，輸出一個 HTML 講解頁：一張 token bucket 流程圖，3-4 段加註解的關鍵程式碼片段，底部加一個「易踩坑點」小節。優化為只讀一遍就能看懂的形式。

適用場景：

總結一個功能的工作原理
向我解釋一個概念
向老闆彙報每週狀態
向主管上報事故報告
SVG 插圖、流程圖、技術示意圖等

自訂編輯介面

有時候，純文字框很難描述清楚你想要的東西。這種情況下，我會讓 Claude 幫我做一個一次性的編輯器，專門針對我手頭這件事。不是產品，也不是可重用的工具——就是一個 HTML 檔案，專門為這一份資料服務。

訣竅永遠是：以一個匯出按鈕收尾——「複製為 JSON」或「複製為 prompt」，把我在 UI 中做的事變成可以貼回 Claude Code 的內容。

範例 Prompts：

我需要重新排序這 30 個 Linear 工單。做一個 HTML 檔案，每個工單是一張可拖曳的卡片，分布在 Now / Next / Later / Cut 四欄中。先按你的最佳猜測排好。加一個「複製為 markdown」按鈕，匯出最終排序，每一欄附一行簡短的理由。

這是我們的功能開關設定。給我做一個表單式編輯器：按領域分組，展示開關之間的依賴關係，如果我打開了一個開關但其前置開關是關閉的就發出警告。加一個「複製 diff」按鈕，只給我變更過的 key。

我在調一個系統 prompt。做一個並排編輯器：左邊是可編輯的 prompt，變數插槽要高亮；右邊是三個範例輸入，即時渲染填入後的模板。加一個字元/token 計數器和一個複製按鈕。

適用場景：