別寫 Markdown 了，用 HTML【譯】

TRANSLATION

本文作者 Thariq 是 Anthropic Claude Code 團隊的工程師，原文標題 Using Claude Code: The Unreasonable Effectiveness of HTML

本文中，他建議把輸出從 Markdown 換成了 HTML，以及怎么用

Thariq Shihipar

Claude Code 工程師 · Anthropic Technical Staff · @trq212

Anthropic Claude Code 團隊的核心工程師，Claude Code 幾乎所有重大功能更新都由他在 X 上首發。之前是 YC W20 創始人（游戲公司，融了 1700 萬美元），MIT Media Lab 出身。

用 Claude 寫 HTML，效果很好

Markdown 一直是 Agent 跟我們溝通時最常用的文件格式。簡單，跨平臺，有一定的富文本能力，而且方便你手動編輯。Claude 甚至學會了在 Markdown 里用 ASCII 畫圖，畫得還挺像樣

但隨著 Agent 變得越來越強，我越來越覺得 Markdown 是一種限制。超過一百行的 Markdown 文件我基本讀不下去。我想要更豐富的可視化，想要顏色和圖表，想要方便地分享給別人

而且我越來越不自己編輯這些文件了。我更多是把它們當 spec、參考資料、頭腦風暴的產出物來用。真要改的時候，也是讓 Claude 來改，這讓 Markdown 最大的優勢「人好編輯」基本失效了

我已經開始用 HTML 取代 Markdown 作為輸出格式，Claude Code 團隊里越來越多人也在這么做。下面說說為什么

（如果你想先看一些示例，可以去 thariqs.github.io/html-effectiveness 看，但記得回來讀完為什么這么做）

為什么是 HTML 信息密度

HTML 能承載的信息比 Markdown 豐富得多。除了基本的文檔結構（標題、格式化），它還能表達各種其他類型的信息：

●表格數據（用 table）

●設計數據（用 CSS）

●插圖（用 SVG）

●代碼片段（用 script 標簽）

●交互元素（用 HTML + JavaScript + CSS）

●工作流程圖（用 SVG 和 HTML）

●空間數據（用絕對定位和 canvas）

●圖片（用 img 標簽）

我甚至會說，幾乎沒有什么信息是 Claude 能讀懂但 HTML 表達不了的。這讓 HTML 成為一種極其高效的方式，讓模型把深度信息傳達給你，也讓你能高效地審閱

我發現如果不讓模型用 HTML，它就會在 Markdown 里做一些很勉強的事，比如畫 ASCII 圖。我最喜歡的一個例子是，它試圖用 Unicode 字符來「估算」顏色，就像下面這張 Claude Code 的截圖

Claude Code 在 Markdown 里試圖表達顏色

視覺清晰度和可讀性

隨著 Claude 能做的事情越來越復雜，它寫出來的 spec 和方案也越來越長。實際使用中，超過 100 行的 Markdown 文件我基本不會真的去讀，更別說讓團隊里其他人讀了

但 HTML 文檔好讀得多。Claude 可以用 tab 分組、用插圖輔助、加鏈接導航，把結構組織得更容易瀏覽。它甚至可以做成響應式的，讓你在不同設備上以不同的方式閱讀

方便分享

Markdown 文件很難分享，因為大部分瀏覽器不能原生渲染它。你通常得把它作為附件加到郵件或消息里

用 HTML 的話，只要你把文件上傳到某個地方（比如 S3），就可以輕松分享鏈接。同事在哪都能打開，隨時引用

一個 spec、報告或 PR 說明真正被人讀到的概率，HTML 比 Markdown 高得多

雙向交互

HTML 可以讓你跟文檔互動。比如你可以讓它加滑塊或旋鈕來調整設計參數，或者讓你調整算法的不同選項來看效果。你還可以讓它加一個按鈕，把你的調整復制成 prompt，粘貼回 Claude Code

更多關于雙向交互的例子，可以看我之前關于 playground 的帖子：x.com/trq212/status/2017024445244924382

數據攝入能力

為什么要用 Claude Code 來生成 HTML，而不用 Claude.ai 或 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-effectiveness，下面是分類概述

Spec、規劃和探索

HTML 是一塊很好的畫布，讓 Claude 深入探索一個問題。我現在開始做一個問題的時候，不再寫一份簡單的 Markdown 方案，而是會生成一組 HTML 文件。比如我可能先讓 Claude Code 做頭腦風暴，對不同選項做幾個探索。然后讓它深入展開其中一個，做 mockup 或代碼片段。滿意了再讓它寫實施方案。方案確定后，我開一個新 session，把所有這些文件傳進去讓它實施

做驗證的時候，我也會讓驗證 Agent 讀入這些文件，這樣它對需求的上下文理解會寬廣得多

示例 Prompt：

I'm not sure what direction to take the onboarding screen. Generate 6 distinctly different approaches — vary layout, tone, and density — and lay them out as a single HTML file in a grid so I can compare them side by side. Label each with the tradeoff it's making.

Create a thorough implementation plan in a HTML file, be sure to make some mockups, show data flow and add important code snippets I might want to review. Make it easy to read and digest.

適用場景：

●探索代碼的不同實現方式

●探索多種視覺設計方案

代碼審查和理解

代碼在 Markdown 文件里很難讀。但用 HTML 我們可以渲染 diff、加注釋標注、畫流程圖、展示模塊關系。用這個來理解 Agent 寫的代碼、做代碼審查、或者給審查你代碼的人做解釋。我發現這通常比 GitHub 默認的 diff 視圖好用，我現在每個 PR 都會附一個 HTML 代碼解釋文件

示例 Prompt：

Help me review this PR by creating an HTML artifact that describes it. I'm not very familiar with the streaming/backpressure logic so focus on that. Render the actual diff with inline margin annotations, color-code findings by severity and whatever else might be needed to convey the concept well.

適用場景：

●創建 PR

●審查 PR

●理解代碼中的某個主題

設計和原型

Claude Design 就是基于 HTML 的，因為 HTML 在設計表達上極其強大，即使你最終的目標平臺不是 HTML。Claude 可以先用 HTML 畫出設計稿，然后再轉寫成你要的語言，React、Swift 都行

你還可以做交互原型，比如動畫、操作等。考慮讓 Claude 做滑塊、旋鈕之類的控件，讓你精確調出你想要的效果

示例 Prompt：

I want to prototype a new checkout button, when clicked it does a play animation and then turns purple quickly. Create a HTML file with several sliders and options for me to try different options on this animation, give me a copy button to copy the parameters that worked well.

適用場景：

●創建設計系統產物

●調整組件

●可視化組件庫

●制作原型動畫

報告、研究和學習

Claude Code 非常擅長從多個數據源綜合信息，轉化成可讀性很高的報告。你可以讓 Claude 搜你的 Slack、代碼庫、Git 歷史、互聯網等，然后生成極其易讀的報告，給自己看、給領導看、給團隊看

形式可以是一個長 HTML 文檔、一個交互式解釋器，甚至是一個幻燈片。讓 Claude 用 SVG 畫圖來輔助可視化

比如我寫 prompt caching 那幾篇帖子的時候，我讓 Claude 先讀了 Git 歷史中所有跟 prompt caching 相關的改動，然后為我準備了一份深度研究的 HTML 文件來閱讀

示例 Prompt：

I don't understand how our rate limiter actually works. Read the relevant code and produce a single HTML explainer page: a diagram of the token-bucket flow, the 3-4 key code snippets annotated, and a "gotchas" section at the bottom. Optimize it for someone reading it once.

適用場景：

●總結一個功能是怎么工作的

●給我解釋一個概念

●給老板寫周報

●給領導寫事故報告

●SVG 插圖、流程圖、技術圖表等

一次性編輯器

有些事情純用文本框很難描述清楚。這種時候我會讓 Claude 給我做一個一次性的編輯器，專門為我當前在做的這件事而設計。不是產品，不是可復用的工具，就是一個 HTML 文件，專門為這一份數據而做

關鍵是結尾永遠要有一個導出：一個「復制為 JSON」或「復制為 prompt」的按鈕，把你在 UI 上做的事情變回可以粘貼進 Claude Code 的文本

示例 Prompt：

I need to reprioritize these 30 Linear tickets. Make me an HTML file with each ticket as a draggable card across Now / Next / Later / Cut columns. Pre-sort them by your best guess. Add a "copy as markdown" button that exports the final ordering with a one-line rationale per bucket.

Here's our feature flag config. Build a form-based editor for it, group flags by area, show dependencies between them, warn me if I enable a flag whose prerequisite is off. Add a "copy diff" button that gives me just the changed keys.

I'm tuning this system prompt. Make a side-by-side editor: editable prompt on the left with the variable slots highlighted, three sample inputs on the right that re-render the filled template live. Add a character/token counter and a copy button.

適用場景：

●重新排序、分類、分桶任何東西（工單、測試用例、用戶反饋）

●編輯結構化配置（feature flag、環境變量、有約束的 JSON/YAML）

●調 prompt、模板或文案，帶實時預覽

●整理數據集，逐行批準/拒絕，打標簽，導出選擇結果

●標注文檔、轉錄稿或 diff，導出標注

●選擇那些用文字很難表達的值：顏色、緩動曲線、裁剪區域、cron 表達式、正則

常見問題

我跟很多人聊過我換 HTML 的事，看到了幾個反復出現的問題

HTML 不是更費 token 嗎？確實 Markdown 通常用的 token 更少，但 HTML 表達能力更強，而且我真的會去讀，所以整體產出質量更好。Opus 4.7 的 100 萬 token 上下文窗口下，多出來的 token 消耗幾乎感知不到

Markdown 現在還用嗎？說實話我幾乎已經完全停用 Markdown 了，但我大概是屬于 HTML 極端派那邊的

怎么查看 HTML 文件？我一般就在本地瀏覽器打開（你可以讓 Claude 幫你打開），如果要分享就傳到 S3 上

生成不是更慢嗎？確實更慢。HTML 的生成時間大概是 Markdown 的 2-4 倍，但我覺得結果值得

版本控制怎么辦？說實話這是 HTML 最大的短板。HTML 的 diff 噪音很大，review 起來比 Markdown 難很多

怎么讓 Claude 符合我的審美 / 別做得太丑？frontend design 插件能幫 Claude 做出好看的 HTML 文件。如果要匹配你公司的風格，可以讓 Claude 讀你的代碼庫，生成一個設計系統 HTML 文件，然后用那個文件作為其他 HTML 輸出的樣式參考

保持在 Loop 里

以上所有這些，歸根到底，我覺得我用 HTML 的真正原因是：我重新感覺到自己在 loop 里了

之前我開始擔心，因為我不再深入閱讀方案了，我只能放手讓 Claude 自己做決策

但我很高興地說，用了 HTML 之后，我感覺自己比以前任何時候都更在 loop 里。希望你也一樣

原文鏈接：x.com/trq212/article/2052809885763747935

示例集合：thariqs.github.io/html-effectiveness