前言
自从A\发了这篇博文之后，网上就出现了诸如《HTML正在淘汰Markdown》这类文章，看来看去，反复就是说 有了Agent，人不用编辑文档，所以不需要关注编辑文档的复杂性，只关注最终展示的文档就行了。 使用HTML的文档表现力大于Markdown，因为HTML可以用图标、CSS等，而Markdown不能，所以HTML更有效。
在我看来，这类文章有些荒谬，如果为了流量而只读标题，曲解原文的意思，最后站在原文的对立面，这是很可怕的。
我对于HTML的有效性是认可的，因为恰当的时候使用恰当的工具是很重要的，但是我认为HTML并不是万能的，Markdown也有它的优势。 技术人员总是无法避免人工修改文档，所以比起繁琐的HTML，Markdown的简洁性无法被抛弃。
随着 Agent 的发展，传统的开发者与文档的关系的确正在发生改变，文档编写者正在开始承担文档阅读者的责任。 如果想要理解这种变化，那么就先需要理解为什么需要文档以及为何需要修改。
为什么需要文档以及为何需要修改？
就 Vibe Coding 来说，如果只是浅薄地在一个 thread 中直接通过对话，不用 skills，不用 AGENT.md，仅仅是两行提示词 来对 Coding Agent 许愿，希望能一次就达到项目的标准，这几乎是不可能的。
为了提高生成质量，大多数情况下，开发人员往往会编写 AGENT.md / CLAUDE.md 文件来指导 Agent 的行为，这类项目级的提示文档 往往会比较简洁，通常包含一些项目的技术栈信息，而不过多赘述项目中的设计理念，业务逻辑等。
因此，我们需要一种方法来管理和维护除了项目提示词之外的文档，很多人会把这些内容写到代码的注释中，也有人会把他们写到类似于 /docs 的目录中
，通过基础的模板文档衍生出各种文档，并且提供工具供 Agent 查询读取对应的文档。
我认为两者都做可能是比较好的方法，最大的缺点就是维护成本太高，如果某一次 Agent 修改了代码，但是文档和注释没有一起修改，那么这些内容就不新鲜了，
并且有可能会让后续的 Vibe 产生幻觉。现在这种问题也能够被很好地解决，例如规格驱动开发，通过 skill 让规格文档变得可执行，那么修改规格就等同于
修改代码，换句话说，例如 spec-kit 通过 specify 把大量规范和规格维护到了 .specify/ 下，通过 skill 和可确定的工具调用，文档是能够被保证的。
结语
在设定的框架中运行的东西总是比随意地发散更加稳定，因此我们需要文档而且需要去修改它，当然大多数时候不会自己改，而是让 Agent 去修改，而修改完的文档如果达到了一定 的行数，就没有人会去看它，而 HTML 不同，通过直观的视觉效果来向你表达文档的内容，从而减轻阅读压力，这就是 HTML 的有效性，也是A\博文的核心观点，绝非简单的 “HTML比Markdown更有效”。