htmx 作者 Carson Gross 写了一篇随笔，主张把 Markdown 当成源代码。他不是要说「文档该用 Markdown 写」这种老话，而是一个正在行业里成形的趋势：agentic coding 时代，真正的应用逻辑被定义在 Markdown 里，agent 生成的代码反而成了「低层实现细节」——这句判断他引自 Hartley Brody 的《Markdown is the new source code》：『软件的应用程序逻辑开始用 markdown 定义和编辑，而 agent 生成的代码变成了某种低级实现细节。』

Gross 在蒙大拿州立大学当教授，靠兼职咨询保持手感，他见过大量公司正在「以惊人的速度」走向这条路。他对 AI 生成代码本身是矛盾的（之前写过几篇相关随笔），但这一篇关心的是后果：今天 LLM 生成的代码来自一串串临时 prompt，这意味着生成代码本身成了某个 feature 的『事实真相』——文档散落在 Linear、Slack、wiki 里，而代码库里唯一可信的就是那段生成代码。

他说编译器工作流会保留原始源代码，LLM 工作流不会，这正是他和『LLM 即编译器』类比的分歧点。他的提议很具体：把从临时 prompt 会话里沉淀出的 Markdown 提交进源码目录，放在一个新目录 /src/md 里。这些 Markdown 比传统设计文档更底层——包含架构决策、源码级决策、低层数据设计，更接近规格说明（但不是规格说明）。

理由还是他反复强调的『局部性』（locality）：代码模块旁边就是解释它意图的 Markdown，没有那种『规格在别处』的隔空魔法；Markdown 人和 agent 都能读，agent 不用再去别处找上下文。测试则承担另一层分工——他说『测试即新规格』有道理，但测试仪式感太重、层级太低、装不下 Mermaid 图这类高层解释，不适合做人机交互的介质。所以 Markdown 是规格（ish），测试基于它做自动化确认。

他还给了一套 /src/md 的目录约定，但明说是全文最弱的部分——新想法，自己也没怎么用过，欢迎讨论：README.md 当索引和 agent 入口、TODO.md、OVERVIEW.md，下面按 features / data / api / infrastructure 分轴。重点是补了一句很有态度的建议：/src/md 里的内容应该主要由人来写和整理，别用 agent 生成。

结尾的价值判断值得单独读一遍：『随着代码越来越便宜，真正有价值的，是代码背后的意图——它做什么、为什么做、绝不能做什么。』今天这些意图往往丢在临时 prompt 里，或散落在 wiki、工单和 Slack 线程中。他建议把这些意图写进 Markdown、check in 到 /src，让人和 agent 都能找到。最后还补了句俏皮话：「就算 LLM 不是编译器」。

来源：

• Markdown in /src - Carson Gross / htmx essays