让 Claude Code 审一个 PR，得到的往往是一大段 Markdown：几百行 diff 解释夹着代码块，信息都在，但哪几行是真正危险的改动，要读好几分钟才找得出来。

换一种输出格式，体验会差很多：同一个 PR，让它输出一个 HTML 页面，高风险改动标红、需要注意的标黄，diff 旁边挂着批注，顶部一张严重程度汇总表，浏览器打开几秒就能扫完重点。这个做法来自 Anthropic Claude Code 团队的 Thariq Shihipar，他在官方博客文章《Using Claude Code: The unreasonable effectiveness of HTML》里系统讲了团队为什么越来越多地让 Claude 输出 HTML。Django 联合创始人 Simon Willison 读完也说，自己从 GPT-4 时代起就默认要 Markdown，现在要重新考虑了。

这篇讲 Markdown 的局限在哪、Claude Code 输出 HTML 适合哪些场景、每个场景的提示词怎么写，以及这种做法的代价。

Markdown 的问题出在哪

先说清楚：这里不是让 Claude 帮你做网站，而是让它在给你解释东西、写方案、做审查时，用 HTML 来呈现。

Markdown 只有标题、段落、列表和代码块，从头到尾一条线。可很多技术信息本来就是二维的：

diff 是左右对照的；
架构是方块加箭头；
设计系统是一排排色卡；
流程图有分支和判断。

Markdown 把这些压成了一维，信息还在，结构没了。Thariq 在文章里提到，他很难读完一个超过一百行的 Markdown 文件，而模型在 Markdown 里只能用 ASCII 画图、用字符去「描述」颜色。

换成 HTML，Claude 能用的手段多了很多：

内联 SVG 画流程图和架构图，不需要 Mermaid 或别的插件；
折叠面板分层展示，想看哪层点开哪层；
用颜色区分严重程度；
多个 tab 或多栏并排放几个方案；
加一点 JS 做滑块、动画这类交互。

Claude Code 输出 HTML 的 6 个场景

Thariq 配套整理了 20 个由 Agent 生成的自包含 HTML 示例（thariqs.github.io/html-effectiveness），下面挑开发中最常用的 6 个，每个给一段可以直接改的提示词。

1. 代码审查

帮我审查这个 PR，输出一个 HTML 页面：渲染真实的 diff，
在行内用页边批注标出问题，按严重程度用颜色分级。

结果是彩色 diff、行内批注加一张汇总表，比纯文本的 review comment 更容易抓重点。如果你更关心审查之后怎么批量改，可以配合 Claude Code simplify 与 batch 教程里的流程。

2. 方案对比

我在考虑这三种数据库方案，帮我生成一个 HTML 对比页面，
每个方案一栏，写清优缺点、适用场景和预估成本。

三个方案并排摆着，你可以直接指着其中一个说「展开讲讲这个」，不用在脑子里同时记住三段文字。

3. 架构图

画一个这个系统的架构图，用内联 SVG，不要用 Mermaid，
模块之间的数据流用箭头标注。

输出的是矢量图，可以直接放进文档。

4. 学习新概念

解释 RAG 的工作原理，输出 HTML。用折叠面板分层，
每层可以点开看更多细节，侧边放一个术语表。

概念之间有依赖关系时，分层导航比线性的教程更好读。

5. 设计系统

把我们的设计 token 渲染成一个 HTML 色板页面，
每个颜色显示色值、使用场景和对比度评分。

颜色这种信息，用文字描述再多也不如直接看到。

6. 临时幻灯片

几个 section 标签加一小段 JS，就是一个能用方向键翻页的演示稿。开会前让 Claude 把设计文档转成幻灯片，不用再开 Keynote。

怎么让 Claude Code 稳定输出 HTML

明确写出格式要求。 不说的话，Claude 默认还是给 Markdown。在提示词末尾加一句就够：

Output as a self-contained HTML file with inline CSS and SVG diagrams.

「self-contained」很关键：生成的 HTML 不依赖外部 CSS 和 JS，双击文件就能在浏览器里打开，也方便发给同事或提交到仓库。

在命令行里一次生成。 用 claude -p 非交互模式，让它直接把结果写成文件：

claude -p "读取 some_code.py，解释这段代码的执行流程，用颜色标出关键路径、用折叠面板展示细节，输出成一个自包含的 HTML 文件，保存为 explanation.html"

生成后在浏览器里打开 explanation.html 即可。

让 HTML 变成临时工具。 还可以让 Claude 做一个一次性的小界面，比如拖拽排序列表、参数调节面板，末尾放一个「导出」按钮。你在界面里调好，点导出，再把结果贴回给 Claude 继续下一步。人仍然在循环里，只是来回更快了。

限制与注意事项

更费 token：同样的内容，HTML 比 Markdown 长不少，长会话里要留意上下文和用量。
源码不好读、不好 diff：HTML 适合给人看，不适合当需要频繁手改、在 git 里逐行对比的文档。Thariq 的说法是，他现在多数时候让 Claude 去改这些文件，而不是自己手改。
注意来源安全：不要随手打开来源不明、带脚本的 HTML；团队共享时最好约定只用内联 CSS 和 SVG。
不是所有输出都要换：短回答、命令说明、需要被其他工具解析的内容，Markdown 仍然更合适。

总结

这个技巧的关键不在 HTML 本身，而在于意识到：和 AI 沟通时，输出格式也是一种工具选择。Markdown 适合写给人改的文档，HTML 适合交给浏览器渲染、给人快速看懂。代码审查、方案对比、架构图、概念讲解这几类场景，可以先在提示词末尾加一句 self-contained HTML 试试。

想直接上手，可以在 AIGoCode 上接入 Claude Code，用上面的提示词跑一遍自己的项目。

参考链接

Thariq Shihipar：Using Claude Code: The unreasonable effectiveness of HTML（claude.dev 博客）
20 个 HTML 示例：https://thariqs.github.io/html-effectiveness/
Simon Willison 的评论：https://simonwillison.net/2026/May/8/unreasonable-effectiveness-of-html/