我们应该在 Agent 时代重新审视 literate programming

Source: Hacker News

请提供您希望翻译的正文内容，我将按照要求保留链接、格式和代码块，仅翻译文本部分。

Literate Programming, Org Mode, and Coding Agents

Literate programming 是一种理念，认为代码应当与文字交织在一起，使得没有背景的读者也能把代码库当作叙事来阅读，并能够理解它是如何工作的以及它的功能。

虽然我长期对这个想法很感兴趣，并且在几种不同的场景中找到了它的用法¹²，但我发现实际上 Literate programming 往往会演变成维护两条平行叙事的苦差事：代码本身和文字说明。这显然限制了它的推广。

在历史上，Literate programming 最常见的形式是数据科学社区中的 Jupyter notebooks，解释与计算及其结果并存于网页浏览器中。

本博客的常读者会知道 Emacs Org Mode 通过其 org‑babel 包支持多语言 Literate programming，允许执行任意语言并将结果捕获回文档，但这一直是像我这样的极客的利基模式。

即便对这种模式热情如我，也会发现把 Org 作为大型软件项目的唯一事实来源会变得笨拙，因为源代码本质上变成了编译后的产出，每次在 Org 文件中编辑后都必须重新 tangle（在 Org 术语中称为“纠缠”）并把代码放回其目标位置。显然这可以自动化，但很容易出现恼人的情况：你或你的代理已经编辑了真实的源代码，却在下次 tangle 时被覆盖。

尽管如此，我在使用 Literate programming 进行个人配置管理方面已经取得了足够的成功，以至于在 LLM 出现之前，我仍然无法完全放弃这个想法。

A concrete workflow

例如，在使用编码代理之前，我在手动测试和笔记记录时采用了一种 Org Mode 的模式：不在命令行上操作，而是在编辑器中编写更多命令并直接执行，边编辑边调试每一步，直至每一步都正确，然后就地运行。这样当我完成后，就会得到一份文档，准确说明所执行的每一步，而无需额外的记录或笔记。

将创建笔记的行为与运行测试相结合，就能在测试完成时免费获得笔记。

现在有了编码代理，这一点更加令人兴奋。Claude、Kimi 以及其他模型都对 Org Mode 语法非常熟悉；它是一种宽容的标记语言，它们也相当擅长。所有文档都在线可得，可能已经在训练数据中，而 Org Mode 的一个大缺点是语法繁多，但这对语言模型根本不是问题。

现在，当我想测试一个功能时，我会让 clanker³ 为我写一份 Org 格式的运行手册。随后我可以审阅它——文字说明解释模型对每一步意图的反思，代码块在我审阅完毕后可以交互式执行，既可以逐个执行，也可以像脚本一样一次性执行。结果会像 Jupyter notebook 那样存放在代码块下方的文档中。

我可以编辑文字，让模型更新代码，或者编辑代码，让模型在文本中反映其含义。或者我可以让代理同时修改两者。平行系统维护的问题随之消失。

代理被指示处理 tangling，因此提取代码的问题不复存在。可以通过一个 AGENTS.md 文件指示代理把 Org 文件视为唯一事实来源，始终用文字解释正在发生的事情，并在执行前进行 tangle。代理在这些方面表现非常出色，且在代码微调后永远不会厌倦再次用文字解释。

Why agents make literate programming practical

Literate programming 那额外的劳动——也是它未被广泛实践的原因——被代理所消除，代理利用 c

Source: …

capabilities the large language model is best at: translation and summarization.
大型语言模型最擅长的能力：翻译和摘要。

As a benefit, the code base can now be exported into many formats for comfortable reading. This is especially important if the primary role of engineers is shifting from writing to reading.
作为一个好处，代码库现在可以导出为多种格式，便于阅读。如果工程师的主要角色正从编写转向阅读，这一点尤其重要。

I don’t have data to support this, but I also suspect that literate programming will improve the quality of generated code, because the prose explaining the intent of each code block will appear in context alongside the code itself.
我没有数据支持这一点，但我也怀疑可读性编程会提升生成代码的质量，因为解释每个代码块意图的文字会与代码本身一起出现在上下文中。

I have not personally had the opportunity to try this pattern yet on a larger, more serious codebase. So far, I have only been using this workflow for testing and for documenting manual processes, but I am thrilled by its application there.
我个人还没有机会在更大、更正式的代码库上尝试这种模式。到目前为止，我只在测试和记录手动流程时使用这种工作流，但我对它的应用感到非常兴奋。

Org Mode vs. other markup languages

I also recognize that the Org format is a limiting factor, due to its tight integration with Emacs. However, I have long believed that Org should escape Emacs. I would promote something like Markdown instead, although Markdown lacks the ability to include rich metadata⁴.
我也意识到 Org 格式是一个限制因素，因为它与 Emacs 紧密集成。然而，我长期认为 Org 应该摆脱 Emacs。我会推广类似 Markdown 的东西，尽管 Markdown 缺乏包含丰富元数据的能力⁴。

But, as usual in my posts about Emacs, it’s not Emacs’s specific implementation of the idea that excites me – it’s Org’s implementation of literate programming. It is the idea itself that is exciting, not the tool.
但和我往常关于 Emacs 的帖子一样，令我兴奋的不是 Emacs 对该想法的具体实现，而是 Org 对可读性编程的实现。令人兴奋的是想法本身，而不是工具。

With agents, does it become practical to have large codebases that can be read like a narrative, whose prose is kept in sync with changes to the code by tireless machines?
有了代理，是否可以实用地让大型代码库像叙事一样被阅读，其文字能够通过不知疲倦的机器与代码的更改保持同步？
I think that’s a compelling question.
我认为这是一个引人深思的问题。

---

脚注

The lack of metadata in Markdown also means that there is nowhere to store information about code blocks that would be extracted from a literate document. Org Mode provides [header arguments](https://orgmode.org/manual/Using-Header-Arguments.html) that can be applied to source code blocks, providing instruction to the machine about execution details like where the code should be executed, which might even be a remote machine.

Footnotes

1. 示例我探索的用例。 ↩

2. 我应用文学化编程的另一个不同场景。 ↩

3. 我把编写运行手册的 LLM 称为 “clanker”。 ↩

4. Org Mode 有类似 properties 的概念，允许通过 Emacs Lisp 对文档进行编程操作。过去这意味着我经常会被诱惑去摆弄 Lisp 一段时间，以在文档中实现某些想象中的交互功能，而实际上我根本没有时间去实现。但现在 LLM 会乐意把一些 Emacs Lisp 放进文档的 file‑variables 部分，为该交互文档提供定制功能。 ↩ ↩²