代码是写给人看的？时代已经变了

一个触发重构的信号 #

我在做的一个项目是基于 Web 的文件管理系统，支持本地文件和 WebDAV 协议，除了基本的目录和文件操作，还支持图片浏览和视频播放。今天花了不少时间在视频播放部分——多种格式、格式探测、浏览器能力探测、转码策略、边转边播还是全转再播，这一套下来，核心的后端服务文件已经来到了一两千行。

功能完成之后，我照例看了一眼被修改的文件。一个文件里揉进了 FFmpeg 调用、格式探测、转码策略、网络响应，功能全混在一起，加上文件本身已经很长。这个直接触发了我的重构信号。

让 Agent 来做重构 #

我没有开新会话，因为当前这个会话已经对整个上下文有了足够的了解。我让 Agent 制定重构计划，再生成一份细节丰富的提示词，交给下一个对话继续执行。

重构完成之后，我突然意识到一件事：我过去做重构，目的是让自己看得懂、将来好维护。但现在这份代码，几乎都是 Agent 在维护。我已经很少手动改代码了。

那"为了我自己可维护"这件事，还成立吗？

面向 Markdown 编程 #

这个问题带出了今天一整个下午的讨论。结论比我预想的要激进：我现在，特别是自己的项目，已经不怎么看代码了。我是面向 Markdown 编程的。设计文档、决策背景、模块之间的关系——这些我认真写、认真看。代码本身，交给 Agent。

那句话该更新了 #

有一句话，出自《SICP》，在程序员里广为流传：

代码是写给人看的，只是机器恰好可以运行。

这句话现在要改一改了。

代码的读者已经不只是人。人靠理解读代码，Agent 靠检索和上下文读代码。写给人看，需要清晰的结构；写给 Agent 看，还需要显式的意图——注释里写清楚这里为什么这么做，而不只是做了什么。好的拆分，不是为了文件短，而是因为"这块逻辑会因为同一个原因变化"才放在一起，让 Agent 在定位一个任务时，不需要同时理解五个不相关的文件。

对 Agent 来说，好的重构是什么样的 #

讨论完之后，我直接把这个问题拿去问了 Codex——对 Agent 维护的代码来说，"好的重构"不是抽象得漂亮，而是下一次改动时能低风险、低上下文成本地继续做事。

它的判断标准是这样的：下一位 Agent 改一条播放规则时，不需要先通读一千四百行大文件；决策和副作用分开，"为什么这么播"与"怎么起 ffmpeg、怎么回 HTTP"不要缠在一起；关键策略能被测试直接描述，而不是靠读实现猜；命名直白，文件边界稳定，别做一堆未来可能用不上的框架；外部行为尽量不变，避免"结构变好了，但产品悄悄坏了"。

按这个标准，这次重构大方向做到了，明显变好了，但还没到"非常理想"的终点。我对它说：你看着改，目的是方便你维护，别的不考虑。

两种读者，不同的需求 #

对 Agent 来说，某些对人类有意义的讲究是没有意义的。Agent 没有工作记忆的瓶颈，读一个五千行文件和读五个一千行文件，本身没有本质区别。那些"每个函数不超过二十行"之类纯粹为人类视觉舒适度服务的教条，对 Agent 不重要。真正重要的是信息密度——相关信息有没有聚在一起，意图有没有被显式表达出来。

所以现在我理解代码的方式是：代码是意图的载体，读者从人变成了人机混合。两种读者对代码的需求有重叠，但不完全一样。而我自己，已经活在 Markdown 那一层了。