前几天在 X 上刷到一篇推文，Thariq推荐在Claude Code中使用 HTML替代Markdown作为输出格式。HTML信息密度更高、视觉更清晰、易于分享，且支持交互式操作，更适合展示复杂内容。现在超过了1200w的阅读，文末也会给出原文链接。核心差异就是HTML可用表格、SVG、CSS 等丰富形式表达数据，从使用者人的角度出发HTML更方便人理解和阅读。所以想起来了之前看到一个Skill，把整个代码仓库变成了交互式的教学页面，带着动画、测验、还有逐行代码的白话文翻译。后续试了几个项目，确实有点被惊艳到。关于如何让一个人理解自己已经写出来的代码这件事，还挺有意思，推荐给大家。
01
这个 Skill 到底是什么
先聊一个问题：我们面对近期交付完的项目或者代码模块，给别人去做项目介绍或者是讲解核心逻辑，传统的做法是把需求、设计等过程文档整理出一份材料。在 AI 辅助越来越成熟的今天，完全借助AI的理解生成一份材料，也逐渐变成常规操作。
但是选择输出的材料类型通常是文本文档类，搞技术的大多数都是Markdown 文档。可能也有历史惯性，Markdown 是人为了方便协作产生的，轻量、可读、用纯文本就能写。但当输出方已经不是人而是AI时，是不是可以换个更舒服的标准。可能这么说不直观，举几个例子方便体会，你想想看：
一份 1000+ 行的 Markdown 文档，你要翻多少才能找到你想看的部分？
一个复杂的数据依赖关系，Markdown 用文字描述，HTML 画一张带高亮的依赖图就完事了
你想对比两个方案的差异，Markdown 只能写两段话，HTML 可以直接做个对比滑块
视觉体验方面，HTML 能给的视觉体验，Markdown 给不了。当然我绝对不是说 Markdown 没用了，写笔记、写文档它仍然是好工具。但当你需要让别人更直观理解一个复杂系统时，只输出 Markdown信息都在，但体验大打折扣。
结合这个思路，推荐一个Skill给大家，这个Skill叫做：codebase-to-course，一个能将代码库转化成交互式 HTML 课程的 Claude Code Skill。它的 SKILL.md 和推文的观点基本一致，不止用 HTML，而且要最大限度地利用 HTML 的能力。
02
一次完整的实践样本
用 HTML 做了几件 Markdown 做不到的事：
2.1分组聊天动画替代流程图
Markdown 写组件A通过HTTP调用组件B，然后组件B返回结果给组件A，读者全靠脑补。而它生成的是类似 iMessage 气泡的对话动画，组件A发一条消息，组件B回一条，一目了然。
2.2 代码逐行对照，不换上下文
Markdown 里贴一段代码，再另起一段写说明，你读的时候得来回切视线。它用 HTML 做左右分栏，左边是真代码（从仓库原样取出来的），右边是逐行白话文翻译。同一个页面，不用上下翻。
2.3 应用型测验，这个有点意思
它还提供了一份随堂测试，测验理念我很喜欢，测试的是应用能力，不是记忆力。不用 Markdown 模拟的Q&A列表。它的测验是交互式的：选完答案，即时反馈；错了不是给个红叉，目的是让大家有真正了解，而不是考你，并且附一段鼓励性的解释。这些小特性都是纯文本做不到的。
2.4 名词悬停解释
API、JSON、回调、xx中间件……所有技术术语，鼠标悬停就能看到通俗定义。这在 Markdown 里要么靠链接跳转（跳出打断阅读流），要么靠脚注（不够直观）。
上面的几个小特性，贯穿起来的核心理念是：让一个非技术背景的人真正理解代码怎么跑。 这个目标天然指向了强视觉、交互式、自包含的输出格式，而这正好是 HTML 的领地。整个展示的过程能够体会到不要让参与者跳出学习流
一个 HTML 文件直接扔浏览器打开
术语悬停，不用去跳转解释
代码对照，不需要来回翻页
交互测验，即时反馈
如果是纯文档，就会有一个缺陷就是：需要参与者不断跳出。 看到不懂的术语→跳出搜索；想查文件结构→跳出看目录；想理解代码→跳出翻 IDE。
下面是我自己用这个Skill做的一份材料的过程和结果（用法也很简单，就是告诉你的Agent，把这个项目做成一门交互课程即可），可以先看下，如果有兴趣也可以自己试一下：
03
这对我们有什么意义？
个人觉得更重要的是换思路。不单是技术上的替代，而是理念上的升级。过去我们写技术文档，默认约束是人能写。写公式用 专用工具、画图得截屏贴图、复杂的交互根本别想。但现在AI 能写一切，人的写不再是瓶颈，读才是。 所以输出格式的最优解，应该从人写什么最省事转向人读什么最有效。
就拿上面的例子来说，当输出格式从文字变成页面时，技术知识的传递效率会上一个台阶。一个有动画、有测验、有代码对照、有悬停解释的课程，和一个几百行 Markdown 文档，传递的信息量不在一个量级。
另外还有一个变化点，我们都身处AI 时代下，当生成的能力不再是瓶颈，我们应该从生产思维转向交付思维。Markdown 像一个记事本，你往上面记东西。而 HTML 像一个展览策划，你把信息设计成观众愿意观看的形式。
说了这么多 HTML 的优势，也得把另一面端出来。
费 Token。同样的内容，HTML的Token消耗比Markdown贵不少，生成一份完整 HTML 课程可能会吃掉几百K Token。
不方便团队版本控制。Markdown 是纯文本，一行改动通过 git diff 就能看清前后差异。代码评审、历史追溯都非常友好，在这方面HTML会很痛苦。
https://x.com/trq212/status/2052809885763747935
https://thariqs.github.io/html-effectiveness/
https://github.com/zarazhangrui/codebase-to-course
仁者见仁，智者见智。两种格式各有领地，关键看你面对的是什么场景、服务的读者是谁。
👆👆👆tips：敬爱的读者朋友，原创文章不易，如果您对企业架构、系统架构设计、软考高级系统架构师等技术领域感兴趣，可以点赞+关注，欢迎留言讨论，我们一起进步~
