「HTML 是新的 Markdown」:Claude Code 工程师与卡帕西把文档格式吵上了热搜
「HTML 是新的 Markdown」:Claude Code 工程师与卡帕西把文档格式吵上了热搜
一句"HTML is the new Markdown",让 AI 编程圈在 X 上吵翻了天。起因是 Anthropic Claude Code 团队的工程师公开表态——给大模型看文档,HTML 可能比 Markdown 更合适;随后 Andrej Karpathy 等知名开发者转发力挺,观点迅速出圈,被 36Kr、品玩等媒体跟进报道。这听起来像是"老前端复活"的段子,但背后其实是 AI 编程范式转变的真实信号:当代码生成的主力从"人"变成"Agent"时,文档的消费对象也从"人眼"变成了"token 上下文窗口"。
本文不站队,而是把双方论点、AI 编程场景下的真实差异,以及它对我们写提示词、写 CLAUDE.md、写项目文档的直接影响,结合一个真实的开源生态——claude-code-templates(一个 2000+ 组件、累计下载超 150 万次的 Claude Code 配置模板库)逐层拆开。
论战的起点:Markdown 是为"人"发明的,还是为"机器"发明的
争论的核心其实是一个再朴素不过的问题:Markdown 的语法到底在服务谁?
支持 Markdown 的一方认为,Markdown 是人类写作效率的巅峰——不需要闭合标签、不需要层层嵌套,## 标题、- 列表、**加粗** 读起来和写起来都极其自然,这正是它统治 README 与文档二十年的原因。反对者(也就是这次上热搜的一方)则指出:Markdown 是为"人类解析"优化的语法,而它牺牲掉的恰恰是"机器解析"最需要的显式结构。
Claude Code 工程师的论点大致可以还原为三条:
- 歧义是幻觉的温床。Markdown 的标题层级、列表嵌套、代码块边界大量依赖缩进和空行来推断,模型在 token 序列里"猜"结构时,猜错的代价是生成错误的层级关系或重复内容。而 HTML 的
<h1>、<ul>、<pre>是显式声明的语义边界,不需要任何推断。 - 训练语料的天平本就偏向 HTML。大模型在训练阶段见过的 HTML 文本量级远超 Markdown,对标签语义的建模更深——让模型读它"最熟悉的语言",指令遵循率和结构还原度天然更高。
- 渲染即验证。HTML 写完可以直接丢进浏览器验证结构是否正确,Markdown 则需要经过一层解析器;而对 Agent 而言,它"看到的"文档本质上永远是一串需要被正确解析的标记。
Karpathy 的力挺进一步放大了这条逻辑:他长期强调"token 才是模型的思维语言",既然模型在内部推理时对结构化标记的理解远优于人类速记符号,那么把喂给它的文档也写成结构化标记,就是顺势而为。
为什么在 AI 编程场景下,HTML 的优势被放大了
抛开站队,看一个具体的 AI 编程工作流就能理解争议为何如此真实。以 claude-code-templates 项目为例,它本身就是"AI 编程被模板化、被工程化"的样本:仓库里 2000+ 个组件(Agent、斜杠命令、MCP、Hooks、Skills)全部以 Markdown 为载体,最后被 Claude Code 读取进上下文。
看它自己的前端实现 MarkdownViewer.tsx 会发现一件很有讽刺意味的事:这个组件用 marked 把 Markdown 解析成 HTML,再自定义 renderer 给每个标题生成 id 锚点、给代码块包裹语义化标签。也就是说——"写作端用 Markdown,消费端最终全是 HTML"。Markdown 只是人类输入的中间格式,模型真正稳定理解的、真正用于渲染和检索的,是那个结构化、语义化的 HTML 树。
再往下看,这种"结构优先"的倾向在这个仓库里无处不在:
- 它的博客系统 BLOG_WRITING_GUIDE.md 要求每篇文章必须是语义化 HTML + JSON-LD 结构化数据,而不是纯 Markdown 转发的页面;
- 它的分析面板 analytics-web/index.html 用语义化标签组织实时会话监控界面;
- 它的沙箱服务 sandbox-server.js 直接提供一个 localhost HTML 界面,让浏览器成为 Agent 的可视化操作台。
把这三件事连起来,就能看到论战背后的技术现实:AI 编程的产出物正在从"给人看的文件"变成"既给人看、也给 Agent 消费的语义结构"。HTML 的标签体系恰好是两端通吃的语言——人能读懂,模型能精确定位,浏览器能渲染验证。
对提示词与项目文档写法的实际影响
这场争论最有价值的部分,是它给出了可立即落地的工程结论。结合 claude-code-templates 的实践,可以提炼出三条对日常工作的直接影响。
第一,CLAUDE.md 与斜杠命令模板:从"散文式"走向"结构式"。
Claude Code 的记忆文件 CLAUDE.md 和自定义斜杠命令本质上都是 Markdown 文件,但仓库里模板的写法已经在向"结构化约束"倾斜。比如 generate-tests.md 这个斜杠命令模板,frontmatter 里用 allowed-tools、argument-hint、description 声明权限与入参,正文则用"Analyze → Strategy → Mock Design → Unit Tests"的编号阶段强制模型按顺序执行;而 common/CLAUDE.md 模板则用固定的小节清单(Code Quality、Git Workflow、Documentation、Testing、Security)把"通用开发准则"变成可勾选的清单而非自由文本。
这就是论战在实操层面的映射:与其依赖模型"理解"一段流畅的 Markdown 散文,不如用明确的分节、列表和约束把它变成一组可验证的指令。 当你想更进一步时,直接在 Markdown 里嵌入 <goal>、<context>、<constraints> 这类语义标签包裹关键指令,就是"HTML 化"最轻量的一步——它给你的不是语法,而是显式的语义边界。
第二,文档的"消费对象"变了,格式的选择标准就变了。
传统选型问的是"人读起来顺不顺",现在必须追加一问:"模型读起来准不准、渲染后能不能验证"。仓库里的 technical-writer.md Agent 模板本身就体现了这种双重标准:它既要输出"Readability score > 60"这种面向人的指标,又要保证"Technical accuracy 100% verified"这种面向事实的结构化要求。项目文档如果想同时服务人和 Agent,HTML 的标题锚点、表格语义、代码块边界就是比 Markdown 缩进更可靠的契约。
第三,"写作用 Markdown,交付用 HTML"会成为默认工作流。
争论的真正共识也许不是"谁取代谁",而是分工:人写的时候用 Markdown 保留效率,交给 AI 的时候用结构化的 HTML/语义标签保证确定性,最终渲染端一律 HTML。 这一点在这个仓库的数据链路里已经闭环——CLAUDE.md 由人写(Markdown),被模型消费(转成结构化理解),最终在 SkillExplorer.tsx 这类界面里以渲染后的 HTML 呈现给团队复盘。
更进一步,这个仓库已经在测试"浏览器直接成为 Agent 的工具面":它实现了 WebMCP 集成(见 webmcp.md),让浏览器 Agent 可以直接通过 document.modelContext 调用页面上注册的搜索、查询、统计工具。当 Agent 开始直接消费页面结构而非扫描文本时,"HTML 是新的 Markdown"就不再是修辞,而是一种工程事实。
结语
把热搜标题翻译成工程师语言,这轮争论其实只论证了一件事:在 AI 编程时代,文档格式的评判标准从"人类可读性"转移到了"机器可解析性与结构确定性"。HTML 标签是显式的语义承诺,Markdown 是高效的人类速记——它们本就不是同一层的工具。
对正在写 CLAUDE.md、调提示词、维护项目文档的开发者,最值得带走的不是"赶紧把所有文档改写成 HTML",而是一个判断框架:凡是需要模型精确理解结构的地方(指令边界、约束条件、层级关系、可验证清单),就用显式标签把它钉死;凡是给人快速阅读的草稿,Markdown 依然是效率之王。给 Agent 的每一段结构化的清晰,都会以更少的返工和更稳定的输出返还给你。