Agent 怎么用文档？

论文：From Agent Behaviour to Agent-Friendly Documentation（arXiv:2608.20195）
https://arxiv.org/abs/2608.20195

核心问题：大家都在教你怎么写「对 agent 友好的文档」，却没人真正观察过 agent 实际怎么用文档。这篇论文用 557 段真实编码会话（9.4 万事件）和 3.3 万个 agent PR（69 万文件变更）做了实测，结论有点扎心：

· 60.5% 的文档交互落在「因 agent 而存在」的制品上（指令文件 AGENTS.md/CLAUDE.md 占 35.4%，工作笔记占 25.1%），经典技术文档仅 10.6%，API 参考低至 1.3%。
· 流行的两大假设站不住脚：可操作性（读文档→写代码的相邻转移概率仅 0.002）、可验证性（整个语料零个显式验证事件）。
· agent 自驱查文档占 70.2%，只有 7.5% 由失败触发——文档并不是「卡住时的救命稻草」。

论文本身只诊断、没给成熟方法论，但给了一条最实在的启示：把写文档的精力从 API 参考转到 instruction 文件上。

#agent #上下文