HTML 将成为新的 Markdown？

有没有发现，Markdown 文档，正在变得越来越长？

一个文档的旅程想法诞生口喷 10 分钟文档膨胀300行500行1000行交接交给你了崩溃好长啊...收到!你要 review... 按住看完整旅程 →

我最近做了些调整：当有了一个新的想法或一件新的事情要做，如果不是我让 AI 直接就能干完的、复杂度较高的，我会给 AI 连续口喷 10 分钟数千字，然后让它帮我把想法完善。

完善的过程，我会和多个 AI 进行深入的讨论，会交替使用 Claude Code 和 Codex，并最终给出一个文档。

这个文档可能会有三五百行，甚至 1000 多行。

我的习惯上，我更倾向于让 AI 一次性解决一个很大、很完整的功能，或者一堆小需求小 bug 的大集合（比如“请完成如下所有任务”——大约有 20 个这样）。

在这里，我已经不太喜欢小步快跑了，而是一次性让 AI 完成较大的任务。原因在于，AI 已经具备一次性完成复杂任务的水平了。而我则需要减少与 AI 沟通的频率，减少我在其中 loop 的次数。

这虽然很好理解，但我还是举个例子。

买菜 vs AI coding 的往返对比

假如你要去菜市场买菜，你显然是不会先买一棵白菜回家，然后再去买一个西红柿回家，然后再买一次辣椒回家；你会一次性在菜市场买好，然后全部带回家，这样可以大大减少你在路上的时间。

但如果你买好到家后发现漏了个什么没买，你会骂自己一句 SB，然后再跑一趟……

而在 AI coding 的过程中，这“路上的时间”也就是 AI 说：“我干完了，你来看看。”后你得一次又一次对这些小任务进行的多次检查验收。

所以在准备好这个很长的 Markdown 文档之后，偷懒的我一般会开一个分支，然后交给团队里的某位同学去完成。这里我不是直接自己完成，是因为在 AI 完成之后，我需要去验收，然后发布到生产，还要增加相关的数据统计，并持续地进行数据分析和效果追踪。

虽然我是省事了，但是看这么一个大文档，确实还是很有压力的。

我发现接手的人要么就不会一行一行看，要么会认真且很头疼地看。更多时候，我发现他们会直接扔给 AI 进行讨论分析然后开干。

但我其实，更希望接手的人能有一些不同的意见和观点，在方案环节就进行 review 提出大的质疑和建议，而不是完成之后再 review 出我初始方案中的问题，让问题更能左移而非右移。

这里我们会习惯性地选择 Markdown，原因在于它确实轻量、通用、够用，且 AI 和 AI 之间传递信息也足够顺畅。

# Title50 行# Spec## Sec 1## Sec 2200 行# Design## Overview## Arch## API500 行# Tech Plan## Background## Goals## Design## Testing1000 行还有214行……# Title50 行# Spec## Sec 1## Sec 2200 行# Design## Overview## Arch## API500 行# Tech Plan## Background## Goals## Design## Testing1000 行还有214行……AI看不完……文档传送带 ←←←

但看一份详细的 Markdown 文档，实在是太不容易了。

几百行、上千行，一个大项目的技术方案，终于写好了，但问题也来了：你/其他人真的会从头到尾读完吗？

虽然我在给 AI 的指令中带上的最多的，就是“精炼”这个词了，我会经常说“用精炼的文字给出，不要无用的废话”。

对应的就是，现在用 AI 写本书真的越来越容易了（不要觉得写书的人多牛逼了……我就拒绝了好多出版社的写书邀约），如何在和人进行信息传递时，使用精炼的语言、更少的 token 来表达同样的内容，反而是 AI 时代更为重要的一项技能了。

同样的内容，不同的交付

但即使如此，我和 AI 最后产出的文档，还是会长到自己都看不过来，甚至不小心里面还会藏着一些前后矛盾的地方。

我一直在琢磨怎么改进这件事。

然后昨天，我看到 Claude Code 的工程师 Thariq Shihipar 发了篇文章，讲的也正是这件事情。

01关于 Thariq Shihipar

Thariq Shihipar，Anthropic 的 Claude Code 团队成员。

Thariq 的小头像

他的履历可以说是非常丰富：MIT Media Lab 硕士毕业，YC W20 的创业者，创办过一家拿了 1700 万美元融资的游戏公司，卖掉过一个 SaaS 产品，做过非营利组织。

Thariq 文章封面

大概一年多前，Thariq 加入了 Anthropic，据他自己说的是：因为「AI 精神病」发作，觉得 Claude Code 就是软件开发的未来，于是放下一切 all in 了进来。

他在 Claude Code 团队里有一个你一定会知道的贡献：设计了「ask user question」工具，也就是让 Claude 在 Plan 模式下可以反过来向用户提问、澄清需求的那个功能。

他在 X 上发了一篇长文，标题叫：

Using Claude Code: The Unreasonable Effectiveness of HTML

即：HTML 不讲道理的好用。

Thariq 在推文中说道：

“ HTML is the new markdown. I've stopped writing markdown files for almost everything and switched to using Claude Code to generate HTML for me.

HTML 是新的 Markdown。我已经几乎不写 Markdown 文件了，全部换成让 Claude Code 给我生成 HTML。

这篇文章很快在开发者社区里引发了大量讨论，我们一起来看一看。

02为什么是 HTML

Thariq 的核心论点，可以用一张图来概括：

Markdown vs HTML 对比

左边是一个 240 行的 Markdown 文件，底部写着「还有 214 行」。

右边是同样的内容，用 HTML 呈现：有 tab 切换、有数据图表、有关键指标高亮。同样的信息，一个是让你滚动阅读的文档，一个是让你扫一眼就能抓住重点的页面。

他在文章中列了几个核心理由。

03信息密度

HTML 能承载的信息类型，比 Markdown 丰富太多了。

HTML 的八种信息类型

表格、CSS 样式、SVG 插图、代码高亮、交互组件、工作流程图、空间布局、嵌入图片，一个 HTML 文件就能全装下。

Thariq 的原话是：

“ 几乎不存在 Claude 能读懂但 HTML 表达不了的信息。”

而 Markdown 呢？

想要展示个颜色时，只能用 Unicode 字符去「估算」。Thariq 贴了一张 Claude Code 在终端里试图展示色板的截图：

Markdown 里的色板

怎么说呢……精神可嘉、想法很好、效果感人。

04读不动的方案

随着 Claude 能处理的任务越来越复杂，它写的方案和规格文档也越来越长。

Thariq 坦言：

“ 超过 100 行的 Markdown 文件，我基本不会认真读完。更别提让团队里其他人去读了。”

这和我前面说的情况，简直是一模一样。

HTML 的好处在于，Claude 可以用 tab 页、导航链接、折叠面板这些方式来组织内容，读者不需要从头滚到尾，而是像浏览一个网页一样，按需跳转。

甚至还能做成响应式的，手机上看也没问题。

还有 214 行...概览详情日志架构API部署FAQ展开▸一目了然 点击切换 → 05分享门槛

Markdown 文件其实挺有些不方便，因为大部分浏览器不会原生渲染 Markdown，你往往得把它当成附件发送出去，或者贴到飞书 / notion 这样原生支持 markdown 的在线文档里。

但 HTML 呢？上传到 S3 后发个链接，或者本地局域网开个 192.168.1.xxx:8080/xxx.html 就行。

（注意：不能是 localhost:8080/xxx.html）

梗图，取自网络

同事打开就能看，不需要任何额外工具。

Thariq 表示：

“ 如果你的方案是 HTML 格式的，别人真的会去看的概率，比 Markdown 高得多。”

这一点，非常实用。

交互式调参面板

上图展示的是一个按钮悬浮动画的调参界面。左边是 HTML 生成的可交互面板：duration、scale、shadow blur、spring easing，全都是可以拖动的滑块。

调好参数之后，点「Copy as prompt」，参数就被复制成一段 prompt，直接粘贴回 Claude Code，它就会把这些值应用到真实的代码组件里。

在浏览器里调，调好了粘回给 AI。

这样的交互方式，显然，Markdown 是做不到的（你要是说 Markdown 里也可以插入 html 的脱裤子放屁式做法，那这话当我没说……）。

0720 个示例

光说理论可能还有点抽象，Thariq 特意做了一个示例站点，放了 20 个完整的 HTML 文件，覆盖了 9 大类使用场景。

地址在这里：https://thariqs.github.io/html-effectiveness/

每个文件都是独立的，不需要安装任何东西，浏览器打开就能体验。

我挑了几个，一起来看下。

08方案探索
三种方案并排对比

这是一个 debounced search 的三种实现方案对比。

A 方案最简单但不支持取消，B 方案零依赖但代码更多，C 方案用了库但多了 12kb 体积。

三个方案并排摆在一起，优缺点非常的一目了然，底下还有个「choose」按钮。

而如果用 Markdown 来做同样的事情，你得把三段代码顺序摆出来，然后脑子里自己去做对比。

差别在于，HTML 是让你「看」到差异，Markdown 是让你「想」出差异。

09代码审查
PR Review 界面

这个例子是一个 PR 的 code review 界面。

diff 渲染出来之后，右侧带了注释气泡：红色是 blocking（必须改），灰色是 nit（建议改），绿色是 nice（写得好）。

Thariq 提到，他现在每个 PR 都会让 Claude 生成一个这样的 HTML 文件，附在 PR 描述里。

“ 这个效果，往往比 GitHub 默认的 diff 界面还好用。”