返回洞察
工程实践

丢掉 Markdown，回归 HTML：实现与 AI 智能体的高效沟通

前两天在 X 上有一篇来自 Claude Code 工程师 Thariq 的文章爆了。这篇文章发布到目前才短短 2 天，阅读量已经有了惊人的 855 万！

但与以往 Claude 团队成员发表的文章的反馈不同，这篇文章在 X 上并不是一边倒的支持，而是引发了全网广泛的争论：有朋友支持作者的观点，也有朋友强烈反对。

近期工作节奏拉满，实在无暇分身，没能第一时间细读评析。此刻恰逢我的 AI Agent 正在跑数据，便借这点空档完成了翻译整理，并通过我的公众号呈现给大家。

由于原文直接翻译成中文大约有 5000 字，且内容广泛、读起来散乱晦涩，所以我对内容进行了如下优化：

好了，接下去我先来介绍一下作者 Thariq Shihipar 是谁：

Thariq Shihipar 在 Anthropic 的Claude Code团队中担任工程师（Engineer）。

他在该项目中的具体身份和贡献包括：

核心功能推动者：他是 Claude Code 中 “Skills”（技能）功能的核心推动者之一，负责在该工具中构建和扩展代理（Agent）的能力。

工具架构设计：他参与了 Claude Code 的底层工具设计，包括Claude Agent SDK（原 Claude Code SDK）的架构与实现。

技术布道与经验分享：他经常在社交平台（如 X ）和技术社区分享关于 Claude Code 的一手使用经验、功能动态以及智能体工具设计的底层逻辑。

在加入 Anthropic 之前，他曾是 MIT Media Lab 的研究员，并联合创办了受 Y Combinator 支持的初创公司。

下面开始正文：

使用 Claude Code：HTML 不可思议的有效性

Markdown 一直是 AI 智能体跟我们沟通的主流格式——简洁、可移植、便于编辑。Claude 甚至练就了用 ASCII 在 markdown 里画图的本事。

但随着智能体越来越强，我越来越觉得 markdown 是种“束缚”。超过 100 行我就读不下去了。我想要更丰富的可视化——颜色、图表，并且能轻松分享给别人。

何况我现在很少亲自编辑这些文件了，更多是把它们当作规格说明、参考文档、头脑风暴产出。要改也是让 Claude 改——这就让 markdown“便于人手编辑”的核心优势失效了。

所以我开始改用 HTML 作为输出格式，Claude Code 团队里也越来越多人这么做。下面说说原因。

为什么是 HTML？

信息密度高。几乎没有 Claude 能读懂的信息是 HTML 表达不了的：表格数据、CSS 设计、SVG 插图、代码片段、JS + CSS 交互、流程图、空间数据、图片……当模型缺乏这种表达力时，它就只能在 markdown 里干一些低效的事，比如画 ASCII 图，或者用 unicode 字符“模拟”颜色。

视觉清晰，更易读。Claude 现在写的方案越来越长，超过 100 行的 markdown 我自己都读不完，更别提让团队其他人读了。HTML 文档则可以用标签页、插图、链接组织得井井有条，还能做成响应式，在手机上也能舒服地看。

便于分享。浏览器原生渲染 markdown 的体验很差，常常只能当附件发。HTML 上传到 S3 之类的地方就能直接发链接，同事点开就能看。你的 spec、报告、PR 说明被人真正读完的概率会高得多。

支持双向交互。HTML 可以让你跟文档本身互动——加滑块、加旋钮调参数，再用一个“复制为 prompt”按钮把改动粘回 Claude Code。

Claude Code 能拿到丰富的上下文。比起 Claude.ai 或 Claude Design，Claude Code 能访问你的文件系统、MCP（Slack、Linear 等）、浏览器、git 历史。本文里的图，就是我让它扫了我的代码文件夹、把过往生成的 HTML 文件分类后画出来的。

它让人愉悦。跟 Claude 一起做 HTML 文档就是更好玩，让我感到自己在创作里更投入——光这一点就够了。

怎么开始

不需要做什么特别准备。直接说“做一个 HTML 文件”或“做一个 HTML artifact”就行。我有点担心会有人把这个做成一个 /html skill ——其实没必要。关键是你得知道自己想要这个 artifact 做什么、怎么用，先从零开始 prompt 摸索一下。

几种典型用法

规格说明、规划与探索。我现在处理新问题时，期待产出的是“一张 HTML 文件织成的网”，而不是单个 markdown 方案。先让 Claude 头脑风暴几个不同方向，再深入做原型，最后写实施方案，开新 session 把所有这些文件丢进去让它实施。

Prompt 示例：onboarding 页面我没想好方向。生成 6 个截然不同的方案——布局、语气、密度都做差异化——以网格形式排在同一个 HTML 文件里方便对比。每个标注它的取舍。

代码审查与理解。用 HTML 可以渲染 diff、加注解、画流程图、做模块图——比 GitHub 默认的 diff 视图好用得多。我现在给每个 PR 都附一份 HTML 代码讲解。

Prompt 示例：帮我审这个 PR，做一个 HTML artifact。我对 streaming / backpressure 不熟，重点说那部分。把 diff 渲染出来旁边加边注，按严重程度给问题用颜色编码。

设计与原型。Claude Design 就是基于 HTML 的，因为 HTML 表达设计极有表现力。Claude 可以先用 HTML 把设计草拟出来，再翻译成 React、Swift 等。还可以做交互原型——让它加滑块、旋钮，方便你精准调参。

Prompt 示例：我想给“结账”按钮做原型，点击后播放动画再快速变紫色。做一个带滑块和选项的 HTML 文件，让我试不同参数，再加个"复制参数"按钮。

报告、研究与学习。Claude Code 极擅长跨数据源综合信息。你可以让它搜你的 Slack、代码库、git 历史、互联网，生成给自己、给领导、给团队看的高可读性报告——长文档、交互式讲解、幻灯片皆可，让它用 SVG 画图。

Prompt 示例：我不懂我们的限流器怎么工作。读相关代码，产出一份 HTML 讲解：一张 token-bucket 流程图、3-4 段关键代码加注释、底部加“踩坑提醒”。优化它，让人读一遍就懂。

自定义的一次性编辑界面。有时候光靠文本框很难描述你想要什么。这时我会让 Claude 给我搭一个一次性的编辑器——不是产品，不是可复用工具，就是为眼前这一份数据量身打造的一个 HTML 文件。诀窍是用一个“复制为 JSON”或“复制为 prompt”按钮收尾，把 UI 里做的事变回能粘回 Claude Code 的东西。

Prompt 示例：我要重排这 30 个 Linear 工单的优先级。每个工单做成可拖拽卡片，分到 Now / Next / Later / Cut 四列。先按你的判断预排，加一个“复制为 markdown”按钮导出顺序，每类附一句理由。

适合做这类工具的场景：重排 / 分类工单或反馈、编辑带约束的配置（feature flag、JSON / YAML）、带实时预览的 prompt 调试、数据集筛选打标、文档 / diff 注解、挑那些用文字很难表达的值（颜色、缓动曲线、cron、正则）。

常见问题

不是更费 token 吗？Markdown 是省一些，但 HTML 表达力更强、我读完的概率高得多，整体产出更好。Opus 4.7 有 100 万 token 上下文窗口，多耗的那点根本感觉不出来。

还会用 markdown 吗？老实说几乎完全不用了，但我属于 HTML 极端派。

怎么看 HTML？直接用浏览器打开就行。

比 markdown 慢吗？慢，大概 2-4 倍。但值得。

版本控制怎么办？这是 HTML 最大的短板——diff 很嘈杂，难审。

怎么让 Claude 符合我的审美？frontend design 插件有帮助。要贴公司风格，让 Claude 对着代码库生成一份设计系统 HTML 文件，之后所有 HTML 都拿它当参考。

真正的理由

说了这么多，我用 HTML 的真正原因是：和 Claude 协作时，我感觉自己更“在状态里”了。我之前担心，既然不再深读方案，就只能撒手让 Claude 自己拿主意。但用 HTML 之后，我反而比以往任何时候都更深入地参与其中。希望你也能体会到。

看完文章，你会把你与 AI 智能体沟通的格式从 markdown 改为 HTML 吗？请在评论区告诉我。