我们不得不为人工智能编写文档：《大语言模型说明文件》改变了一切

大多数开发者为人类编写文档。

在构建我的 JavaScript 框架时，我遇到了一个始料未及的问题：框架本身运行正常，但人工智能却无法使用它。不是“不够完美”，也不是“犯些小错误”，而是除非能访问框架的源代码，否则它完全无法正确构建哪怕是最基础的应用程序。

事情崩溃的那一刻

经过数年努力，我终于拥有了一套稳定的系统：自定义的扫描器、解析器、解释器、带组件的模板引擎、基于信号的响应式系统，以及大约 600 个覆盖边界情况的测试用例。我以为大功告成了。

于是我尝试了一个简单的任务：“使用这个框架构建一个待办事项应用。”

我收到的回复看起来信心十足，但内容却完全错误：语法错误、心智模型错误，甚至还凭空捏造了根本不存在的功能。

这并非框架本身的缺陷，而是文档的失败。

自述文件已不再足够

传统文档是为人类设计的：采用叙述性解释、循序渐进的入门引导，以及穿插故事性的示例。

但人工智能并非如此工作。它不会真正“阅读”文档，而是通过模式匹配和猜测来推断。因此，当文档不完整、含糊不清或过于偏重叙述性文字时，人工智能便会自信而错误地自行填补空白。

解决方案：llms.txt

事后看来，解决方案其实很简单：把人工智能当作严格的编译器对待，而非普通读者。

我创建了一个新文件：llms.txt。这不是营销文案，也不是教程，而是一份纯粹、明确的规范说明。

规则非常严格：

禁止叙述性文字。 不讲故事，不做解释，只包含语法、规则和约束条件。

杜绝歧义。 以下两种表述存在巨大差异：

你可以使用 @if 进行条件渲染。

与：

@if="condition"
- condition 必须是有效的 JS 表达式
- 根据表达式的真值/假值进行判断
- 若为假值，则从 DOM 中移除该节点

覆盖全部接口。 所有指令、模板表达式、组件、生命周期钩子、信号行为等，都必须明确定义，不得有任何隐含内容。

提供简洁但真实的示例：

<ul>
  <li @each="item in items" @key="item.id">{{ item.name }}</li>
</ul>

阅读文档与源代码

即便有了 llms.txt，人工智能也无法凭空猜出所有细节。它需要大量阅读源代码，检查函数签名，理解信号如何传播，观察组件生命周期如何运作。只有这样，它才能将规范映射到实际实现，并生成可运行的应用程序。

构建应用程序并非魔法，而是人工智能 + 规范 + 代码理解力的结合。

迭代循环

我并没有简单地交出文件就寄希望于成功。整个迭代循环如下所示：

1. 向人工智能提供当前的 llms.txt 文件及源代码访问权限
2. 要求它构建一个真实的应用（如待办事项、看板等）
3. 观察其失败之处
4. 修正规范文档
5. 重复上述过程

在此过程中，一些关键问题逐渐清晰起来。

缺失的功能并不总是显而易见。 曾有一段时间，人工智能不断尝试使用 @keydown.enter。我从未对此进行过文档说明，但……