From Agent Behaviour to Agent-Friendly Documentation: An Empirical Study of How Coding Agents Discover, Read, and Write Technical Documentation
Zhijun Gao, Jing Chen
cs.SE, cs.AI, cs.HC
2026-08-20
北京大学用 557 场会话和 3.3 万个 Agent PR 发现：文档互动 60.5% 落在 AGENTS.md 一类指令和自写笔记，API 参考仅 1.3%；读完立刻改代码几乎不发生。
软件文档研究默认读者是人：会迷路、会问同事、会按任务去翻 API 手册。现在开源仓库里越来越多改动是编码 Agent 自己写的，它们读仓库、跑命令、开 PR。业界已经开始写 AGENTS.md、llms.txt、可运行示例，号称「对 Agent 友好」。这些建议建立在 Agent「应该」怎么用文档上，几乎没有人量过它们实际怎么用。
北京大学高志军、陈静用两份公开数据把这件事钉到行为轨迹上：SWE-chat 里 557 场真实会话、94,813 条开发事件（其中 3,033 条是文档互动）；AIDev 里 33,097 个 Agent PR、690,260 条文件级变更。问题不是怎样写更好的文档，是 Agent 碰到文档时到底在干什么。
两套数据回答不同问题，从不混在一起算。SWE-chat 给过程：从四种互不兼容的会话格式里抽出 20 类事件，按路径规则给文档分 15 类，再用语言模型给 54% 的残差路径打标（500 条路径覆盖 98.4% 的模糊事件）。agentworkingnote 这个大类就是从残差里长出来的，初始方案里根本没有它。每个文档事件再标互动类型（Discover / Search / Read / Edit / Create）、触发（往前看 4 个事件）和阶段（定向、实现、验证、调试、交付）。有的 Agent 把改文件藏在 shell 的 applypatch here-document 里，不解析命令字符串，整族会显示零次文档互动。
AIDev 给产物：在星数大于 100 的仓库子集上，按路径判断一次 PR 改了代码、文档还是两者，再看多 commit PR 里谁先动。
统计上他们很克制。事件套在会话里、PR 套在仓库里，不能当独立抛硬币。主区间用 cluster bootstrap（2,000 次，按会话或仓库整簇重抽）；读文档之后三步内发生什么，再用按会话聚类的 logistic GEE，控制阶段、位置、会话长度和 Agent 家族。抽样故意过采样少数 Agent，所以主数字同时给事件加权、会话等权和按语料 Agent 分布回权三套。
观察范围写死了：只看得见仓库内、走文件路径的文档操作。浏览器打开的 API 网站、模型权重里的知识、源码注释、运行时预加载的 context 文件（除非后来又显式读一遍）都不在账上。指令文件的曝光是下界。
核心分布和文档研究的默认图景对不上。
| 文档类型 | 事件数 | 占比 |
| Agent 指令文件（AGENTS.md、CLAUDE.md、SKILL.md 等） | 1,074 | 35.4% |
| Agent 工作笔记（plans、thoughts/、brainstorm） | 760 | 25.1% |
| 任务 / 需求 | 301 | 9.9% |
| 配置 | 205 | 6.8% |
| README | 197 | 6.5% |
| 九类「经典技术文档」合计 | 323 | 10.6% |
| API 参考 | 40 | 1.3% |
| 排障文档 | 11 | 0.4% |
面向 Agent 的两类加起来 60.5%（簇区间 53.9–66.5%）。按 Agent 回权后掉到 55.1%；只看「读」这一侧，回权后大约一半（50.1%），不再是稳稳的多数。API 参考只占可观察的仓库内查阅的 2.3%。指令文件的互动量大约是 API 参考的 27 倍。
读完立刻改代码几乎不发生：P(edit code | read doc) = 0.002，1,328 次读里只有 3 次。读完更常继续读（0.270）或进入推理（0.245）。三步窗口里，跑测试的 lift 是 0.23（簇区间 0.08–0.45，调整后 OR 0.39），构建是 0.15（OR 0.25）；这两项未调整和调整后都站得住。读完写文档（lift 1.67）和读完改代码（lift 1.05 / OR 1.33）则对调整敏感，论文自己标成未解决。
触发侧：70.2% 是 Agent 自己发起，失败驱动只有 7.5%，差 9.3 倍。2,034 次失败片段里，第一步去读文档的只有 109 次（5.4%）；更常见的是读代码（31.0%）、直接重试（19.9%）、直接改（15.3%）。排障文档在整个语料里只有 11 次。
产物侧，Agent 写文档几乎赶上读：生产 1,401 次，咨询 1,615 次，比值 0.87。AIDev 上 41.5% 的 Agent PR 会改文档（簇区间 35.8–45.4%）。能分出先后的多 commit PR 里，代码先动是文档先动的 4.7 倍（不同 commit 时 82.5% 代码在先）。被改最多的文档文件包括 AGENTS.md（692 个 PR）、CLAUDE.md（362）、copilot-instructions.md（287）：Agent 在改自己下次要读的说明书。
他们据此丢掉「发现→检索→理解→应用→验证→更新」这条直线，改成两叶循环：咨询叶在读和推理之间打转，生产叶独立写文档，两叶之间的耦合在不同模型设定下对不上，验证叶在工具调用轨迹里是零。
给仓库维护者的直接含义很窄、也很硬：有限的文档工时，改 AGENTS.md / CLAUDE.md 比打磨 API 参考手册更能碰到 Agent。Agent 几乎不跟文档超链接（Follow-reference 一次都没观察到），读完接着读，更吃自包含、本地可检索的结构。
另一件被漏掉的事：plans、thoughts/ 这类 Agent 自写笔记已经占互动的四分之一，会作为持久文件留在仓库里。现有的文档质量指标、review checklist、仓库卫生工具还没有这个类别。论文没量过这些文件会不会过期、会不会互相打架，只量了体量。
「可执行、可验证」仍然可以是设计目标，但不是从这批行为里长出来的。语料里看不到 Agent 拿散文当 oracle 去对代码；要让验证变得可观察，更可能需要 doctest、schema contract 这类能跑的东西。这是干预假设，不是发现。
最大的洞在分类器。agentworkingnote 这个占 25.1% 的新类，来自语言模型给 500 条模糊路径打的标，没有人工校验。论文自己说下一步必须双人编码 200–300 条再报 kappa。精确占比是暂定的；「存在一大类以前没人统计的 Agent 自写文档」比那个 25.1% 更稳。
仪器只能看见路径。docstring、行内注释、浏览器打开的外部 API 网站全是盲区。绝对发生率是下界。阶段标签会粘在 debugging 上，所以他们只敢说文档互动不只发生在任务开头，不敢拿 54.4% debugging 当精确分配。
SWE-chat 是自愿上报，语料 87% 来自单一 Agent 家族（Claude Code 占已标注会话的 83.8%）。Cursor 那 11 场会话文档互动是 0，论文明确警告这更像抽取覆盖问题：有的 Agent 把文件操作藏在 shell 命令字符串里，不解析 here-document 就会整族归零。不能拿跨 Agent 的会话占比当行为差异。
读完改代码的相邻转移接近零，挡不住更长程、或藏在推理文本里的影响。三步 lift 是补救，补救之后这项仍然未解决。失败恢复里「读文档」的解决率点估计最高（7/11 = 63.6%），区间 35.4–84.8%，和所有策略重叠，论文拒绝排名。
两份数据不是同一总体，私有代码库、非 CLI Agent、未来一两年的惯例都可能改掉那个 60.5%。能指望留下来的是类别存在且突出，不是精确份额。