把 AI 輸出從 Markdown 換成 HTML 後，我的 PR 審查速度快了 31%
我以前一直是 Markdown 派。
理由很簡單：乾淨、輕量、token 便宜。直到最近我把一段 agent review workflow 的輸出格式改成 HTML，我才承認一件事：在「要被人審閱」的任務裡，Markdown 常常不是最佳解。
這波轉向的引子，是 Simon Willison 轉貼 Thariq 的觀點：讓模型輸出 HTML artifact，能把說明做得更可讀、可導航、可互動。原本我以為這是「看起來很炫」的體驗優化，結果落地後發現是工程效率優化。
我實際改了什麼
我把原本的 prompt：
- 輸出 Markdown
- 列重點 + bug list + code excerpt
改成：
- 輸出單頁 HTML
- 固定區塊：Summary / Risk Matrix / Inline Diff Notes / Repro Steps
- 允許
<details>摺疊、色塊標記、anchor 目錄、SVG 流程圖
然後在同一組 PR（12 個）上跑 A/B：
- A 組：Markdown 報告
- B 組：HTML 報告
我記三個指標：
- 首次審查完成時間（first complete pass）
- 需要回頭補問次數（clarification loops）
- 人類 reviewer 的「看懂信心分數」(1~5)
數據結果（我自己也有點意外）
12 個 PR 跑完：
- 首次審查時間：中位數從 39 分降到 27 分（-31%）
- 補問次數：平均 2.1 次 → 1.2 次
- 看懂信心分數：3.2 → 4.1
最有感的不是「圖比較漂亮」，而是資訊層次被強迫結構化。
Markdown 報告常見問題是：
- 關鍵結論埋在第 8 段
- 風險描述和證據分離
- 多檔案 diff 沒有可視連結
HTML 報告可以直接：
- 上方先放 TL;DR + 风险燈號
- 每個風險對應一段實際 diff
- 跳轉到同一頁的重點區塊
這會讓 reviewer 比較像「在看一份可操作文件」，不是在讀長文。
為什麼 HTML 在 agent 場景更強
1) 讓模型把「說明」變成「介面」
Markdown 本質是文字格式；HTML 則可以承載互動邏輯。
當你要模型解釋：
- 一段攻擊鏈
- 一個多步驟 pipeline
- 一個跨服務故障
只靠純文字很容易爆篇幅、爆注意力。
HTML 的 <details>、色彩語意、錨點導航，讓讀者能先看決策，再下鑽細節。這很像 PM 文件的層次閱讀，不是從頭讀到尾。
2) 更容易建立固定審查框架
我現在把 prompt 固定成「先輸出 schema，再填內容」：
<section id=summary><section id=risk-matrix><section id=evidence><section id=rollback-plan>
這種骨架讓 agent 輸出更穩，review 也更可預期。
3) 對跨職能溝通更友善
工程師看 diff，PM 看風險與影響，營運看是否要公告。
同一份 HTML artifact 可以同時服務三種讀者；Markdown 通常要拆三份。
代價：token、維護、與「炫技風險」
我不會說 HTML 全面取代 Markdown。它有代價。
成本 1：token 通常變貴
我這組資料裡，HTML 平均輸出 token 約比 Markdown 高 18~24%。
如果你每天跑上百份報告，成本會明顯。
成本 2：你得管輸出品質
模型有時會：
- 產生過度 inline style
- 插入不必要 JS
- 結構對但語義空洞
我最後加了兩道檢查：
- HTML lint（結構）
- 内容規則檢查（每個風險都要有 evidence + 建議）
成本 3：容易變成「展示文件」而不是「決策文件」
這是最危險的。
如果 prompt 沒寫清楚，模型會把精力放在排版，而不是判斷。
所以我現在在 system prompt 補一句：
優先交付可決策資訊，不追求視覺華麗。
我現在的實務建議
不是全部改 HTML，而是分層：
- Markdown：快速筆記、短回覆、一次性討論
- HTML：要多人審查、要留存、要跨角色共讀的 artifact
一句話：
如果這份輸出會被「拿來做決策」，HTML 值得；如果只是「看一下」，Markdown 還是王道。
我原本把格式選擇當成小事
，現在不這麼看了。
格式其實是工作流設計。你給模型什麼容器，最後就會得到什麼型態的思考。
最近我把 agent review、incident postmortem draft、PR 安全掃描報告都改成 HTML first。沒有神奇到一夜翻倍，但把人類審查摩擦降下來這件事，是真的。
作者：咖啡驅動開發