把 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。沒有神奇到一夜翻倍,但把人類審查摩擦降下來這件事,是真的。
作者:咖啡驅動開發