別寫 Markdown 了，用 HTML【譯】
整理版優先睇
用HTML取代Markdown，提升Agent輸出的可讀性與互動性
呢篇文章係Anthropic Claude Code團隊工程師Thariq Shihipar嘅經驗分享。佢發現隨住Agent能力越來越強，Markdown作為輸出格式嘅限制愈來愈明顯——超過一百行嘅Markdown文件佢基本讀唔落，而且佢越來越少手動編輯呢啲文件，反而係交畀Claude改，令Markdown「人好編輯」嘅優勢失效。
Thariq提出用HTML取代Markdown作為Agent輸出格式，原因係HTML可以承載更豐富嘅信息：表格、CSS、SVG、互動元素等等，幾乎冇Claude讀得明但HTML表達唔到嘅資訊。佢強調HTML令文檔視覺更清晰、更容易分享（上傳到S3就畀到連結），仲可以做到雙向互動，例如加滑塊調整參數。佢認為咁樣令佢重新感覺自己參與喺創作過程入面，而唔係齋睇方案。
文章詳細講解咗點樣開始用HTML：直接prompt Claude Code「幫我做一個HTML文件」，唔需要複雜準備。佢仲列出咗幾個具體用法，包括spec規劃、代碼審查、設計原型、報告研究、一次性編輯器。最後提醒HTML生成速度係Markdown嘅2-4倍，版本控制嘅diff噪音大，但整體好處遠超代價。
- 結論：HTML比Markdown更適合Agent輸出，因為信息密度高、視覺清晰、易分享、可互動。
- 方法：直接prompt Claude Code生成HTML文件，由簡單場景開始慢慢摸索。
- 差異：HTML承載能力遠超Markdown，但生成慢、版本控制難；Markdown嘅「人好編輯」優勢已唔重要。
- 啟發：用HTML後開發者更投入決策，重新「喺Loop入面」，而唔係放手畀Agent自己做。
- 可行動點：從spec規劃、代碼審查、設計原型、報告、一次性編輯器呢五個場景開始嘗試。
HTML示例集合
Thariq製作嘅多個HTML文件展示，涵蓋spec、代碼審查、設計原型等場景
點解要轉用HTML？
Markdown一直係Agent同我哋溝通最常用嘅格式，但隨住Agent變強，我發現Markdown嘅限制越來越明顯。超過一百行嘅Markdown文件我基本讀唔落，我想要更豐富嘅可視化、顏色、圖表，同埋方便分享畀人。
Markdown超過一百行我就讀唔落
而且我越來越唔會自己編輯呢啲文件，反而係交畀Claude改，令Markdown最大優勢「人好編輯」基本失效。我已經開始用HTML取代Markdown作為輸出格式，Claude Code團隊入面愈來愈多人咁做。
- 信息密度：HTML可以承載表格、CSS、SVG、script標籤、互動元素等，Markdown做唔到。
- 視覺清晰度：Claude可以用tab分組、插圖、連結導航，令文檔更容易瀏覽。
- 方便分享：上傳HTML到S3，畀個連結同事就開到，唔使附件。
- 雙向交互：加滑塊、按鈕，調整參數，甚至複製成prompt貼返去Claude Code。
- 數據攝入能力：Claude Code可以掃描文件系統、MCP、瀏覽器、Git歷史，生成更全面嘅HTML。
- 開心：用HTML做文檔更好玩，令自己更投入創作過程。
點樣開始用HTML？
其實唔需要做好多準備，直接同Claude講「幫我做一個HTML文件」或者「做一個HTML artifact」就得。關鍵係你要知呢個artifact想做乜，同埋打算點用。時間長咗你可能會做一個skill，但而家建議先從零開始prompt，喺唔同場景慢慢摸索用法。
直接同Claude講「幫我做一個HTML文件」
- 1 Spec、規劃同探索：生成一組HTML文件做頭腦風暴、mockup同實施方案，開新session時傳入呢啲文件畀Agent。
- 2 代碼審查同理解：用HTML渲染diff、加註釋、畫流程圖，每個PR附一個HTML解釋文件。
- 3 設計同原型：先用HTML畫設計稿，再轉寫成React或Swift，加滑塊調整動畫參數。
- 4 報告、研究同學習：綜合多個數據源生成易讀報告、交互式解釋器或幻燈片，用SVG畫圖。
- 5 一次性編輯器：為特定數據做拖曳卡片、表單編輯器、prompt調試工具，結尾有「複製為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.關鍵係結尾永遠要有一個導出按鈕，將UI操作變返文本
常見問題同總結
好多人都問過幾個反覆出現嘅問題：HTML會唔會更費token？係，但表達能力更強，而且我真係會去讀，整體產出更好。Markdown而家仲用唔用？我幾乎完全停用咗，但我係極端派。點樣睇HTML？喺本地瀏覽器打開，或者上傳去S3分享。生成係咪更慢？係，大概2-4倍時間，但值得。版本控制點算？HTML diff噪音大，係最大短板。
- HTML生成時間係Markdown嘅2-4倍，但結果值得。
- 版本控制：HTML diff噪音大，review較難。
- 如果怕Claude做得太醜，可以用frontend design插件或讀代碼庫生成設計系統HTML做樣式參考。
用HTML之後，我感覺自己比以前任何時候都更喺loop入面
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