使用 Claude Code：HTML 難以置信的奇效【譯】
整理版優先睇
用HTML代替Markdown做AI協作文件，大幅提升閲讀效率同互動性
呢篇文章係由開發者 Thariq 分享，佢係 Claude Code 團隊嘅成員，成日要用 AI 生成文件畀人睇。佢發現傳統 Markdown 喺資訊密度同可讀性上越嚟越唔夠用，尤其係當文件超過 100 行嗰陣，佢同團隊都唔多想睇。所以佢開始全面轉用 HTML 作為輸出格式，結果發現無論係自己審查定係俾人睇，效率都高好多。
文章整體結論係：HTML 雖然用多啲 Token 同生成時間，但係因為佢可以整合表格、圖表、互動元素、自適應排版，令到成個溝通變得更直接同好玩，尤其適合用喺需求規格、代碼審查、設計原型同報告呢啲場景。Thariq 仲提供咗大量實際例子同提示詞，話你其實只需要講「幫我做個 HTML 檔案」就得，唔使複雜設定。
作者特別強調，HTML 令人機協作更加順暢——因為你可以睇得更清楚、互動更多，唔會覺得自己甩咗個圈。最終佢覺得用 HTML 係令佢更投入創作嘅關鍵。
- HTML 比 Markdown 有更高資訊密度，可以同時用表格、SVG、JavaScript 等呈現複雜數據，唔使靠 ASCII 畫圖。
- 可讀性大幅提升：選項卡、插圖、連結令文件結構清晰，手機都睇得舒服，解決咗 Markdown 文件過長冇人睇嘅問題。
- 分享方便：上傳至雲端就畀到連結，同事直接用瀏覽器開，唔使好似 Markdown 咁要附件。
- 雙向互動：加滑塊、按鈕、一鍵複製參數，令你唔單止睇文件，仲可以直接調整內容再貼返俾 AI。
- 唔需要複雜技能：直接講「做個 HTML 檔案」就得，最緊要係清楚自己想要乜用途，慢慢摸索就得。
HTML Effectiveness 示例頁面
作者收集嘅大量 HTML 使用場景範例，包括需求計劃、代碼審查、設計原型、報告同自定義編輯器。
點解要由 Markdown 轉用 HTML？
Thariq 話 Markdown 一直係 AI Agent 溝通嘅主流格式，但隨住文件越嚟越長，佢發覺自己根本冇心機睇成百行嘅 Markdown。佢想要更豐富嘅視覺展示、明亮色彩同直觀圖表，而且希望容易分享畀團隊。
而家佢更多係將文件當做需求文檔或者參考資料，改都係直接寫 Prompt 叫 Claude 改，Markdown 最核心嘅「易於人手編輯」優勢已經冇咗。
- 1 信息密度：HTML 可以用表格、CSS、SVG、JavaScript、script 標籤等展示數據，連 workflow 圖表都畫到，唔使再硬用 ASCII 畫圖。
- 2 視覺清晰度：Claude 可以加選項卡、插圖、連結，令文檔結構井井有條，仲做到移動端自適應。
- 3 易於分享：上傳去 S3 就畀到連結，同事用任何裝置都得，閲讀機會大增。
- 4 雙向交互：加滑塊、旋鈕、按鈕，可以即時調整參數再一鍵複製返 Claude Code，唔使淨係睇。
- 5 數據攝取：Claude Code 可以讀好大 context，例如遍歷本地代碼、Slack 記錄、Linear 任務等，產出結合多源數據嘅 HTML 報告。
- 6 充滿樂趣：整 HTML 本身好玩，令佢覺得自己更深度參與創造過程。
點樣開始用 HTML？
作者擔心大家會將呢個方法變成一 set 複雜嘅 skill 指令，但佢強調：你只需要直接同 Claude 講「做個 HTML 檔案」就得，完全唔使額外設定。
真正嘅竅門係要清楚呢個檔案想做啲乜、你會點用，慢慢摸索唔同場景下嘅用法。
Thariq 列出咗幾個主要使用場景，每個都有對應嘅提示詞示例，你可以直接參考去試。
- 需求、計劃與探索：叫 Claude 生成多個方案 HTML 網格，或者畫視覺草圖同核心代碼片段。
- 代碼審查與理解：用 HTML 渲染 diff、頁邊註釋、流程圖，相比 GitHub 嘅 diff view 好用好多。
- 設計與原型製作：用滑塊同旋鈕微調 UI 參數，整動畫交互原型，再一鍵複製參數。
- 報告、研究與學習：整合 Slack、Git 記錄等海量數據，生成精美報告，用 SVG 畫圖表。
- 自定義編輯界面：為特定數據整臨時可視化編輯器，例如拖拽任務優先級、編輯功能開關配置、調優系統提示詞。
每個自定義編輯界面都要設計導出功能，例如「複製為 JSON」或「複製為提示詞」，先可以將結果貼返 Claude Code 繼續用。
常見問題同最後總結
- 唔會浪費 Token 咩？確實多啲，但 Opus 4.7 有 100 萬 context window，多出嚟嘅 Token 可以忽略。
- 而家仲用 Markdown 嗎？作者話幾乎唔用，承認自己可能極端咗啲。
- 點樣令生成嘅 HTML 靚仔？可以叫 Claude 掃描公司代碼庫，生成一份設計系統 HTML，之後作為參考保持風格一致。
- 保持人機協同：HTML 令佢感覺自己仲參與緊，唔會被 AI 拋離。
總括嚟講，Thariq 認為 HTML 係目前最適合 AI 協作嘅文件格式，尤其係當你需要傳達複雜資訊、多人協作同互動調整嗰陣。佢強烈建議大家直接開始試，由簡單 Prompt 入手，慢慢發掘更多可能性。
作者：Thariq
Markdown 已經成為 AI 智能體 (AI Agent) 同我哋溝通嗰陣最常用嘅文件格式。佢簡單、便攜、有返啲富文本 (Rich text) 能力，而且超容易人手修改。你甚至會發現，Claude 已經變得超擅長喺 Markdown 文件裏面用 ASCII (美國信息交換標準代碼，即係用純文字符號砌成圖表) 字符嚟畫圖。
但係，隨住 AI 智能體變得越嚟越勁，我開始覺得 Markdown 變成咗一種束縛。面對成百行嘅 Markdown 文件，我完全冇心機睇落去。我想要更豐富嘅視覺展示、鮮艷嘅顏色同直觀嘅圖表，仲希望可以輕輕鬆鬆咁分享畀團隊。
另外，我而家越嚟越少親自去編輯呢啲文件。我更多係將佢哋當做需求文檔 (Specs)、參考資料或者腦暴嘅輸出結果。就算要改，我通常都係直接寫提示詞 (Prompt) 叫 Claude 去改。咁樣就令到 Markdown 最核心嘅優勢——容易人手編輯——完全冇咗。
所以，相比 Markdown，我開始更鍾意將 HTML 做輸出格式。我仲發現 Claude Code 團隊嘅其他成員都越嚟越常用 HTML。下面我想同大家講嚇背後嘅原因。
（如果你想先睇啲直觀嘅例子，可以㩒呢度睇大量範例：https://thariqs.github.io/html-effectiveness/ ，不過記得睇完返嚟，等我繼續講點解要咁做。）
點解揀 HTML？
資訊密度 (Information Density)
HTML 可以比 Markdown 傳達豐富得多嘅資訊。佢當然處理到好似標題同簡單排版呢啲基本文檔結構，但佢嘅威力遠遠唔止咁，佢仲可以完美展示各種複雜資訊，例如：
• 用表格 (Tables) 展示數據列 • 用 CSS (層疊樣式表，用嚟控制網頁嘅外觀同佈局) 展示設計細節 • 用 SVG (可縮放向量圖形，一種基於代碼嘅清晰圖像格式) 畫靚插圖 • 用 script 標籤嵌入代碼片段 (Code snippets) • 結合 HTML 元素、JavaScript 同 CSS 去做到動態互動 • 結合 SVG 同 HTML 畫清晰嘅工作流程圖 (Workflows) • 用絕對定位同畫布 (Canvases) 展示空間分佈數據 • 用 image 標籤直接插入圖片
我甚至夠膽講：只要係 Claude 睇得明嘅資訊，幾乎冇嘢係唔可以用 HTML 高效展示嘅。呢種特性令 HTML 成為咗一種極之有效嘅載體，無論係模型向你傳遞深度資訊，定係你閲讀審查，都順暢到爆。
我發現，如果冇得用 HTML，模型往往會喺 Markdown 裏面做啲極之低效率嘅「奇怪操作」，例如夾硬用 ASCII 字符去畫圖表；或者——呢個係我最哭笑不得嘅——好似下面呢張 Claude Code 截圖咁，用 Unicode (統一碼) 字符嚟生硬咁模擬顏色色塊。
視覺清晰度同易讀性 (Visual Clarity & Ease of Reading)
隨住 Claude 可以處理越來越複雜嘅工作，佢寫出嚟嘅需求規格說明同實施計劃都變得越嚟越大份。喺實際工作中，我發現自己基本上唔會讀超過 100 行嘅 Markdown 文件，更唔好指望團隊裏面嘅其他人去睇。
但 HTML 文件就容易睇得多。Claude 可以透過選項卡 (Tabs)、插圖、連結等視覺元素，將文件結構整理得井井有條，極之方便導航瀏覽。佢甚至做到流動裝置自適應，令你喺手機等唔同尺寸嘅裝置上都睇得好舒服。
容易分享 (Ease of Sharing)
分享 Markdown 文件其實幾頭痕，因為大多數瀏覽器本身並唔擅長渲染佢哋。你通常只可以將佢哋當做附件，夾硬塞落電郵或聊天訊息度發畀人。
但係有咗 HTML，只要你將文件上載到雲端（例如上載到雲端儲存 S3 度），你就可以輕鬆咁將連結分享出去。你嘅同事可以隨時隨地用任何裝置打開佢，仲可以輕鬆噉參考。
如果你嘅需求文檔、分析報告或者代碼審查說明係用 HTML 寫嘅，其他人會真係用心去睇嘅機會絕對會大好多。
雙向互動 (Two-way Interaction)
HTML 容許你同文檔進行真實嘅互動。例如，你可以叫 Claude 喺頁面上加幾個滑塊 (Sliders) 或旋鈕，用嚟直觀咁調整設計效果；或者提供一啲選項，等你可以微調演算法嘅參數，睇嚇結果會有咩變化。你甚至可以要求佢加個掣，等你將微調完嘅完美參數「一鍵複製」做提示詞，直接貼返落 Claude Code 度。
想知多啲關於呢種雙向互動嘅例子，可以去睇我之前關於「遊樂場 (Playgrounds)」嘅帖文：https://x.com/trq212/status/2017024445244924382
數據攝取與理解 (Data Ingestion)
點解我哋要用終端工具 Claude Code 嚟生成 HTML 文件，而唔直接用網頁版嘅 Claude AI 或者 Claude Design 呢？其中一個最大嘅原因，就係 Claude Code 可以攝取極之龐大嘅上下文 (Context) 資訊。
以寫呢篇文章為例，我叫 Claude Code 自動遍歷我電腦嘅代碼文件夾，揾曬所有由佢生成嘅 HTML 文件，幫佢哋分組歸類，然後生成一個全新嘅 HTML 頁面，喺裏面用圖表展示每一類文件嘅特徵。你喺呢篇文章見到嘅配圖，就係呢個工作流程嘅直接產物。
除咗本地文件系統，Claude Code 仲可以透過你嘅 MCP (模型上下文協定，一種容許 AI 模型存取外部工具同私人數據嘅標準) 接入其他極之豐富嘅上下文資訊，例如 Slack (團隊通訊軟件) 聊天記錄、Linear (項目追蹤工具) 任務看板等。佢仲可以結合瀏覽器、Git 版本控制歷史記錄等多種來源獲取背景知識。
充滿樂趣 (It’s Joyful)
用 Claude 製作 HTML 文件本身就係一件極之好玩嘅事。佢令我覺得自己更深咁參與咗創造嘅過程，淨係呢份參與感就已經夠曬吸引。
點樣開始 (How to Get Started)
我有啲擔心，大家睇完呢篇文章之後，會將佢當成一個專門嘅 /html 複雜技能指令或者類似嘅嘢。雖然咁做可能都有價值，但我特別想強調：你根本唔需要做任何繁瑣嘅設定，就可以令 Claude 幫你生成 HTML。你只需要好似平時傾偈咁，直接同佢講：「整一個 HTML 文件畀我」或者「生成一個 HTML 製品 (Artifact)」就得。
真正嘅竅門係，你要清楚呢個製品想做啲咩，以及你會點樣用佢。也許隨住時間推移，你會總結出一套自己嘅技能模板，但係目前嚟講，我強烈建議你直接由最簡單嘅提示詞開始，慢慢摸索佢喺唔同場景下嘅奇妙用法。
使用場景 (Use Cases)
為咗令大家有更直觀嘅感受，我已經為各種唔同嘅使用場景整咗好多 HTML 文件。你可以在呢度睇曬所有範例：https://thariqs.github.io/html-effectiveness/ ，下面係對一啲核心場景嘅概覽。
需求、計劃與探索 (Specs, Planning & Exploration)
對 Claude 嚟講，HTML 係一塊可以深入探討問題嘅廣闊畫布。當接手一個新問題時，我唔再指望佢淨係掉一個單薄嘅 Markdown 計劃出嚟，而係期望佢生成一張由多個 HTML 文件交織而成嘅思考網絡。
例如，我會先叫 Claude Code 進行腦暴，探索幾種唔同嘅實現方案；然後，我會叫佢揀中其中一個方案深入發展，可能會叫佢畫啲界面草圖或者寫幾段核心代碼片段；最後，當我覺得方向啱咗，我先會叫佢寫出一份詳細嘅實施計劃。等我對計劃徹底滿意之後，我會開一個新對話，將呢啲積累落嚟嘅 HTML 文件全部餵畀佢，叫佢正式開始寫代碼。
喺驗證環節，我都會叫負責檢查嘅 AI 智能體對話讀取呢啲 HTML 文件，等佢可以擁有更宏大嘅全局視角，清楚我哋到底想做啲咩。
提示詞範例：
• 我仲未諗掂新手引導頁面 (Onboarding screen) 要行咩風格。請生成 6 種完全唔同嘅方案——喺佈局、語氣同資訊密度上做出差異——然後將佢哋放喺同一個 HTML 文件嘅網格佈局裏面，方便我並排對比。請喺每個方案旁邊清楚標註佢所做嘅取捨權衡。 • 請喺一個 HTML 文件裏面建立一份詳盡嘅實施計劃。記得畫啲視覺草圖，展示數據流向，仲要補充一啲我可能需要重點審查嘅代碼片段。排版要清晰，令人容易消化理解。
適用場景：
• 探索一段代碼嘅其他實現方式 • 並行探索多種視覺設計方案
代碼審查與理解 (Code Review & Understanding)
喺 Markdown 文件裏面生啃代碼絕對係一件痛苦嘅事。但係有咗 HTML，我哋就可以優雅咁渲染出代碼差異對比 (Diffs)、詳細嘅頁邊註釋 (Annotations)、流程圖 (Flowcharts) 同模塊結構圖等。
你可以用佢嚟理解 AI 智能體寫出嘅複雜代碼，獲取代碼審查建議，或者喺提交 PR (Pull Request，程式員提交代碼合併請求時嘅說明) 時向評審人解釋你嘅思路。我發現呢種方式往往比 GitHub 本身嘅差異對比視圖好用一萬倍，而家我每次提交 PR，都會硬性規定附帶一個 HTML 格式嘅代碼解讀頁面。
提示詞範例：
• 幫我審查呢個 PR，生成一個 HTML 製品嚟向我解釋佢嘅邏輯。我對數據流同背壓邏輯 (Backpressure，即係接收方處理唔切時向發送方發出減慢發送速率嘅反饋機制) 唔係好熟，所以請重點剖析呢部分。請渲染出真實嘅代碼差異，並喺旁邊加上行內註釋。根據嚴重程度對你發現嘅問題進行顏色編碼，仲可以加啲有助於傳達概念嘅視覺圖表。
適用場景：
• 建立 PR 嘅說明文檔 • 審查同事或 AI 提交嘅 PR • 快速理解代碼庫入面某個特定複雜主題
設計與原型製作 (Design & Prototypes)
Claude Design 嘅底層邏輯就係 HTML，因為就算你最終產品嘅渲染終端唔係網頁，HTML 喺表達設計理念方面仍然有無可比擬嘅優勢。Claude 可以先用 HTML 快速勾畫出設計草圖，然後再將佢翻譯成你需要嘅程式語言，無論係 React、Swift 定其他語言。
你仲可以用佢嚟製作絲滑嘅互動原型，例如動畫效果或用戶操作鏈路。不妨試嚇叫 Claude 幫你加啲滑塊同旋鈕，等你親自上手，將細節微調到你心目中最理想嘅狀態。
提示詞範例：
• 我想為一個新嘅結賬掣做個互動原型：㩒佢嗰陣，佢會播一段動畫，然後快速變成紫色。請生成一個有幾個滑塊同選項嘅 HTML 文件，令我可以反覆測試呢套動畫嘅唔同參數配置。記得畀我一個「複製」掣，方便將我試到覺得完美嘅參數一鍵複製落嚟。
適用場景：
• 建立設計系統 (Design system) 嘅相關組件資產 • 直觀咁微調 UI 組件細節 • 將沉悶嘅組件庫可視化展示 • 製作充滿樂趣嘅動畫互動原型
報告、研究與學習 (Reports, Research & Learning)
Claude Code 極之擅長整合海量嘅多源數據，並將佢哋提煉成可讀性極高嘅報告。你可以叫 Claude 去搜尋你嘅 Slack 聊天記錄、你嘅代碼庫、Git 提交歷史甚至成個互聯網，然後為你自己、你嘅領導或者你嘅團隊生成一份一目瞭然嘅精美報告。
你可以將佢排版成一篇長篇 HTML 文檔、一個帶互動嘅解說頁面，甚至一個投影片/簡報 (Deck)。唔好唔記得提醒 Claude 盡情用 SVG 格式嚟畫圖表，咁會令報告嘅視覺表現力瞬間爆燈。
例如，喺我寫關於提示詞緩存 (Prompt Caching) 嘅深度文章時，我叫 Claude 閲讀咗相關模塊嘅 Git 歷史記錄，然後生成咗一份深入嘅 HTML 研究報告，幫我有系統咁梳理我哋喺呢段時間對緩存邏輯做過嘅所有修改。
提示詞範例：
• 我一直搞唔明我哋嘅限流器 (Rate limiter) 到底係點運作。請閲讀相關代碼，並為我生成一個單頁嘅 HTML 講解文檔：包含一個令牌桶機制 (Token-bucket flow) 嘅數據流向圖、3 到 4 段附有詳細註釋嘅核心代碼片段，並喺頁面底部另列一個「常見陷阱 (Gotchas)」部分。請優化排版佈局，確保其他人只睇一次就徹底明。
適用場景：
• 總結某個複雜功能嘅運作原理 • 向我通俗解釋一個難明嘅概念 • 畀老細快速生成精美嘅週報 • 畀管理層出直觀嘅故障/事故事後檢討報告 • 自動繪製 SVG 插圖、流程圖同技術架構圖
自定義編輯界面 (Custom Editing Interfaces)
有時，就咁靠文字輸入框好難準確描述你嘅複雜需求。遇到呢種情況，我會叫 Claude 特別為我手頭上嘅工作，快速搭建一個「用完即棄」嘅臨時可視化編輯器。佢唔係一個成熟嘅產品，亦唔係一個可以重複使用嘅通用工具，只係一個專為呢批特定數據度身訂造嘅單一 HTML 文件。
呢度嘅核心竅門係，一定要喺界面上設計一個匯出功能：例如一個「複製為 JSON」或「複製為提示詞」嘅掣，咁你就可以將你喺呢個靚 UI 裏面一輪操作之後嘅成果，直接貼返落 Claude Code 度繼續下一步工作。
提示詞範例：
• 我需要重新梳理呢 30 個 Linear 任務單嘅優先級。請幫我整一個 HTML 文件，將每個任務變成一張可拖拽嘅卡片，橫跨分為「而家 (Now) / 下一步 (Next) / 遲啲先算 (Later) / 斬走 (Cut)」四個欄目。你可以根據你嘅理解先幫我預先排好次序。最後加一個「複製為 Markdown」嘅掣，一鍵匯出最終嘅分類排序結果，並為每個分類補充一句簡短嘅判斷理由。 • 呢度係我哋嘅功能開關 (Feature flag) 設定檔。請為佢生成一個基於表單嘅編輯器，按功能模組將開關合理分組，展示佢哋之間嘅依賴關係；如果我開咗一個開關，但佢嘅前置依賴開關仲係關緊，請彈窗警告我。最後加一個「複製差異」嘅掣，只匯出我修改過嘅鍵值對。 • 我正在調校呢個系統提示詞 (System prompt)。請做一個左右對照嘅編輯器：左邊係可編輯嘅提示詞模板，變量槽 (Variable slots) 要 highlight 顯示；右邊放 3 個範例輸入源，當我修改左邊嘅模板時，右邊要可以即時渲染出填入變量後嘅最終效果。界面上仲要有字符同 Token (大語言模型處理文本嘅基本單位) 嘅計數器，以及一個一鍵複製掣。
適用場景：
• 對任何事物進行重新排序、分類分流或分組（任務單、測試用例、用戶反饋） • 編輯結構化設定資訊（功能開關、環境變量、附帶複雜限制條件嘅 JSON/YAML） • 藉助即時預覽功能調校提示詞、模板或文案 • 整理數據集、批准/拒絕特定數據行、為範例加標籤並匯出揀選結果 • 為長文檔、錄音文稿或代碼差異加詳細備註，並匯出備註內容 • 揀選啲用純文字極之痛苦先描述到嘅參數：顏色代碼、動畫緩動曲線 (Easing curves)、裁剪區域、Cron 定時任務表達式 (用嚟設定伺服器定時執行任務嘅時間格式) 、正則表達式 (Regexes) 等。
常見問題解答 (Frequently Asked Questions)
我不斷向好多人推介我係點樣徹底轉投 HTML 陣營，期間成日被問到以下幾個高頻問題。
咁樣咪好嘥 Token 效率？
的確，Markdown 通常消耗嘅 Token 少啲。但我發現，HTML 極強嘅表現力同埋佢極高嘅人工閲讀率，令我整體上得到好得多嘅輸出結果。喺 Opus 4.7 模型高達 100 萬 (1MM) 嘅龐大上下文窗口裏面，多用嗰啲 Token 幾乎可以忽略不計。
咁你而家幾時仲會用 Markdown？
老實講，我而家幾乎做咩都用 Markdown 喇，不過我承認我可能已經喺「HTML 極端主義者」嘅路上行得太遠。
點樣睇生成嘅 HTML 文件？
我通常直接喺本地用瀏覽器打開佢（你亦可以直接叫 Claude 幫你打開）。如果想將連結俾人，直接傳上雲端 S3 就得。
生成出嚟咪比 Markdown 慢？
的確慢啲！生成 HTML 嘅時間可能係生成 Markdown 嘅 2 到 4 倍，但我親身試過，生成嘅結果絕對物超所值，值得等待。
咁版本控制點搞？
坦白講，呢個的確係 HTML 最大嘅痛點之一。相比起清爽嘅 Markdown，HTML 文件喺版本控制工具嘅差異對比 (Diffs) 非常雜亂，代碼審查起嚟比較頭痕。
點樣令 Claude 生成嘅頁面符合我嘅審美，唔會太樣衰？
Claude 內置嘅前端設計插件已經可以幫佢生成相當唔錯嘅 HTML 頁面。但如果你想令頁面完全配合你哋公司嘅品牌風格，你可以叫 Claude 掃描你哋嘅代碼庫，生成一個專屬嘅「設計系統 HTML 文件」。之後，你可以將呢個文件作為參考資料掉畀 Claude，等佢生成其他 HTML 頁面時「照辦煮碗」，保持風格高度一致。
保持人機協同 (Stay in the Loop)
講到最後，我覺得自己咁鍾意 HTML 嘅根本原因係：佢令我真切咁覺得，自己依然喺呢個循環入面，依然同 Claude 並肩作戰。
我之前曾經好驚，既然我連幾百行嘅 Markdown 計劃書都懶得仔細睇，咁以後係咪只能夠矇查查，任由 Claude 自己去盲目做決定？但而家我好開心咁話，因為有咗 HTML，我覺得自己比以往任何時候都更緊密咁參與咗呢段人機協同嘅創作旅程。
希望你都可以快啲體會到呢種樂趣。
原文：Using Claude Code: The Unreasonable Effectiveness of HTML
https://x.com/trq212/status/2052809885763747935
作者：Thariq
Markdown 已經成為 AI 智能體 (AI Agent) 與我們溝通時最常用的文件格式。它簡單、便攜、具備一定的富文本 (Rich text) 能力，而且極其容易進行人工修改。你甚至會發現，Claude 已經變得極其擅長在 Markdown 文件裏用 ASCII (美國信息交換標準代碼，這裏指用純文本符號拼湊成圖表) 字符來畫圖了。
但是，隨着 AI 智能體變得越來越強大，我開始覺得 Markdown 變成了一種束縛。面對動輒上百行的 Markdown 文件，我根本沒有耐心讀下去。我想要更豐富的視覺展現、明亮的色彩和直觀的圖表，而且希望能夠輕鬆地把它們分享給團隊。
另外，我現在越來越少親自去編輯這些文件了。我更多是把它們當作需求文檔 (Specs)、參考資料或是頭腦風暴的輸出結果。即使需要修改，我通常也是直接寫提示詞 (Prompt) 讓 Claude 去改。這就讓 Markdown 最核心的優勢——易於人工編輯——蕩然無存。
因此，相比 Markdown，我開始更偏愛將 HTML 作為輸出格式。我也發現 Claude Code 團隊的其他成員正越來越頻繁地使用 HTML。下面我想和大家聊聊背後的原因。
（如果你想先看些直觀的例子，可以點擊這裏查看大量示例：https://thariqs.github.io/html-effectiveness/ ，不過看完記得回來，聽我繼續講講為什麼該這麼做。）
為什麼選擇 HTML？
信息密度 (Information Density)
HTML 能比 Markdown 傳達豐富得多的信息。它當然能處理像標題和簡單排版這樣的基礎文檔結構，但它的威力遠不止於此，它還能完美呈現各種複雜信息，比如：
• 用表格 (Tables) 展示數據列 • 用 CSS (層疊樣式表，用於控制網頁的外觀和佈局) 展現設計細節 • 用 SVG (可縮放矢量圖形，一種基於代碼的清晰圖像格式) 繪製精美插圖 • 用 script 標籤嵌入代碼片段 (Code snippets) • 結合 HTML 元素、JavaScript 和 CSS 來實現動態交互 • 結合 SVG 和 HTML 繪製清晰的工作流圖表 (Workflows) • 用絕對定位和畫布 (Canvases) 展示空間分佈數據 • 用 image 標籤直接插入圖片
我甚至敢說：只要是 Claude 能讀懂的信息，幾乎沒有什麼是不能用 HTML 高效展現出來的。這種特性讓 HTML 成為了一種極為高效的載體，無論是模型向你傳遞深度的信息，還是你進行閲讀審查，都無比順暢。
我發現，如果無法使用 HTML，模型往往會在 Markdown 裏做一些極其低效的“騷操作”，比如硬用 ASCII 字符去畫圖表；或者——這也是我最哭笑不得的一種——像下面這張 Claude Code 截圖裏那樣，用 Unicode (統一碼) 字符來生硬地模擬顏色色塊。
視覺清晰度與易讀性 (Visual Clarity & Ease of Reading)
隨着 Claude 能夠處理越來越複雜的工作，它寫出的需求規格說明和實施計劃也變得越來越龐大。在實際工作中，我發現自己基本不會去讀超過 100 行的 Markdown 文件，更別提指望團隊裏的其他人去讀了。
但 HTML 文檔就好讀多了。Claude 可以通過選項卡 (Tabs)、插圖、連結等視覺元素，把文檔結構整理得井井有條，極其方便導航瀏覽。它甚至能做到移動端自適應，讓你在手機等不同尺寸的設備上都能獲得極佳的閲讀體驗。
易於分享 (Ease of Sharing)
分享 Markdown 文件其實挺讓人頭疼的，因為大多數瀏覽器本身並不能很好地渲染它們。你通常只能把它們當作附件，硬塞進電子郵件或聊天消息裏發給別人。
但有了 HTML，只要你把文件上傳到雲端（比如傳到雲存儲服務 S3 上），你就可以輕鬆地把連結分享出去。你的同事可以隨時隨地用任何設備打開它，並輕鬆作為參考。
如果你的需求文檔、分析報告或者代碼審查說明是用 HTML 寫的，別人真正去耐心閲讀它的概率絕對會大幅提升。
雙向交互 (Two-way Interaction)
HTML 允許你與文檔進行真實的互動。例如，你可以讓 Claude 在頁面上加幾個滑塊 (Sliders) 或旋鈕，用來直觀地調整設計效果；或者提供一些選項，讓你微調算法的參數，看看結果會發生什麼變化。你甚至可以要求它加個按鈕，讓你把微調後的完美參數“一鍵複製”為提示詞，直接粘貼回 Claude Code 裏去。
想了解更多關於這種雙向交互的例子，可以去讀讀我之前關於“遊樂場 (Playgrounds)”的帖子：https://x.com/trq212/status/2017024445244924382
數據攝取與理解 (Data Ingestion)
為什麼我們要用終端工具 Claude Code 來生成 HTML 文件，而不是直接用網頁版的 Claude AI 或者 Claude Design 呢？最大的原因之一，就在於 Claude Code 能夠攝取極其龐大的上下文 (Context) 信息。
拿寫這篇文章來說吧。我讓 Claude Code 自動遍歷我電腦裏的代碼文件夾，找出所有由它生成的 HTML 文件，對它們進行分組歸類，然後生成一個全新的 HTML 頁面，在裏面用圖表展示每一類文件的特徵。你在這篇文章裏看到的配圖，就是這個工作流的直接產物。
除了本地文件系統，Claude Code 還能通過你的 MCP (模型上下文協議，一種允許 AI 模型訪問外部工具和私有數據的標準) 接入其他極其豐富的上下文信息，比如 Slack (團隊通訊軟件) 聊天記錄、Linear (項目追蹤工具) 任務看板等。它還能結合瀏覽器、Git 版本控制歷史記錄等多種來源獲取背景知識。
充滿樂趣 (It’s Joyful)
用 Claude 製作 HTML 文檔本身就是一件極其好玩的事。它讓我感覺自己更深度地參與到了創造的過程中，光憑這份參與感，就足夠有吸引力了。
如何開始 (How to Get Started)
我其實有點擔心，大家讀完這篇文章後，會把它搞成一個專門的 /html 複雜技能指令或者類似的東西。雖然那樣做可能也有價值，但我特別想強調的是：你根本不需要做任何繁瑣的設置，就能讓 Claude 為你生成 HTML。你只需要像平時聊天一樣，直接告訴它：“給我做一個 HTML 文件”或者“生成一個 HTML 製品 (Artifact)”就行了。
真正的訣竅在於，你要清楚自己希望這個製品能做什麼，以及你會如何使用它。也許隨着時間的推移，你會總結出一套自己的技能模板，但就目前而言，我強烈建議你直接從最簡單的提示詞開始，慢慢摸索它在不同場景下的奇妙用法。
使用場景 (Use Cases)
為了讓大家有更直觀的感受，我已經為各種不同的使用場景製作了許多 HTML 文件。你可以在這裏查看所有示例：https://thariqs.github.io/html-effectiveness/ ，下面是對一些核心場景的概覽。
需求、計劃與探索 (Specs, Planning & Exploration)
對 Claude 來說，HTML 是一塊可以深入探討問題的廣闊畫布。當接手一個新問題時，我不再指望它只給我丟出一個單薄的 Markdown 計劃，而是期望它能生成一張由多個 HTML 文件交織而成的思考網絡。
比如，我會先讓 Claude Code 進行頭腦風暴，探索幾種不同的實現方案；接着，我會讓它選中其中一個方案深入展開，可能還會讓它畫些界面草圖或者寫幾段核心代碼片段；最後，當我覺得方向對了，我才會讓它寫出一份詳細的實施計劃。等我對計劃徹底滿意後，我會開啓一個新會話，把這些積累下來的 HTML 文件全部餵給它，讓它正式開始敲代碼。
在驗證環節，我也會讓負責檢查的 AI 智能體會話讀取這些 HTML 文件，這樣它就能擁有更宏偉的全局視角，清楚我們到底想要實現什麼。
提示詞示例：
• 我還沒想好新手引導頁面 (Onboarding screen) 要走什麼風格。請生成 6 種截然不同的方案——在佈局、語氣和信息密度上做出差異——並把它們放在同一個 HTML 文件的網格佈局裏，方便我並排對比。請在每個方案旁清晰標註它所做的取捨權衡。 • 請在一個 HTML 文件裏創建一份詳盡的實施計劃。記得畫一些視覺草圖，展示數據流向，並補充上我可能需要重點審查的代碼片段。排版要清晰，讓人容易消化理解。
適用場景：
• 探索一段代碼的其他實現方式 • 並行探索多種視覺設計方案
代碼審查與理解 (Code Review & Understanding)
在 Markdown 文件裏生啃代碼絕對是一件痛苦的事。但有了 HTML，我們就能優雅地渲染出代碼差異對比 (Diffs)、詳細的頁邊註釋 (Annotations)、流程圖 (Flowcharts) 以及模塊結構圖等。
你可以用它來理解 AI 智能體寫出的複雜代碼，獲取代碼審查建議，或者在提交 PR (Pull Request，程序員提交代碼合併請求時的說明) 時向評審人解釋你的思路。我發現這種方式往往比 GitHub 自帶的差異對比視圖好用一萬倍，現在我每次提交 PR，都會雷打不動地附帶一個 HTML 格式的代碼解讀頁面。
提示詞示例：
• 幫我審查這個 PR，生成一個 HTML 製品來向我解釋它的邏輯。我對數據流和背壓邏輯 (Backpressure，指接收方處理不過來時向發送方發出減緩發送速率的反饋機制) 不太熟悉，所以請重點剖析這部分。請渲染出真實的代碼差異，並在旁邊加上行內註釋。根據嚴重程度對你發現的問題進行顏色編碼，還可以加上任何有助於傳達概念的視覺圖表。
適用場景：
• 創建 PR 的說明文檔 • 審查同事或 AI 提交的 PR • 快速理解代碼庫中的某個特定複雜主題
設計與原型製作 (Design & Prototypes)
Claude Design 的底層邏輯就是 HTML，因為即使你最終產品的渲染終端不是網頁，HTML 在表達設計理念方面依然具有無可匹敵的優勢。Claude 可以先用 HTML 快速勾勒出設計草圖，然後再把它翻譯成你需要的編程語言，不管是 React、Swift 還是其他語言。
你還可以用它來製作絲滑的交互原型，比如動畫效果或用戶操作鏈路。不妨試着讓 Claude 幫你加上一些滑塊和旋鈕，這樣你就能親自上手，把細節微調到你心目中的完美狀態。
提示詞示例：
• 我想為一個新的結賬按鈕做個交互原型：點擊它時，它會播放一段動畫，然後迅速變成紫色。請生成一個帶有幾個滑塊和選項的 HTML 文件，讓我能反覆測試這套動畫的不同參數配置。記得給我提供一個“複製”按鈕，方便我把試出來覺得完美的參數一鍵複製下來。
適用場景：
• 創建設計系統 (Design system) 的相關組件資產 • 直觀地微調 UI 組件細節 • 將枯燥的組件庫可視化展現 • 製作充滿樂趣的動畫交互原型
報告、研究與學習 (Reports, Research & Learning)
Claude Code 極其擅長整合海量的多源數據，並將它們提煉成可讀性極強的報告。你可以讓 Claude 去搜索你的 Slack 聊天記錄、你的代碼庫、Git 提交歷史甚至整個互聯網，然後為你自己、你的領導或者你的團隊生成一份一目瞭然的精美報告。
你可以將它排版成一篇長篇 HTML 文檔、一個帶交互的解說頁面，甚至是一個幻燈片/演示文稿 (Deck)。別忘了提醒 Claude 盡情使用 SVG 格式來繪製圖表，這會讓報告的視覺表現力瞬間拉滿。
例如，在我撰寫關於提示詞緩存 (Prompt Caching) 的深度文章時，我讓 Claude 閲讀了相關模塊的 Git 歷史記錄，然後生成了一份深度的 HTML 研究報告，幫我係統梳理了我們在此期間對緩存邏輯做過的所有修改。
提示詞示例：
• 我一直搞不懂我們的限流器 (Rate limiter) 到底是怎麼工作的。請閲讀相關代碼，併為我生成一個單頁的 HTML 講解文檔：包含一個令牌桶機制 (Token-bucket flow) 的數據流向圖、3 到 4 段帶有詳細註釋的核心代碼片段，並在頁面底部單列一個“常見陷阱 (Gotchas)”部分。請優化排版佈局，確保別人只讀一遍就能徹底弄懂。
適用場景：
• 總結某個複雜功能的工作原理 • 向我通俗解釋一個晦澀的概念 • 給老闆快速生成精美的本週工作彙報 • 給領導層出具直觀的故障/事故覆盤報告 • 自動繪製 SVG 插圖、流程圖和技術架構圖
自定義編輯界面 (Custom Editing Interfaces)
有時候，單純靠文字輸入框很難準確描述你的複雜需求。遇到這種情況，我會讓 Claude 專門為我手頭上的工作，快速搭建一個“用完即走”的臨時可視化編輯器。它不是一個成熟的產品，也不是一個可以反覆利用的通用工具，僅僅是一個專為這批特定數據量身定製的單一 HTML 文件。
這裏的核心竅門在於，一定要在界面上設計一個導出功能：比如一個“複製為 JSON”或“複製為提示詞”的按鈕，這樣你就能把你在這個精美 UI 裏一頓操作後的成果，直接粘貼回 Claude Code 裏繼續下一步工作。
提示詞示例：
• 我需要重新梳理這 30 個 Linear 任務單的優先級。請給我做一個 HTML 文件，把每個任務做成一張可拖拽的卡片，橫跨分為“現在 (Now) / 接下來 (Next) / 以後再說 (Later) / 砍掉 (Cut)”四個欄目。你可以根據你的理解先幫我預先排序好。最後加一個“複製為 Markdown”的按鈕，一鍵導出最終的分類排序結果，並且為每個分類補充一句簡短的判斷理由。 • 這裏是我們的功能開關 (Feature flag) 配置文件。請為它生成一個基於表單的編輯器，按功能模塊對開關進行合理分組，展示它們之間的依賴關係；如果我打開了一個開關，但它的前置依賴開關還處於關閉狀態，請彈窗警告我。最後加一個“複製差異”的按鈕，只導出我修改過的鍵值對。 • 我正在調優這個系統提示詞 (System prompt)。請做一個左右對照的編輯器：左邊是可編輯的提示詞模板，變量槽 (Variable slots) 要高亮顯示；右邊放 3 個示例輸入源，當我修改左邊的模板時，右邊要能實時渲染出填入變量後的最終效果。界面上還要有字符和 Token (大語言模型處理文本的基本單位) 的計數器，以及一個一鍵複製按鈕。
適用場景：
• 對任何事物進行重新排序、分類分診或分組（任務單、測試用例、用戶反饋） • 編輯結構化配置信息（功能開關、環境變量、帶有複雜約束條件的 JSON/YAML） • 藉助實時預覽功能調優提示詞、模板或文案 • 整理數據集、批准/拒絕特定數據行、給示例打標籤並導出選中結果 • 為長文檔、錄音文稿或代碼差異添加詳細批註，並導出批註內容 • 挑選那些用純文字極其痛苦才能描述清楚的參數：顏色代碼、動畫緩動曲線 (Easing curves)、裁剪區域、Cron 定時任務表達式 (用於配置服務器定時執行任務的時間格式) 、正則表達式 (Regexes) 等。
常見問題解答 (Frequently Asked Questions)
我一直在向很多人安利我是如何徹底倒向 HTML 陣營的，期間也經常被問到以下幾個高頻問題。
這樣不會很浪費 Token 效率嗎？
確實，Markdown 通常消耗的 Token 更少。但我發現，HTML 極強的表現力以及它極高的人工閲讀率，讓我整體上獲得了好得多的輸出結果。在 Opus 4.7 模型高達 100 萬 (1MM) 的龐大上下文窗口裏，多花的這點 Token 幾乎是可以忽略不計的。
那你現在什麼時候還會用 Markdown？
說實話，我現在幾乎幹什麼都不用 Markdown 了，不過我承認我可能已經在“HTML 極端主義者”的道路上走得太遠了。
怎麼查看生成的 HTML 文件？
我通常直接在本地用瀏覽器打開它（你也可以直接讓 Claude 幫你打開）。如果想把連結發給別人，直接傳到雲端 S3 上就行。
這生成起來不比 Markdown 慢嗎？
確實更慢！生成 HTML 的時間可能是生成 Markdown 的 2 到 4 倍，但我親身測試下來，生成的結果絕對物超所值，值得等待。
那版本控制怎麼辦？
老實說，這確實是 HTML 最大的痛點之一。相比起清爽的 Markdown，HTML 文件在版本控制工具裏的差異對比 (Diffs) 非常雜亂，代碼審查起來比較頭疼。
怎麼讓 Claude 生成的頁面符合我的審美，不至於太醜？
Claude 內置的前端設計插件已經能幫它生成相當不錯的 HTML 頁面了。但如果你想讓頁面完全契合你們公司的品牌風格，你可以讓 Claude 掃描你們的代碼庫，生成一個專屬的“設計系統 HTML 文件”。之後，你可以把這個文件作為參考資料丟給 Claude，讓它在生成其他 HTML 頁面時“照貓畫虎”，保持風格的高度一致。
保持人機協同 (Stay in the Loop)
說到底，我覺得自己如此鍾愛 HTML 的根本原因在於：它讓我真切地感覺到，自己依然在這個循環之中，依然在與 Claude 並肩作戰。
我之前一度很恐懼，既然我連幾百行的 Markdown 計劃書都懶得仔細看了，那以後是不是隻能兩眼一抹黑，任由 Claude 自己去盲目做決定了？但現在我很高興地說，因為有了 HTML，我感覺自己比以往任何時候都更緊密地參與到了這段人機協同的創作旅程中。
希望你也能儘快體會到這種樂趣。
原文：Using Claude Code: The Unreasonable Effectiveness of HTML
https://x.com/trq212/status/2052809885763747935