TRANSLATION

本文作者 Thariq 是 Anthropic Claude Code 團(tuán)隊(duì)的工程師，原文標(biāo)題 Using Claude Code: The Unreasonable Effectiveness of HTML

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

Thariq Shihipar

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

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

用 Claude 寫 HTML，效果很好

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

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

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

我已經(jīng)開始用 HTML 取代 Markdown 作為輸出格式，Claude Code 團(tuán)隊(duì)里越來越多人也在這么做。下面說說為什么

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

為什么是 HTML 信息密度

HTML 能承載的信息比 Markdown 豐富得多。除了基本的文檔結(jié)構(gòu)（標(biāo)題、格式化），它還能表達(dá)各種其他類型的信息：

●表格數(shù)據(jù)（用 table）

●設(shè)計(jì)數(shù)據(jù)（用 CSS）

●插圖（用 SVG）

●代碼片段（用 script 標(biāo)簽）

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

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

●空間數(shù)據(jù)（用絕對定位和 canvas）

●圖片（用 img 標(biāo)簽）

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

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

Claude Code 在 Markdown 里試圖表達(dá)顏色

視覺清晰度和可讀性

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

但 HTML 文檔好讀得多。Claude 可以用 tab 分組、用插圖輔助、加鏈接導(dǎo)航，把結(jié)構(gòu)組織得更容易瀏覽。它甚至可以做成響應(yīng)式的，讓你在不同設(shè)備上以不同的方式閱讀

方便分享

Markdown 文件很難分享，因?yàn)榇蟛糠譃g覽器不能原生渲染它。你通常得把它作為附件加到郵件或消息里

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

一個(gè) spec、報(bào)告或 PR 說明真正被人讀到的概率，HTML 比 Markdown 高得多

雙向交互

HTML 可以讓你跟文檔互動(dòng)。比如你可以讓它加滑塊或旋鈕來調(diào)整設(shè)計(jì)參數(shù)，或者讓你調(diào)整算法的不同選項(xiàng)來看效果。你還可以讓它加一個(gè)按鈕，把你的調(diào)整復(fù)制成 prompt，粘貼回 Claude Code

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

數(shù)據(jù)攝入能力

為什么要用 Claude Code 來生成 HTML，而不用 Claude.ai 或 Claude Design？最大的原因是 Claude Code 能攝入的上下文多得多

比如寫這篇文章的時(shí)候，我讓 Claude Code 掃描我的代碼文件夾，找出所有我生成過的 HTML 文件，按類型分組和分類，然后生成一個(gè)包含所有分類圖表的 HTML 文件。你在這篇文章里看到的那些圖表就是這么來的

除了文件系統(tǒng)，Claude Code 還能通過你的 MCP（比如 Slack、Linear 等）、網(wǎng)頁瀏覽器（通過 Claude in Chrome）、Git 歷史等獲取額外的上下文

開心

用 Claude 做 HTML 文檔就是更好玩，讓我覺得自己更投入、更參與到創(chuàng)作過程中。光這一條就夠了

怎么開始

說實(shí)話我有點(diǎn)擔(dān)心，大家讀完這篇文章會(huì)立刻做一個(gè) /html skill 之類的東西。雖然那可能有點(diǎn)用，但我想強(qiáng)調(diào)的是，你不需要做太多準(zhǔn)備工作。直接跟 Claude 說「幫我做一個(gè) HTML 文件」或「做一個(gè) HTML artifact」就行了

關(guān)鍵是你要知道你想讓這個(gè) artifact 做什么，以及你打算怎么用它。時(shí)間長了你可能會(huì)做一個(gè) skill，但現(xiàn)在我建議先從零開始 prompt，在不同場景下慢慢摸索用法

具體用法

為了說得更具體，我做了很多不同用途的 HTML 文件。你可以在這里看到所有的：thariqs.github.io/html-effectiveness，下面是分類概述

Spec、規(guī)劃和探索

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

做驗(yàn)證的時(shí)候，我也會(huì)讓驗(yàn)證 Agent 讀入這些文件，這樣它對需求的上下文理解會(huì)寬廣得多

示例 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.

適用場景：

●探索代碼的不同實(shí)現(xiàn)方式

●探索多種視覺設(shè)計(jì)方案

代碼審查和理解

代碼在 Markdown 文件里很難讀。但用 HTML 我們可以渲染 diff、加注釋標(biāo)注、畫流程圖、展示模塊關(guān)系。用這個(gè)來理解 Agent 寫的代碼、做代碼審查、或者給審查你代碼的人做解釋。我發(fā)現(xiàn)這通常比 GitHub 默認(rèn)的 diff 視圖好用，我現(xiàn)在每個(gè) PR 都會(huì)附一個(gè) 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.

適用場景：

●創(chuàng)建 PR

●審查 PR

●理解代碼中的某個(gè)主題

設(shè)計(jì)和原型

Claude Design 就是基于 HTML 的，因?yàn)?HTML 在設(shè)計(jì)表達(dá)上極其強(qiáng)大，即使你最終的目標(biāo)平臺(tái)不是 HTML。Claude 可以先用 HTML 畫出設(shè)計(jì)稿，然后再轉(zhuǎn)寫成你要的語言，React、Swift 都行

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

示例 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.

適用場景：

●創(chuàng)建設(shè)計(jì)系統(tǒng)產(chǎn)物

●調(diào)整組件

●可視化組件庫

●制作原型動(dòng)畫

報(bào)告、研究和學(xué)習(xí)

Claude Code 非常擅長從多個(gè)數(shù)據(jù)源綜合信息，轉(zhuǎn)化成可讀性很高的報(bào)告。你可以讓 Claude 搜你的 Slack、代碼庫、Git 歷史、互聯(lián)網(wǎng)等，然后生成極其易讀的報(bào)告，給自己看、給領(lǐng)導(dǎo)看、給團(tuán)隊(duì)看

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

比如我寫 prompt caching 那幾篇帖子的時(shí)候，我讓 Claude 先讀了 Git 歷史中所有跟 prompt caching 相關(guān)的改動(dòng)，然后為我準(zhǔn)備了一份深度研究的 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.

適用場景：

●總結(jié)一個(gè)功能是怎么工作的

●給我解釋一個(gè)概念

●給老板寫周報(bào)

●給領(lǐng)導(dǎo)寫事故報(bào)告

●SVG 插圖、流程圖、技術(shù)圖表等

一次性編輯器

有些事情純用文本框很難描述清楚。這種時(shí)候我會(huì)讓 Claude 給我做一個(gè)一次性的編輯器，專門為我當(dāng)前在做的這件事而設(shè)計(jì)。不是產(chǎn)品，不是可復(fù)用的工具，就是一個(gè) HTML 文件，專門為這一份數(shù)據(jù)而做

關(guān)鍵是結(jié)尾永遠(yuǎn)要有一個(gè)導(dǎo)出：一個(gè)「復(fù)制為 JSON」或「復(fù)制為 prompt」的按鈕，把你在 UI 上做的事情變回可以粘貼進(jìn) 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.

適用場景：

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

●編輯結(jié)構(gòu)化配置（feature flag、環(huán)境變量、有約束的 JSON/YAML）

●調(diào) prompt、模板或文案，帶實(shí)時(shí)預(yù)覽

●整理數(shù)據(jù)集，逐行批準(zhǔn)/拒絕，打標(biāo)簽，導(dǎo)出選擇結(jié)果

●標(biāo)注文檔、轉(zhuǎn)錄稿或 diff，導(dǎo)出標(biāo)注

●選擇那些用文字很難表達(dá)的值：顏色、緩動(dòng)曲線、裁剪區(qū)域、cron 表達(dá)式、正則

常見問題

我跟很多人聊過我換 HTML 的事，看到了幾個(gè)反復(fù)出現(xiàn)的問題

HTML 不是更費(fèi) token 嗎？確實(shí) Markdown 通常用的 token 更少，但 HTML 表達(dá)能力更強(qiáng)，而且我真的會(huì)去讀，所以整體產(chǎn)出質(zhì)量更好。Opus 4.7 的 100 萬 token 上下文窗口下，多出來的 token 消耗幾乎感知不到

Markdown 現(xiàn)在還用嗎？說實(shí)話我?guī)缀跻呀?jīng)完全停用 Markdown 了，但我大概是屬于 HTML 極端派那邊的

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

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

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

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

保持在 Loop 里

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

之前我開始擔(dān)心，因?yàn)槲也辉偕钊腴喿x方案了，我只能放手讓 Claude 自己做決策

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

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

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