HTML 的不合理有效性 — Claude Code 团队的文档范式转移¶
Claude Code 核心工程师 Thariq Shihipar 发文宣布自己几乎不再写 Markdown，全部改用 HTML。文章在 X 平台 48 小时内获得 780 万阅读、1200+ 转发，引爆了开发者社区对 AI 时代文档格式的激烈讨论。
目录¶
- 事件背景
- Thariq 其人
- 核心案例：HTML 做了什么 MD 做不到的事
- MD 为什么「不行了」
- MD 党的反击：MD 是 AI 时代的「源代码」
- 真正的答案：不是替代，是分工
- 更深层的问题：如何在 AI 时代保持参与感
- 我的实践启示
- 参考资料
事件背景¶
2026 年 5 月 8 日，Anthropic Claude Code 团队核心工程师 Thariq Shihipar 在 X 平台发布长文 "Using Claude Code: The Unreasonable Effectiveness of HTML"，核心观点：
"HTML 是新的 Markdown。我已经几乎不写 Markdown 文件了，全部换成让 Claude Code 生成 HTML。"
文章同时开源了 20 个日常使用的 HTML 文件案例，按用途分为 9 大类。消息一出，开发者社区迅速分裂为 MD 党和 HTML 党，引发了一场关于 AI 时代文档格式的深度讨论。
Thariq 其人¶
| 维度 | 信息 |
|---|---|
| 教育背景 | MIT 媒体实验室硕士 |
| 创业经历 | Y Combinator W20 批次，创办游戏公司融资 1700 万美元 |
| 当前角色 | Anthropic Claude Code 团队，负责工程、内容和用户反馈三条线 |
| 已知贡献 | 设计了 Claude Code 的「主动提问而非瞎猜」交互模式；2026 年 3 月发文披露 Anthropic 内部运行着几百个活跃 Skills |
| 动机 | 自称「AI 病发作」，认为 Claude Code 是软件开发未来 |
核心案例：HTML 做了什么 MD 做不到的事¶
1. 代码审查（Code Review）¶
MD 方式：GitHub 的 Diff 视图，一行行代码，左旧右新，改动大时极难阅读。
HTML 方式：Claude Code 生成一个 HTML 页面，包含：
+----------------------------------------------------------+
| [风险地图] 文件A: 红 | 文件B: 黄 | 文件C: 绿 | ... |
+----------------------------------------------------------+
| Diff 渲染 |
| + 这段改动有问题（红色标注，blocking 级） |
| - 旧代码 |
| ~ 这个写法可以优化（黄色标注，建议级） |
| + 新代码 |
| + 这里的处理很优雅（绿色标注，好评） |
+----------------------------------------------------------+
| [修复建议清单] |
| 1. [必须] 修复空指针风险 → 具体方案... |
| 2. [建议] 优化查询性能 → 具体方案... |
+----------------------------------------------------------+
关键差异：代码的 Diff 本质上是空间信息，MD 把它压平成一维文字，HTML 能还原回二维空间结构。
2. 技术教程（交互式解释）¶
以一致性哈希（Consistent Hashing） 为例：
| 对比项 | MD 教程 | HTML 教程 |
|---|---|---|
| 可视化 | ASCII 圆圈，脑补环结构 | 可交互 SVG 环，彩色节点 |
| 操作性 | 纯文字描述 | 点击按钮添加/删除节点，实时观察 key 重新分配 |
| 数据对比 | 文字描述差异 | 并排对比表格，鼠标悬停显示解释 |
| 学习效率 | 读文字 → 想象 | 操作 → 观察 → 理解 |
3. 用完即弃的编辑器（Disposable Editors）¶
场景 A：24 个工单重新排序
MD 方式：在聊天框一条条告诉 AI 调整顺序，或手动编辑列表
HTML 方式：生成拖拽卡片界面（四列：现在/下一步/稍后/砍掉）
↓ Claude 预排序 → 用户拖拽微调 → 复制为 MD 导出
场景 B：微调系统提示词（System Prompt）
+----------------------------------+----------------------------------+
| 可编辑区 | 实时预览区 |
| 你是一个 {role}， | 你是一个产品经理， |
| 专注于 {domain}， | 专注于 SaaS 定价策略， |
| 风格是 {tone}。 | 风格是简洁专业。 |
| [变量槽位高亮显示] | [三个样例输出] |
+----------------------------------+----------------------------------+
| 字符数: 342 | Token 数: 89 |
+------------------------------------------------------------------+
4. 其他案例¶
| 用途 | HTML 相比 MD 的提升 |
|---|---|
| 周报 | 配小图表 + 彩色时间线，一扫即懂 |
| 实施计划 | 时间线 + 里程碑 + 数据流图 + 风险表 → 仪表盘（vs 说明书） |
| 设计系统可视化 | 色板渲染 + 组件尺寸/状态/变体铺表 |
| 动画调参 | 拖动滑块调整缓动曲线和时长，一键复制回代码 |
| 幻灯片 | 单个 HTML 文件，浏览器打开即演示 |
MD 为什么「不行了」¶
Thariq 的判断基于两个关键变化：
变化一：AI Agent 的输出越来越复杂¶
一份超过 100 行的 Markdown 文件，我坦言自己读不下去。
MD 的表达方式是线性的：标题 → 段落 → 列表 → 代码块。短的时候很清晰，一长就严重消耗耐心。AI 轻松就能生成几百行甚至上千行的文档——技术方案从背景到实现到测试到风险面面俱到——但你真的会从头到尾读完吗？
变化二：人们越来越少亲自编辑这些文件¶
传统工作流：
人写 MD → 人改 MD → 人读 MD
（MD 的「易编辑」优势发挥到极致）
AI 时代工作流：
AI 写 MD → AI 改 MD → 人「读」MD（实际上只是扫一眼）
（MD 的核心优势「易编辑」被彻底架空）
MD 统治开发者工具链十几年，靠的是一个核心假设：人要亲手编辑文件。所有语法设计（# 标题、** 加粗、- 列表）都是为了让人类打字更方便。当写文件的人从人变成了 AI，这个假设就不成立了。
| 对比维度 | Markdown | HTML |
|---|---|---|
| AI 写作成本 | 无本质区别 | 无本质区别 |
| 人类阅读体验 | 纯文本，线性，无交互 | 有颜色、有布局、有交互 |
| 分享便利性 | 浏览器原生渲染差，需附件 | S3 一传，链接打开 |
| 可读性（长文档） | 扫两下就关了 | 更多人真的会读完 |
| 版本控制 | 清晰的 diff | 乱得没法看 |
| 写作效率 | 快 | 慢 2-4 倍（但写的人是 AI） |
核心观点¶
当瓶颈从「字数数量」变成了「人的注意力」，格式的选择逻辑就彻底翻转了。
你真的会去读 HTML 的东西，而 MD 的长文档大概率你滑两下就关了。读了和没读这个差距，可比那点写效率大多了。
MD 党的反击：MD 是 AI 时代的「源代码」¶
MD 党的论据同样硬核：
论据 1：AGENTS.MD 成为行业标准¶
2025-08 OpenAI 发布 AGENTS.MD → 单个 MD 文件指导 AI Agent 工作流
2025-12 Linux 基金会成立 AgentAI，将其捐为开放标准
白金成员：AWS, Anthropic, Google, Microsoft, OpenAI
采用量：60,000+ 开源项目
支持：Cursor, Devin, Claude Code, GitHub Copilot
论据 2：LMWiki 架构 — 一个 MD 文件 5 万 star¶
Andrei Kaparchy（卡帕西）开源的 LMWiki：
LM Wiki 架构（三次 Markdown）：
raw/ ← 原始资料（MD）
wiki/ ← AI 生成的概念页和摘要（MD）
CLAUDE.md ← Schema 定义 + 规则（MD）
CLAUDE.md 单日涨 7,900 star，目前接近 50,000
论据 3：Token 效率碾压¶
同一篇博客：
HTML → 16,180 tokens
MD → 3,150 tokens （压缩 80%）
→ 同样的 LLM 预算，MD 可以处理 7-17 倍的请求量
论据 4：GitHub 官方定调¶
「文档不再是描述代码，文档就是代码。自然语言被编译成下层语言，恰好长得像 Python 或者 JavaScript。」
真正的答案：不是替代，是分工¶
两边都赢了一半¶
MD 党回答的是：我们用什么【写】？
HTML 党回答的是：我们给人【看】什么？
这两个根本不是同一个问题，怎么会有谁取代谁？
AI 时代的新工作流¶
以前：
人写 MD → 人看 MD
（生产者和消费者是同一个人，需要折中）
现在：
AI 写 MD → AI 改 MD → AI 生成 HTML → 人看 HTML
（生产成本被 AI 吸收，不再需要折中）
两个活样本¶
样本 1：Thariq 自己 - 2026 年 3 月：发 Skills 使用指南 → 生产端推 MD - 2026 年 5 月：发 HTML 的不合理有效性 → 消费端推 HTML - 同一个人，两端各自最优选择
样本 2：Kaparchy + Lex Friedman - Kaparchy 的 LMWiki：内核全是 MD（生产端） - Lex Friedman 用同款架构，外面加了一层动态 HTML + JavaScript（消费端） - 内容是 MD，外壳是 HTML，不是替换，是叠加
决策树：什么时候用 MD，什么时候用 HTML¶
需要给别人看 / 自己反复看吗？
├── 否（AI 内部消费）→ MD
│ - AGENTS.MD / CLAUDE.md / Skills
│ - 系统提示词 / 规则定义
│ - Git 版本控制敏感的场景
│
└── 是（人类消费）→ HTML
├── 需要交互 / 调参 → HTML（拖拽、滑块、导出）
├── 需要可视化 / 空间信息 → HTML（图表、流程图、Diff）
├── 文档 >100 行 → HTML（分段、Tab、导航）
└── 需要分享给非技术人 → HTML（链接即开）
更深层的问题：如何在 AI 时代保持参与感¶
这才是整件事最核心的价值。
Thariq 的自白¶
「之前我开始担心，因为我不再深入阅读那些方案了，我只能放手让 Claude 自己做决策。但用了 HTML 之后，我感觉自己比以前任何时候都更在 Loop 里了。」
问题本质¶
AI 太能写了 → 生成几百行「完美」方案
↓
用 MD → 扫一眼就过 → 让 AI 继续执行
↓
表面上是效率提升，实际上是逐渐失去判断和控制
用 HTML → 计划更容易读
→ 方案更容易比较
→ 代码变化更容易审查
→ 参数更容易调整
→ 结果更容易回传给 AI
↓
把人重新拉回到循环里
信息带宽类比¶
MD → 一根水管（线性、窄、单向）
HTML → 一条马路（空间、宽、可交互）
未来 → 高速公路（可交互视频？AI 像同事一样讲方案？）
最好的 AI 工具不是把人排除在外的全自动工具，而是能让人更好地参与进来、发挥人的判断力和创造力的工具。
我的实践启示¶
立即可做¶
- 让 Claude Code / AI 生成 HTML 报告而非 MD，尤其是：
- PR 审查报告
- 技术方案评审
-
周报 / 状态报告
-
用 HTML 做「用完即弃的编辑器」：
- 工单优先级排序 → 拖拽卡片
- 提示词微调 → 左右对照编辑器
-
参数调优 → 滑块 + 实时预览
-
保持 MD 用于生产端：
- AGENTS.MD / CLAUDE.md 不变
- Skills 定义继续用 MD
- 需要版本控制的场景用 MD
需要注意的坑¶
| 坑 | 应对 |
|---|---|
| HTML 的 diff 在 Git 里很乱 | 用 MD 做源文件，HTML 只做生成产物 |
| 写作效率低 2-4 倍 | 写的人是 AI，不心疼 |
| 分享 HTML 需要托管 | S3 / GitHub Pages / 本地打开都行 |
| 过度设计 | HTML 工具应是「用完即弃」的，不是产品 |
参考资料¶
- Thariq 原文（X 平台） — 1200 万阅读，完整论述 + 案例
- HTML 案例库（GitHub Pages） — 20 个开源 HTML 文件
- Simon Willison 的评论 — 并附带了 GPT-5.5 实测
- Hacker News 讨论 — 社区争论精华
- Reddit 讨论 — MD vs HTML 正反方观点
- 视频来源：AI 啟示錄
相关笔记¶
- [[AGENTS.MD 规范]]（待创建）
- [[Claude Code Skills 实践]]（待创建）