智東西
作者 江宇
編輯 漠影

Agent越來越能干，但它寫出的長文檔，人類還看得完嗎？

智東西5月11日報道，近日，Claude Code工程師Thariq Shihipar發布長文《Using Claude Code: The Unreasonable Effectiveness of HTML》（《在Claude Code工作流中，HTML為何“不講道理地好用”》），給出了一個答案：相比Markdown，HTML正在成為他更常使用的Agent輸出格式。

截至目前，這篇文章在X上的瀏覽量已超過950萬，近3000人收藏。從Markdown轉向HTML，這種看似簡單的變化，究竟能給AI Agent工作流帶來什么不同？

在這篇文章中，Thariq Shihipar分享了幾項核心觀點。

1、Markdown雖然簡單、便攜，但當Agent開始生成長規格文檔、復雜計劃和研究報告時，Markdown的閱讀體驗和信息承載能力正在變弱。

2、HTML能承載表格、CSS設計、SVG圖示、交互組件、圖片、代碼片段和空間布局，信息密度比Markdown更高。

3、HTML不只是“花哨好看”，還可以讓Agent輸出變成一個可閱讀、可分享、可交互的工作界面。

4、在規格規劃、代碼評審、設計原型、研究報告和臨時編輯器等場景中，HTML比Markdown更適合承載復雜信息。

5、HTML的真正價值，是讓用戶重新進入Agent工作流。

Thariq Shihipar也承認，HTML生成速度更慢，版本控制更麻煩，但他認為，只要結果更容易被讀完、理解和使用，這些代價就是值得的。

以下是這篇文章的核心內容。

一、Agent越會寫，Markdown越不夠看了

在Thariq Shihipar看來，Markdown過去之所以成為Agent輸出的主流格式，是因為它足夠簡單、便攜，也方便人類編輯。Claude已經很擅長在Markdown文件里用ASCII字符畫圖，把一些結構和流程解釋清楚。

但問題在于，Agent正在做越來越復雜的工作。它不再只是回答一個問題、列一個清單，而是開始生成上百行的規格文檔、實現計劃、研究報告和代碼解釋。

Thariq Shihipar坦言，自己很難認真讀完一份超過100行的Markdown文件，更不用說讓組織里的其他同事也讀完。

與此同時，他也發現，自己越來越少親手編輯這些文件。很多Markdown文檔只是被用作規格說明、參考資料、頭腦風暴結果或匯報材料。即便真的要修改，他通常也會繼續提示Claude去改，而不是自己打開文件逐行編輯。

這意味著，Markdown最大的優勢之一正在變弱。它原本勝在“人能方便編輯”，但在Agent工作流里，人類越來越多是在審閱、理解和反饋，而不是直接改文檔。

于是，Markdown在視覺組織、信息呈現和復雜表達上的短板，就變得越來越明顯。

二、HTML的關鍵優勢，在于把復雜信息講清楚

Thariq Shihipar轉向HTML，也并不是因為HTML看起來更花哨，而是因為它能承載更多類型的信息。

Markdown可以寫標題、列表、加粗和代碼塊，但HTML能表達的東西要多得多。它可以用表格展示結構化數據，用CSS呈現設計信息，用SVG畫插圖，用腳本嵌入代碼片段，也可以加入滑塊、按鈕、標簽頁等交互元素。對工作流、空間布局、圖片、畫布和復雜頁面結構，HTML也有更強的表達能力。

他甚至認為，只要Claude能讀取的信息，幾乎都可以被相對高效地表示成HTML。換句話說，HTML給Agent提供了一塊更大的表達畫布。

在Markdown里，Agent面對復雜信息時常常會變得笨拙。比如用ASCII字符畫流程圖，或者用Unicode字符近似表達顏色。這些方法不是不能用，但它們更像是在用文本硬湊視覺效果。一旦內容變復雜，讀者很快就會失去耐心。

▲Claude Code試圖在Markdown中展示顏色

HTML的價值就在這里。它可以把信息拆成更容易閱讀的模塊，也可以通過圖示、顏色、布局和交互降低理解成本。

對Agent來說，這是一種更高效的表達方式；對用戶來說，這也是一種更容易看進去的閱讀方式。

▲同樣的信息，HTML換成了更適合閱讀的結構

三、從方案規劃到代碼評審，HTML可以成為“工作看板”

在實際使用中，Thariq Shihipar最常把HTML用于規格文檔、方案規劃和探索性工作。

當他開始處理一個問題時，他不再期待Claude Code只生成一份Markdown計劃，而是希望它生成一組HTML文件。

比如先讓Claude Code探索多個方案方向，再展開其中一個方向，補充界面草圖、數據流圖和關鍵代碼片段，最后再形成一份實現計劃。等方案確認后，他會開啟新的Claude Code會話，把這些HTML文件作為上下文交給Agent繼續執行。

▲通過HTML生成可交互調節面板后，用戶可以調整參數，再將結果復制回Claude Code執行

這套流程的好處是，規劃不再是一段段文字，而是變成了更接近“工作看板”的東西。不同方案可以并排比較，關鍵取舍可以直接標出來，數據流和模塊關系也可以用圖示呈現。用戶能更快理解Agent到底在怎么想、準備怎么做。

▲可將不同實現方案整理成并排對比頁面，方便用戶查看各方案的取舍并選擇后續方向

代碼評審也是類似邏輯。Thariq Shihipar認為，代碼和diff放在Markdown里并不好讀，但HTML可以渲染差異、加入旁注、畫出流程圖和模塊關系，還可以用顏色區分問題嚴重程度。他提到，自己現在會給每個PR都附上一份HTML代碼解釋文件。

▲代碼評審將代碼diff、問題標注和修改建議整合到同一頁面中

這其實把Agent輸出從“解釋給你聽”，升級為“整理給你看”。它還把變化、風險、上下文和關鍵邏輯放在一個更容易審閱的界面里。對復雜PR、陌生模塊或多人協作來說，這種呈現方式明顯比一長段Markdown說明更清晰、易懂。

四、HTML還能變成一次性的臨時工具

更具啟發性的是，Thariq Shihipar不只把HTML當成文檔，也把它當成臨時編輯器。

他說，有些需求很難只靠文本框描述清楚。比如重新排列30個Linear工單、調整功能開關配置、調試系統提示詞、篩選數據集、標注文檔，或者選擇顏色、緩動曲線、裁剪區域、Cron表達式和正則規則。這些任務如果只用文字來回描述，效率很低，也容易說不清楚。

他的做法是，讓Claude Code直接生成一個“用完即扔”的HTML編輯器。這個編輯器不是正式產品，也不需要長期維護，只服務于當前這一件事。

▲設計方向的臨時編輯器，包含顏色、字體、按鈕和間距規范等

再比如，他可以讓Claude把30個Linear工單做成可拖拽卡片，分成Now、Next、Later、Cut幾欄，并加入“復制為Markdown”的按鈕。

他也可以讓Claude針對一份feature flag配置生成表單式編輯器，展示不同開關之間的依賴關系，并提醒某個前置開關是否未開啟。

同樣，他還可以讓Claude做一個提示詞調試界面，左側編輯prompt，右側實時預覽不同輸入下的填充結果，并提供token計數和復制按鈕。

▲提示詞調試的臨時編輯器

這類HTML文件的關鍵不是“編輯”，而是“導出”。用戶在界面里完成調整后，可以一鍵復制成JSON、Markdown、diff或prompt，再粘貼回Claude Code繼續執行。這樣一來，HTML就不只是Agent給人看的結果，也變成了人向Agent反饋結構化信息的中間層。

▲提示詞臨時編輯器，直接導出Prompt

五、讓人重新跟上Agent的工作過程

Thariq Shihipar在文章結尾提到，自己使用HTML最核心的原因，是它讓他在Claude工作流中更有參與感。

隨著Agent能力增強，用戶可能越來越少認真閱讀Agent生成的計劃，只是把任務交給它執行。表面上看，這提高了效率；但另一面是，人可能逐漸脫離Agent的決策過程。Agent為什么這樣做、哪里需要判斷、方案之間有什么取舍，都容易被藏在一大段沒人愿意讀完的文本里。

HTML在一定程度上解決了這個問題。它讓計劃、報告、代碼解釋和設計探索更容易閱讀，也讓用戶可以通過滑塊、按鈕、拖拽、表單等方式參與調整。相比一份長Markdown，HTML更像一個可操作的協作界面。

當然，HTML也有明顯代價。Thariq Shihipar承認，HTML生成時間通常比Markdown長，可能需要2到4倍時間；HTML的版本控制也更麻煩，diff往往嘈雜，不如Markdown容易審閱。

不過在他看來，只要最終產物更容易被真正讀完、理解和使用，這些成本就是值得的。