写代码不写文档，是程序员的老毛病了。但你有没有想过，为什么"文学编程"这个理念提了40年，一直火不起来？

三个月后再看自己写的代码，完全想不起来当初为什么这么写。同事问起来，你只能支支吾吾：“这个嘛…当时是为了解决一个边界情况…”

如果有个文档能把你当时的思路原原本本记下来，那该多好。

文学编程：理想很丰满，现实很骨感

四十多年前，Donald Knuth 提出了"文学编程"（Literate Programming）这个概念。核心理念很简单：代码不应该是一堆冷冰冰的机器指令，而应该是一篇人类可以阅读的叙事文章，代码只是文章的一部分。

听上去很美好对不对？

但真正用过的人都知道，这里有个致命问题：你得同时维护两套东西——代码本身，和解释代码的散文。

想象一下，你写了一个函数，改了三版代码，每版思路都不一样。然后你不仅要改代码，还要同步更新对应的说明文档。这工作量瞬间翻倍。

所以文学编程一直是个小众玩具。最常见的应用场景是数据科学家的 Jupyter Notebook——他们确实需要把分析过程和结果放在一起。但对于日常写业务的程序员来说，这玩意儿太重了。

事情正在起变化

直到 AI Agent 出现。

现在的 Claude、Kimi 这些编程助手，对 Org Mode、Markdown 这类标记语言掌握得炉火纯青。它们不会抱怨"语法太多"，也不会在同步文档时偷懒。

这就意味着一种全新的工作流成为可能：

你告诉 AI Agent：“给我写个运行手册，用 Org Mode 格式。”

然后 AI 会帮你把代码和解释文档整合好。你要做的只是审查、批准、运行。

具体怎么玩？作者描述了他的做法：

  1. 让 Agent 写一个 Org Mode 文件，包含测试步骤和对应的命令
  2. 审查时，散文部分解释了这个步骤的目的，代码块可以直接执行
  3. 运行结果会自动存在文件里，像 Jupyter Notebook 一样
  4. 想改代码？让 AI 同步更新散文。想改说明？让 AI 更新代码。两条线永远保持一致

这就很恐怖了——以前需要人工维护的"双线叙事"，现在 AI 可以不知疲倦地帮你同步。

Agent 为什么能搞定这个活

关键在于，文学编程的痛点恰好是 AI 的强项：

  • 翻译和总结：把代码翻译成人话，或者把人话翻译成代码
  • 保持同步：每次修改后重新整理文档，AI 永远不会嫌烦
  • Org Mode 的复杂语法对 AI 来说不是问题

你甚至可以在项目里放一个 AGENTS.md 文件，告诉 AI：“把这个 Org 文件当作唯一的事实来源，执行前先 tangle。”

它就真的会照做。

还有个额外的好处：代码库可以导出成各种格式供人阅读。如果将来程序员的主要工作从"写代码"变成"读代码"，这一点会变得越来越重要。

真的没有缺点吗

当然有。

Org Mode 跟 Emacs 绑得太紧，这是一个历史包袱。作者也承认，如果能用 Markdown 实现类似功能会更普及。但 Markdown 缺少元数据能力，暂时还替代不了 Org。

另外，这套方法作者目前主要用在测试和记录手动流程上，还没在大项目里验证过。具体效果如何，还需要更多实践检验。

所以到底该不该试试

我的建议是：值得一试。

特别是如果你现在正在用 AI Agent 帮忙写代码，完全可以顺手让它帮你维护文档。

起步很简单：

  1. 装个 Org Mode 插件（Emacs 或 VS Code 都有）
  2. 让 Claude 帮忙时顺嘴提一句：“记得记录成 Org 文件”
  3. 跑一遍试试

至于能不能真的让大型代码库变得"像小说一样可读"，我觉得这是个值得期待的方向。

程序员不用再为"写不写文档"这个问题纠结了—— AI 可以帮你写，你只需要审查和批准。文学编程诞生四十年来，这可能是最接近"普及"的一次。

相关工具

常见问题

文学编程和写注释有什么区别？

注释是内嵌在代码里的碎片，散落在各处，没有叙事结构。文学编程是以文档为主体，代码作为文档的一部分嵌入其中，整体是可以连贯阅读的。

用 Claude 或其他 AI Agent 做文学编程，必须用 Org Mode 吗？

不是必须。Org Mode 的好处是支持代码块元数据（比如指定在哪台机器运行）和 tangling 功能，但如果你只是想让 AI 帮你记录操作步骤和结果，用 Markdown 也能凑合。

这种方式适合大型项目吗？

目前没有大型项目的实践案例。作者（Ian Whitlock）主要用在测试和手动流程记录上。能不能扩展到正式代码库，还是个开放问题。