Markdown 已經成為 Agent 與我們溝通時最常用的檔案格式。它簡單、可攜、具備一定的富文本功能,而且方便你編輯。Claude 甚至在使用 ASCII 於 Markdown 檔案內繪製圖表方面,表現得出乎意料地好。
但隨着 Agent 變得越來越強大,我開始覺得 Markdown 變成了一種受限的格式。我發現要閱讀超過一百行的 Markdown 檔案相當吃力。我想要更豐富的視覺效果、色彩和圖表,也希望能輕鬆分享它們。
而且,我現在越來越少親自編輯這些檔案,而是把它們當作規格說明、參考文件、腦力激盪的產出等等。當我真的需要修改時,通常會直接叫 Claude 去改,這就令 Markdown 其中一個最大優勢失去了意義。
我開始偏好以 HTML 而非 Markdown 作為輸出格式,也越來越多看到 Claude Code 團隊的其他成員這樣做,原因如下。
(如果你想先看一些例子,可以在這裏找到不少:https://thariqs.github.io/html-effectiveness,不過記得回來繼續閱讀背後的原因)
為什麼選擇 HTML?
資訊密度

相比 Markdown,HTML 能傳達豐富得多的資訊。它當然可以做到標題和格式化等基本的文件結構,但同時也能呈現各式各樣的其他資訊,例如:
- 使用表格呈現表格數據
- 使用 CSS 處理設計數據
- 使用 SVG 製作插圖
- 使用 script 標籤展示程式碼片段
- 結合 JavaScript + CSS 與 HTML 元素實現互動
- 使用 SVG 和 HTML 呈現工作流程
- 使用絕對定位和 canvas 表達空間數據
- 使用圖片標籤顯示圖像
我甚至可以說,幾乎沒有什麼 Claude 能讀取的資訊集合,是你無法用 HTML 有效呈現的。這讓它成為模型向你傳遞深入資訊、以及讓你審閱內容的高效方式。
我發現在缺乏這種能力的情況下,模型可能會在 Markdown 中做一些效率較低的事,例如 ASCII 圖表,或者我最喜歡的——用 Unicode 字元來模擬顏色,就像這張來自 Claude Code 的截圖一樣。

Claude Code 嘗試在 Markdown 中顯示顏色
視覺清晰度與易讀性

隨着 Claude 能夠處理更複雜的工作,它撰寫的規格文件和計劃也越來越長。實際上,我發現自己根本不會真正閱讀超過 100 行的 Markdown 檔案,更別說要公司裏其他人去讀了。
但 HTML 文件就易讀得多。Claude 可以從視覺上組織結構,利用分頁、插圖、連結等方式讓導航變得更理想。它甚至可以做到響應式設計,讓你根據裝置類型以不同方式閱讀。
易於分享
由於大部分瀏覽器都無法原生良好地渲染 Markdown 檔案,因此分享起來相當麻煩。你往往要把它們作為附件加到電郵或訊息中。
而 HTML 只要上傳了檔案(例如傳到 S3),就能輕鬆分享連結。你的同事可以在任何地方開啟並輕易引用。
如果你的規格文件、報告或 PR 說明是用 HTML 寫的,別人真正去閱讀的機會會高得多。
雙向互動

HTML 可以讓你與文件互動。例如,你可能想要求它加入滑桿或旋鈕來調整設計,或者讓你在演算法中微調不同選項看看結果。你也可以要求它讓你能把這些變更複製成提示詞,再貼回 Claude Code。
想了解更多關於我的 playgrounds 文章,看看這種雙向互動的例子:https://x.com/trq212/status/2017024445244924382
數據攝取
為什麼要用 Claude Code 而不是例如 ClaudeAI 或 Claude Design 來製作 HTML 檔案?其中一個最大原因是 Claude Code 能攝取的上下文非常豐富。
舉例來說,在寫這篇文章時,我叫 Claude Code 讀取我的程式碼資料夾,找出我生成過的所有 HTML 檔案,將它們分組分類,然後製作一個包含各類圖表的 HTML 檔案。你在本文中看到的圖表就是直接由此而來。
除了檔案系統之外,Claude Code 還能透過你的 MCP(如 Slack、Linear 等)、你的網頁瀏覽器(配合 Chrome 中的 Claude)、你的 git 歷史記錄等尋找額外上下文。
充滿樂趣
用 Claude 製作 HTML 文件就是比較有趣,讓我覺得自己更投入、更有參與感,而這本身就足夠了。
如何開始
我有點擔心大家看完這篇文章後,會把它變成一個 /html 技能之類的東西。雖然那樣做可能有點價值,但我想強調,要讓 Claude 做到這些其實不需要太多功夫。你只需要叫它「製作一個 HTML 檔案」或「製作一個 HTML artifact」就可以了。
關鍵在於你要清楚自己想這個 artifact 做什麼,以及你會如何使用它。隨着時間推移,你或許會建立一個技能,但目前我建議先從零開始下提示詞,熟悉在不同情況下如何使用它。
應用場景
為了更具體說明,我為不同應用場景製作了許多不同的 HTML 檔案。你可以在這裏查看全部:https://thariqs.github.io/html-effectiveness/,以下是概覽。
規格、規劃與探索
HTML 是一塊豐富的畫布,讓 Claude 深入鑽研問題。當我開始處理一個問題時,我不會只寫一份簡單的 Markdown 計劃,而是預期會建立一組互相連結的 HTML 檔案。例如,我可能會先請 Claude Code 進行腦力激盪,並針對不同方案製作一些探索版本。接着我會要求它深入展開其中一個,可能是製作 mockup 或程式碼片段。最後,當我覺得方向對了,就會叫它寫一份實作計劃。滿意之後,我會開一個新 session,把所有這些檔案傳給它去實作。
在驗證階段,我也會請負責驗證的 Agent 讀取這些檔案,這樣它對需求會有更全面的上下文理解。

提示詞範例:
<code-segment id="0" lang="text">
我不確定新手引導畫面該走哪個方向。請生成 6 個截然不同的方案——在版面、語氣和資訊密度上作出變化——並把它們放在同一個 HTML 檔案的網格中,讓我可以並排比較。每個方案都要標註它所作出的取捨。
</code-segment>
<code-segment id="1" lang="text">
在一個 HTML 檔案中建立一份詳盡的實作計劃,記得製作一些 mockup、展示數據流向,並加入我可能需要檢視的重要程式碼片段。讓它易於閱讀和理解。
</code-segment>
應用場景:
- 探索以程式碼實作某件事的其他方法
- 探索多種視覺設計方案
程式碼審查與理解
在 Markdown 檔案中閱讀程式碼可能很困難。但有了 HTML,我們可以渲染 diff、註解、流程圖、模組等等。你可以用它來理解 Agent 所寫的程式碼、進行程式碼審查,或向審查你程式碼的人解釋 PR。我發現這通常比預設的 Github diff 視圖更好用,現在我提交的每個 PR 都會附上一個 HTML 程式碼解說檔。

提示詞範例:
<code-segment id="2" lang="text">
幫我建立一個描述這個 PR 的 HTML artifact,以便我進行審查。我對 streaming/backpressure 邏輯不太熟悉,所以請重點說明那部分。渲染實際的 diff 並在邊距加上行內註解,按嚴重程度為發現的問題標示顏色,以及加入其他有助清晰表達概念的內容。
</code-segment>
應用場景:
- 建立 PR
- 審查 PR
- 理解程式碼中的某個主題
設計與原型
Claude Design 是基於 HTML 的,因為 HTML 在設計上的表現力極強,即使你最終的發佈平台不是 HTML 亦然。Claude 可以先用 HTML 勾勒出設計,然後再用你選擇的語言(例如 React、Swift 等)編寫出來。
你也可以為互動製作原型,例如動畫、操作等。不妨請 Claude 製作滑桿、旋鈕等,讓你精準調校出想要的效果。

提示詞範例:
<code-segment id="3" lang="text">
我想為一個新的結帳按鈕製作原型,點擊後會播放動畫,然後迅速變成紫色。請建立一個 HTML 檔案,附上幾個滑桿和選項,讓我嘗試這個動畫的不同設定,並給我一個複製按鈕,用來複製效果理想的參數。
</code-segment>
適用於:
- 建立設計系統的 artifact
- 調整元件
- 將元件庫視覺化
- 為有趣的動畫製作原型
報告、研究與學習
Claude Code 非常擅長整合多個數據來源的資訊,並轉化成易讀的報告。你可以叫 Claude 搜尋你的 Slack、程式碼庫、git 歷史記錄、互聯網等,然後用它為自己、管理層或團隊生成極具可讀性的報告。
你可以把它整理成長篇 HTML 文件、互動式解說頁面,甚至是幻燈片/簡報。也可以請 Claude 用 SVG 繪製圖表來輔助視覺化。
例如,在我撰寫關於 prompt caching 的文章時,我請 Claude 在讀取 git 歷史記錄後,為我準備一份深入的 HTML 研究檔案,讓我們了解所有關於 prompt caching 的改動。

提示詞範例:
<code-segment id="4" lang="text">
我不明白我們的 rate limiter 實際上是怎樣運作的。請閱讀相關程式碼,並生成單一 HTML 解說頁面:一張 token-bucket 流程圖、3–4 段附註解的關鍵程式碼片段,以及底部的「注意事項」部分。針對只會閱讀一次的人來優化內容。
</code-segment>
適用於:
- 總結某項功能的運作方式
- 向我解釋某個概念
- 每週向上司匯報進度
- 向管理層提交事故報告
- SVG 插圖、流程圖、技術圖表等
自訂編輯介面
有時候,單靠文字框很難準確描述你想要的東西。這時,我會請 Claude 為我正在處理的特定內容建立一個即用即棄的編輯器。不是一個產品,也不是可重複使用的工具,而是一個專為這一筆數據而設的單一 HTML 檔案。
秘訣總是在最後加入匯出功能:一個「複製為 JSON」或「複製為提示詞」按鈕,把我在 UI 中所做的操作轉換成可以貼回 Claude Code 的內容。

提示詞範例:
<code-segment id="5" lang="text">
我需要重新排列這 30 張 Linear ticket 的優先次序。請幫我製作一個 HTML 檔案,每張 ticket 都是一個可拖曳的卡片,可在 Now / Next / Later / Cut 各欄之間移動。先按你的最佳猜測預先排序。加入一個「複製為 markdown」按鈕,匯出最終排序,並為每個分類提供一句理由。
</code-segment>
<code-segment id="6" lang="text">
這是我們的 feature flag 設定。請為它建立一個表單式編輯器,按區域將 flag 分組,顯示它們之間的依賴關係,如果我啟用了一個前置條件未開啟的 flag 就發出警告。加入一個「複製 diff」按鈕,只給我已變更的 key。
</code-segment>
<code-segment id="7" lang="text">
我正在調整這段 system prompt。請製作一個左右並排的編輯器:左邊是可編輯的提示詞,並突出顯示變數位置;右邊是三個範例輸入,可即時重新渲染填入後的模板。加入字元/token 計數器和複製按鈕。
</code-segment>
適用於:
- 重新排序、分流或分類任何項目(ticket、測試案例、意見反饋)
- 編輯結構化設定(feature flag、環境變數、帶約束的 JSON/YAML)
- 透過即時預覽調整提示詞、模板或文案
- 整理數據集、批准/拒絕數據列、標記範例、匯出所選內容
- 為文件、逐字稿或 diff 加上註解並匯出註解
- 挑選難以用文字表達的數值:顏色、緩動曲線、裁剪區域、cron 排程、正則表達式。
常見問題
我一直跟很多人分享我轉用 HTML 的做法,也注意到一些經常被問到的問題。
這樣不是比較浪費 token 嗎?
雖然 Markdown 通常使用的 token 較少,但我發現 HTML 額外的表現力,加上我更願意去閱讀它,整體帶來的輸出效果更好。有了 Opus 4.7 的 1M context window,token 用量增加在上下文窗口中其實不太明顯。
那你現在什麼時候還會用 Markdown?
老實說,我幾乎在所有事情上都已經完全不用 Markdown 了,但我大概算是站在 HTML 極端主義的那一邊。
我要如何查看 HTML 檔案?
我通常會在本地瀏覽器直接開啟(你可以叫 Claude 幫你開啟),或者如果你想要一個可分享的連結,就上傳到 S3。
這樣生成時間不是比 Markdown 長嗎?
的確會長一些!HTML 可能需要比 Markdown 多 2-4 倍的時間,但我發現成果是值得的。
那版本控制怎麼辦?
老實說,這是 HTML 最大的缺點之一。相比 Markdown,HTML 的 diff 比較雜亂,也更難審查。
我要如何讓 Claude 符合我的品味/不要做得太醜?
前端設計插件能幫助 Claude 製作出優質的 HTML 檔案。但要符合你自己公司的風格,你可以指引 Claude 參考你的程式碼庫,建立一個單一的設計系統 HTML 檔案。然後你就可以把這個設計系統檔案作為其他 HTML 檔案的參考。
保持參與感
以上種種,其實是想說我認為自己使用 HTML 的真正原因,是我覺得自己與 Claude 之間的聯繫更緊密了。我曾開始擔心,因為我不再深入閱讀計劃,最終只能任由 Claude 自行作決定。
但我很高興地說,使用 HTML 反而讓我感到前所未有的投入。希望你也有同感。





