你以为的 AI 读文档,可能根本不是那么回事

arXiv 2608.20195：北大团队用 557 个 Agent 会话 + 33097 个 PR 数据，揭开了AI 与文档交互的真实模式

本文拆解北大 8 月最新论文，提炼 5 条关于 AI 编码 Agent 与文档交互的可复现规律。如果你在用 AI 辅助编程，5 分钟读完，少走三个月弯路。

你以为的 AI 协作不是这样发生的。

557 个 AI 编码会话、33097 个 Pull Request、3033 次文档交互事件 —— 数据摆在那儿，60.5% 的文档交互是针对 Agent 自己写的文件，人类写的技术文档只占 10.6%。

林浩接了一个电商后台重构项目，客户要求两周内上线 MVP。他信心满满，第一天就拉了七个工作台 —— 一个扒需求、一个画数据库、一个写接口、一个写前端、一个写后端、一个写测试、一个做代码审查。

第二天早上到公司，林浩打开代码一看，傻眼了。数据库设计是那个模型定的，接口文档是另一个写的，但两个对不上 —— 数据库里叫 user_id，接口文档里叫 uid。七个模型各干各的，互不相通。

林浩写了一份三十页的架构文档，把数据库结构、接口规范、前后端约定全部写清楚，让每个模型按文档执行。三天过去了，文档原封不动地躺在仓库里，模型们照旧各干各的。他翻了十几遍文档，确认没有任何歧义 —— 路径写的是 src/api/users.ts，字段名写的是 userId—— 文档没写错，问题出在哪？

那天晚上他刷到凌晨两点，看到一篇八月刚挂出来的。arXiv 2608.20195，北大团队写的，用 557 个 Agent 编码会话和 33097 个 PR 数据，观察 AI 编码 Agent 到底怎么跟文档打交道的。

论文有一张表，列出了 Agent 跟各类文档的交互频率：指令文件（AGENTS.md、CLAUDE.md、SKILL.md）占 35.4%，工作笔记占 25.1%，两者合计 60.5%。人类写的 API 参考文档 1.3%、故障排除 0.4%、测试文档 1.0%、架构文档 4.0%，加起来才 10.6%。

林浩盯着 60.5% 这个数字看了很久。

更反直觉的发现接踵而至：Agent 读取文档后直接写代码的概率只有万分之二，更倾向于继续读文档或推理。文档读取后运行测试的概率比基线低得多 —— 可能是因为读文档常发生在调试阶段。论文分析了多 Commit PR 里代码和文档的触碰顺序：代码先被触碰 47.3%，文档先被触碰仅 10.0%，综合起来代码在文档之前的概率是后者的 4.7 倍。线性模型在这组数据里根本不存在，真实的交互模式是 "双叶循环"：读取叶和生产叶各自成簇，Agent 在之间来回走。

林浩突然明白了。他写的三十页架构文档没人读，不是因为写得不好，而是因为那不是 Agent 会读的东西。Agent 读的不是人类写的文档，而是自己生成的东西 —— 工作笔记和指令文件，人类文档对 Agent 的吸引力只有 10.6%。

那晚他没睡，直接在仓库里新建了 AGENTS.md。没用模板，没写套话，用最直白的话写了三段：项目背景、关键约定（camelCase、kebab-case、ISO 8601、错误码从 1000 开始）、工作流（先列计划再写代码，每写一个模块写一行验证笔记）。让最新的模型重新读一遍，从数据库层开始写。

第二天早上到公司打开仓库，代码已经生成了 —— 数据库迁移、API 路由、用户模块，全部按约定来的。老张推门看了一眼屏幕，说你这模型怎么突然开窍了。

他笑了笑，没解释。是文档的位置换了 —— 从人类阅读的文档，换成了 Agent 会读取的文档。项目最终提前半天上线，客户在微信里回了四个字：做得不错。

后来林浩复盘时说，自己以前一直有误区，觉得写文档就是写给人类看的。但论文数据告诉他，Agent 读人类写的文档概率只有十分之一，主要读的是自己生成的东西。所以 "Agent 友好文档" 的关键不是写得更清楚，而是写得更对。

他办公室的白板上现在贴着一张打印的论文截图，就是那张文档交互频率分布表。旁边用黑色马克笔写了一行字：

文档不是写给谁看的，是让谁读的。

林浩的故事讲完了。这篇论文的价值不在于某个创业者的顿悟，而在于它把 "AI 编码 Agent 到底怎么跟文档打交道" 变成了可以被测量、被验证、被复现的数据。

以下为 Obsidian 适配版知识卡（直接复制即可用）

title: "From Agent Behaviour to Agent-Friendly Documentation - AI 编码 Agent 与文档交互的实证研究"

arxiv: "2608.20195"

authors: ["Zhijun Gao", "Jing Chen"]

institution: "北京大学"

date: 2026-08-20

tags: [AI Agent, 编码 Agent, 文档交互，实证研究，软件文档，Agent 行为，Trace 分析]

source: ""

status: 已读

rating: 5

T0・论文在做什么

这篇论文是第一个基于真实轨迹数据的 AI Agent 与文档交互行为研究。作者结合两个公开数据集 ——557 个真实 Agent 编码会话（SWE-chat）和 33,097 个 Agent 提交的 Pull Request（AIDev）—— 分析了 Agent 如何发现、读取和编写技术文档。核心发现挑战了当前 "Agent 友好文档" 的所有直觉假设：Agent 60.5% 的文档交互针对的是 Agent-facing artifacts（AGENTS.md、CLAUDE.md、agent working notes），而非传统的 API 参考；读取文档后极少直接写代码（转移概率 0.002），更多是继续读文档（0.270）或推理（0.245）；从未观测到文档驱动代码执行的线性路径；代码总是先于文档被触碰。

T1・三句话说清论文

做什么：

对 557 个真实 Agent 编码会话和 33,097 个 Agent PR 进行行为分析，首次实证刻画了 Agent 与技术文档的交互模式。

发现什么：

线性 "发现→检索→应用→验证→更新" 模型不成立 —— 两个核心阶段（Validate 和 Escalate）完全未观测到，核心交互是 "读取→继续读取"（0.270 转移概率），文档创建几乎与读取等频（1,401 个生产事件 vs 1,344 个检索事件）。

意味着什么：

当前 "Agent 友好文档" 指南（清晰标题、可运行示例、llms.txt）缺乏行为证据支持；Agent 主要在与自己产生的文档交互，而非人类编写的文档。

T2・提炼的规律

每条规律建议拆为独立原子笔记，主笔记保留索引：

[[规律 - Agent 主要与自己生成的文档交互]]

[[规律 - Agent 文档交互呈双叶循环结构]]

[[规律 - 代码先于文档被触碰 4.7 倍]]

[[规律 - 文档读取后测试运行概率显著偏低]]

[[规律 - 涉及文档的 PR 合并率更高]]

规律一：Agent-facing 文档占 Agent 文档交互的 60.5%，远超传统技术文档

当分析 Agent 对仓库中各类文档的访问频率时，Agent-facing 文档占 Agent 文档交互的 60.5% 这一结果可复现地发生，远超传统技术文档。

可复现条件：分析 Agent 对仓库中各类文档的访问频率，数据集覆盖 SWE-chat（557 个会话）和 AIDev（33,097 个 PR）。

可复现结果：Agent-facing 文档（指令文件 + 工作笔记）合计占 60.5%，传统技术文档（API 参考 + 故障排除 + 测试 + 示例 + 架构）合计仅 10.6%。

论文验证：SWE-chat 数据中 3,033 个文档交互事件分布 ——Agent 指令文件（AGENTS.md、CLAUDE.md、SKILL.md 等）35.4%；Agent 工作笔记（计划、thoughts / 目录、脑暴、验证日志）25.1%；传统技术文档 API 参考 1.3%、故障排除 0.4%、测试文档 1.0%、示例 0.9%、架构 / ADR 4.0%。

规律二：Agent 与文档的交互呈 "双叶循环" 结构，线性模型不成立

当分析文档交互事件的转移概率矩阵时，Agent 与文档的交互可复现地呈现 "双叶循环" 结构，读取叶与生产叶各自成簇，线性的 "发现→检索→应用→验证→更新" 路径不存在。

可复现条件：分析文档交互事件的转移概率矩阵。

可复现结果：检索叶（Orient→Discover→Retrieve→Interpret）最强转移是 Retrieve→Retrieve（0.270）；

生产叶（Contribute/Update）1,401 个事件，比检索（1,344）还多；Validate 和 Escalate 两个阶段出现零事件。

论文验证：论文第 5 节详细报告了转移概率矩阵，"Apply"（文档→代码）是最弱的连接 —— 未调整 lift 仅 1.05，调整后 OR=1.33（CI 1.09-1.62）。

规律三：代码在文档之前被触碰的概率是文档在代码之前的 4.7 倍

当分析多 Commit PR 中代码和文档的触碰顺序时，代码在文档之前被触碰这一结果可复现地发生，概率是文档在代码之前的 4.7 倍，与 "Agent 友好文档" 指南假设的 "先读文档再写代码" 完全相反。

可复现条件：分析多 Commit PR 中代码和文档的触碰顺序，数据集为 AIDev 中 4,386 个同时包含代码和文档变更的多 Commit PR。

可复现结果：代码先被触碰 47.3%，同一 Commit 中触碰 42.6%，文档先被触碰仅 10.0%。综合概率比为 4.7:1。

论文验证：AIDev 数据（Table 5b）—— 综合代码先触、同一 Commit 触、文档先触的比例，代码在文档之前被触碰的概率是文档在代码之前的 4.7 倍。

规律四：文档读取后测试运行概率显著低于基线

当分析文档读取事件后 3 步内的动作概率时，文档读取后测试运行概率显著低于基线这一结果可复现地发生（lift=0.23），读文档不是通向代码执行的桥梁。

可复现条件：分析文档读取事件后 3 步内的动作概率，对比文档读取后测试运行概率与基线概率。

可复现结果：文档读取后测试运行概率仅 0.5%（基线 2.2%，lift=0.23）；构建概率 0.4% vs 2.5%（lift=0.15）。

论文验证：这可能是读文档发生在调试阶段（54.4% 的文档交互发生在 debugging 阶段），此时系统处于失败状态，测试自然更罕见。

规律五：涉及文档修改的 PR 合并率比纯代码 PR 高 6.1 个百分点

当比较涉及文档修改的 PR 与纯代码 PR 的合并率时，涉及文档修改的 PR 合并率更高这一结果可复现地发生，比纯代码 PR 高 6.1 个百分点（81.1% vs 75.0%）。

可复现条件：比较涉及文档修改的 PR 与纯代码 PR 的合并率。

可复现结果：涉及文档的 PR 合并率 81.1%（CI 80.4-81.8%），纯代码 PR 合并率 75.0%（CI 74.4-75.7%），差异 6.1 个百分点，统计显著。

论文验证：Table 5c 报告了该结果。论文明确声明这是关联而非因果 —— 涉及文档的 PR 可能本身就是更高质量的 PR。

T3・适用边界与防坑

论文实验基于开源软件项目的 Agent 编码任务（SWE-chat 和 AIDev 数据集），向客服、内容生成、医疗等领域迁移时，交互模式可能完全不同，需自行验证。

研究观察的是仓库本地的文件级文档交互，不覆盖通过浏览器读取的 API 网站、模型权重中的先验知识、或代码内的 docstring。

规律五是关联而非因果 —— 涉及文档的 PR 合并率更高，可能是因为高质量的 PR 本身就附带了文档，而非文档导致了高合并率。

同一 Commit 中代码和文档同时触碰占 42.6%，这种情况下无法确定触碰顺序，将这部分全算作文档优先，文档优先的比例也不会超过 53%。

T4・作者观察与实战结论（非论文数据，属个人观点）

这篇论文最直接的启示是：如果你在用 AI 编码 Agent，你的 "文档" 应该写给 Agent 读，而不是写给人类看。传统文档指南强调清晰标题、完整结构、可运行示例，但论文数据表明，Agent 读人类文档的概率只有 10.6%。

实操建议：

把 AGENTS.md 或 CLAUDE.md 当成 "Agent 的笔记本"，用直白口语写，别用模板。

写代码前先让 Agent 写计划，写完每个模块让 Agent 写验证笔记 —— 这些笔记就是 Agent 最可能读的东西。

不要指望 Agent 会主动读你写的架构文档或 API 参考。如果想让它遵守规范，把规范写在它自己的文件里。

文档的价值不在 "写得好"，在 "被读了"。一个 Agent 会读、读了就照做的简单约定，比一份人类觉得完美但没人碰的三十页文档值钱得多。

实验基础

SWE-chat：557 个真实 Agent 编码会话，3,033 个文档交互事件，覆盖开源软件项目中的编码任务。

AIDev：33,097 个 Agent 提交的 PR，其中 4,386 个为多 Commit PR 且同时包含代码和文档变更。

转移概率矩阵：基于文档交互事件序列构建，包含 Orient、Discover、Retrieve、Interpret、Apply、Contribute、Update、Verify、Build、Test 等状态。

统计显著性：所有 lift/OR 值均报告了置信区间（CI），规律五的合并率差异经统计检验显著。