论文链接：From Agent Behaviour to Agent-Friendly Documentation: An Empirical Study of How Coding Agents Discover, Read, and Write Technical Documentation 发表时间：2026年8月 机构：北京大学（Zhijun Gao、Jing Chen） 领域标签：cs.SE（软件工程实证研究）、Agent、技术文档

一、论文背景

1.1 编码Agent正在成为文档的新读者

如果你在2026年打开任何一个活跃的开源仓库，很可能会在根目录看到一两个特殊的文件：AGENTS.md或者CLAUDE.md。这些文件不是给人看的——它们是写给AI编码Agent的「入职手册」，告诉Agent这个项目用什么命令跑测试、遵循什么代码规范、哪些文件不能碰。Claude Code读CLAUDE.md，Codex CLI、Gemini CLI、Copilot CLI、Cursor读AGENTS.md。截至2026年，AGENTS.md已成为Linux基金会下属Agentic AI Foundation托管的开放标准，被超过六万个开源项目采纳。

这些文件的出现标志着一个结构性变化：软件文档的读者群里，出现了一个新物种。传统的文档质量框架、陈旧度度量、可读性指南，全都预设读者是一个「会形成意图、会困惑、会问同事」的人类开发者。而现在，越来越多的代码变更由自主编码Agent完成——它们读仓库、执行命令、提交PR，每一步都不需要人类在场。

1.2 行业建议先行，行为证据缺位

面对这个新读者，行业里迅速涌现出一批「agent-friendly documentation」（Agent友好文档）的建议：写清晰的标题、提供可运行的示例、发布llms.txt（为LLM准备的Markdown格式文档索引，2024年9月由Jeremy Howard提出后已被广泛采纳）、附上OpenAPI规范等等。各种「让AI读懂你的文档」的指南层出不穷。

但这些建建立在一个从未被验证的假设之上：它们基于对Agent「应该」如何行为的直觉，而不是对Agent「实际」如何行为的观察。Agent真的会去读API参考文档吗？读完后真的会照着写代码吗？真的会用文档来核验自己的工作吗？在本文出现之前，没有人系统测量过。

之所以一直没人测，是因为测量本身很难：商业Agent的对话轨迹不公开，而学术基准（如SWE-bench）只奖励「补丁让测试通过」，完全不为文档工作记分——正如论文所言，「没有基准奖励文档工作，证据必须来自观察性数据」。

1.3 两个公开数据集让测量成为可能

2026年，两个互补的公开数据集改变了局面：

• SWE-chat（斯坦福大学，arXiv:2604.20779）：第一个大规模真实编码Agent会话数据集，由开源开发者自愿贡献，包含约6,000个会话、63,000+用户提示、355,000+Agent工具调用，且是持续更新的「活」数据集。它记录过程——完整的对话、工具调用、工具返回。
• AIDev（加拿大女王大学，MSR 2026）：93万余个由五款Agent（OpenAI Codex、Devin、GitHub Copilot、Cursor、Claude Code）在真实GitHub仓库提交的PR数据集，横跨116,211个仓库。它记录产物——commit、文件级diff、评审、时间线。

过程与产物，恰好是同一枚硬币的两面。本文的作者——北京大学的Zhijun Gao与Jing Chen——把这两个数据集拼在一起，第一次给「Agent如何使用文档」这个问题装上了测量仪器。

1.4 核心悬念

带着行业直觉走进这项研究，你会期待看到什么？Agent查API参考、读架构文档、在调试时翻故障排查指南、读完后照着写代码。而论文给出的答案几乎每一条都与此相反——Agent的文档世界，是一个由Agent自己创造、自己消费的世界，经典技术文档在其中只占边缘位置。

二、论文定位和关联工作

论文梳理了五条相关工作脉络，并指出它们共享一个被本文数据挑战的隐含假设：Agent咨询的文档是为人写的、关于代码的、且由他人生产的。

2.1 编码Agent与LLM软件工程Agent

这条线以SWE-bench为核心的评价体系定义了「Agent的任务是解决issue」，SWE-agent、AutoCodeRover、OpenHands等架构都以「文件+shell的动作空间」来描述，但综述盘点Agent能力时没有一类是文档。观察性研究里，轨迹分析比较成功与失败运行的动作序列，但没有把文档编码为工件类别；工件研究挖掘Agent PR的采纳率、活跃度、PR描述、重构、日志、失败原因——其中「Agent是否像人类一样写日志」的研究为本文提供了模板：问一个非功能性关注点在Agent手里发生了什么变化。本文问的是同样的问题，并测量了一个此前无人报告的量：Agent生产文档的速率是咨询速率的0.87倍。

2.2 LLM之前的软件文档研究

LLM之前的实证研究提供了最清晰的对照基线：人类开发者其实更依赖代码和同事而非文档；他们围绕陈旧度选择性咨询；把需求表述为任务形态的问题；经常上网搜外部信息。程序理解占用了开发者大部分时间，但文档并非其主要输入。对照这个基线，本文的发现相当意外：文档交互出现在56.7%的采样会话中，且70.2%是自发的——这正是文档工程研究长期想鼓励人类开发者养成却被证明很难的行为。更尖锐的反差在「读什么」：既有文献几乎全部围绕API参考，而本文数据显示API参考只占Agent文档交互的1.3%。

2.3 代码-文档协同演化

AIDev部分建立在成熟的协同变更挖掘传统上：注释更新不及时、不一致且与缺陷相关、重构时注释静默损坏、文档链接衰减。本文把协同变更挖掘方法应用到Agent PR的文件级别，得到两个观察：41.5%的文档变更率相对人类注释维护文献报告的比率是高的；在顺序可观测之处，文档滞后于代码。而该文献考虑「用文档核对代码」时，核对者是静态分析器，从不假设Agent会做这件事——与本文观察到零次验证事件一致。

2.4 LLM、文档与Agent上下文文件

检索增强研究把文档当作模型输入：检索提升代码生成、仓库级检索、DocPrompting等。这条线最直接地编码了本文挑战的假设——「文档的价值在于作为可检索的API参考，由模型之外的系统注入」。而本文数据里的Agent打开的是被要求遵守的指令文件和自己写的笔记，这些交互是自发的而非外部检索的。

2025-2026年新兴的上下文文件文献结论并未收敛：描述性研究刻画AGENTS.md/CLAUDE.md；苏黎世联邦理工的评估研究发现LLM生成的上下文文件反而降低约3%任务成功率、人工编写的仅提升约4%、推理成本增加20%以上；还有研究发现「随机规则与精心策划的规则帮助一样大」。维护研究报道了上下文文件的陈旧与无界增长。但没有任何工作测量过：Agent相对于其他所有阅读物，多频繁地咨询这些文件。本文的35.4%（指令文件）与25.1%（工作笔记）首次给出了分母。## 2.5 方法先例

软件事件日志的过程挖掘、IDE交互流的序列挖掘都是成熟方法。论文明确指出：其编码方案尚未做人工验证，未来应按Cohen κ或Krippendorff α的成熟信度框架补做——本文没有报告这类统计，主要区间采用簇自助法，Wilson区间仅作独立性假设下的参照。## 2.6 定位总结

定位结论：本文是第一个把「Agent-文档交互」作为测量对象的行为接地实证研究，它的贡献不在于提出新方法，而在于给一个正在被行业直觉快速塑造的领域提供了第一批行为基准线——包括正面的（agent-facing工件占60.5%）和负面的（可操作性、可验证性缺乏行为支持）。

三、问题定义

3.1 从具体场景到抽象问题

具体场景：一个Agent在真实仓库里工作了几十轮，读了些文件、改了些文件、跑了些命令。我们想知道它和「文档」的关系。但这立刻遇到一个测量难题：「用文档」这个日常语言概念无法直接观测。一次文件读取可能出于无数意图，从工具调用日志里反推意图是不可证伪的。

论文的核心抽象是：把「Agent与文档的关系」操作化为可观测事件流上的统计量。具体拆解为三个研究问题：

• RQ1：Agent对文档做了什么？哪些文档类型、哪些任务阶段、通过哪些行为？
• RQ2：文档交互之前是什么、之后是什么？哪些事件触发咨询，咨询后哪些开发动作更可能或更不可能发生？
• RQ3：代码-文档循环是双向的吗？Agent是否既消费又生产文档？相对代码的先后顺序如何？

3.2 关键的操作化决策

这个抽象之所以精妙，在于几个关键决策：

决策一：不编码意图（purpose）。作者最初的方案里包含「交互目的」维度，后来删掉了——目的无法从工具调用日志中恢复，给一次文件读取指派意图是不可证伪的。他们转而报告三个可观测的替代物：触发（trigger，四事件回看窗口）、交互类型（interaction type）、结果（outcome）。这一刀切得极有纪律性：宁可少回答一个问题，不编造一个答案。

决策二：用lift而非条件概率。RQ2的核心量不是「咨询后做X的概率」，而是「咨询后做X的概率相对同一会话非锚点事件做X的基率提升多少倍」（lift）。因为一个在会话全程都很常见的动作，自然也会频繁出现在咨询之后——不除以基率就会自欺。这是流行病学中标准的风险比思维迁移到行为分析。

决策三：vendored路径标记而非丢弃。读node_modules/pkg/README.md是真实的文档交互，尽管仓库并不拥有该文件——单独打标而非粗暴丢弃。

3.3 形式化

给定：真实Agent会话的事件序列（20符号字母表编码）与Agent PR的文件级变更记录。

求：文档交互事件的类型分布（RQ1）、咨询锚点后三事件窗口内各动作的lift与调整后OR（RQ2）、消费/产出比与代码-文档先后顺序（RQ3）。

约束：所有结论限于可观测切片——仓库内、基于文件路径的文档交互。浏览器里读的API网站、模型权重里已有的知识、源码内docstring，仪器看不见。所有断言都带着这个边界。

精妙之处：这个定义把一个规范性问题（「什么文档对Agent好」）暂时悬置，换成一个描述性问题（「Agent实际怎么和文档交互」）——后者的答案才有资格成为前者的前提。这正是实证科学「先测量、后规范」的纪律。

四、问题解法

4.1 双数据集互补设计

两个数据集描述相关但不同的总体，作者明确把它们当互补证据用而从不合并分析单元——SWE-chat没有合并结果，AIDev没有工具轨迹，谁也替代不了谁。数据清洗全部显式报告：AIDev的commit-details表从711,923行出发，剔除5,132行空文件名（0.72%）与16,531行vendored路径（2.32%）后留下690,260行、278,192个唯一路径（其中29,597个文档路径）；33,596个PR中33,097个（98.5%）至少保留一个具名非vendored文件。

4.2 分层抽样

SWE-chat发布版含5,851个会话（10.4 GB），全部处理不现实。作者按Agent × 会话长度双重分层抽样（轮数≤3、4-8、9-18、>18四档），故意过采样少数Agent以支持分Agent估计，排除超过25 MB的转录（语料最大61.8 MB），得到559个会话，其中557个成功解析出事件。因为分配非比例，Agent级统计单独报告、绝不合并。

4.3 两层文档识别器

Tier 1（确定性）：文件名与路径规则，把路径分入15种文档类型之一，外加两个正交标志——machine_readable（OpenAPI、JSON Schema、Protobuf，既是API文档又是可执行规范）和vendored（第三方路径）。非文档文件获得source/config/test/data/build/other等类型，于是同一个函数同时服务文档识别与协同变更分析。

Tier 2（消歧）：Tier 1把54%的文档事件放进了残余类别。作者用语言模型对残余中527个不同路径分类：500个获得标注（覆盖98.4%的模糊事件），27个走关键词回退规则。这一层带来了整个研究最重要的意外发现：残余路径的主导成分是Agent自己写的计划、thoughts/目录、头脑风暴、验证日志——一个初始方案里根本不存在的类别agent_working_note就此涌现。这25.1%的事件不是设计出来的，是数据逼出来的。

4.4 四种转录格式的事件抽取

SWE-chat混合四种互不兼容的转录格式：406个会话用行分隔JSON（content-block工具调用）、100个用单一JSON文档（parts数组）、43个用{type, payload}事件日志、10个用messages数组。每个格式一个抽取器，输出统一的20符号事件字母表——文档事件因此保留在原始轨迹上下文中。

论文坦白记录了两个实质性影响结果的工程缺陷，堪称语料分析方法论的教学案例：

1. shell内嵌路径：某些Agent族把文件操作全部路由到shell，编辑以apply_patchhere-document形式出现，目标路径只存在于命令文本里。不解析这些路径，该Agent族的文档事件数为零。
2. 非字符串工具输出：有些格式里工具输出是列表或字典而非字符串。支持这些类型额外恢复了9个会话、4,358个事件（含77个文档事件）。

两个缺陷都通过「结果不合理」而非专门测试发现。抽取保真度对照SWE-chat自带的tool_call_count：6个抽查会话中5个精确匹配。

4.5 编码方案与派生度量

每个文档事件沿四个维度编码：

开发阶段用轨迹启发式：首次写之前是orientation，首次写之后是implementation，测试或构建通过后是verification，失败信号后是debugging，最后写之后版本控制活动主导时是delivery。每个事件保留其证据字符串，标签全部可审计。

4.6 统计处理

• 簇自助（2,000次重采样）：SWE-chat按会话、AIDev按仓库重采样，固定种子。原因：事件嵌套在会话内、PR嵌套在仓库内——AIDev最大仓库贡献8,911个PR，前十仓库占44.7%，假设独立会把区间压得虚假地窄（簇化使AIDev侧区间加宽至多14倍）。
• 三套权重：合并事件、会话等权、按语料Agent分布重加权（Claude Code占标注会话的83.8%），敏感性分析逐一报告。
• GEE调整：RQ2的动作窗口拟合可交换相关结构的logistic GEE（按会话聚类），调整开发阶段、会话内位置、会话长度对数、Agent族——因为咨询在轨迹各阶段分布不均。调整后估计与未调整lift并列报告，互不替代。

这套统计处理的核心理念可以概括为：凡是有嵌套就聚类、凡是有抽样就加权、凡是调整前后不一致就如实报告为「未解析」。

五、评估指标与实验证据

557个会话共94,813个事件，其中3,033个（3.2%）是文档交互；316个会话（56.7%，簇95% CI 52.6-60.5%）至少含一个文档事件——常见但非普适。

5.1 RQ1：读什么、何时读、怎么读

文档类型分布（表1，全文核心结果；agent-facing类别以†标注）：

指令文件接收的交互约为API参考的27倍。作者对边界做了诚实的敏感性说明：把README、配置、需求文档也算进「经典文档」可把份额抬到33.8%，所以只对极端类别下断言。工作笔记的归类是显式的定义选择——它们是提交到仓库、可被下一个行动者阅读的关于软件的持久散文产物，作者始终单独报告，读者换个边界定义可以重算每个份额（剔除工作笔记后，指令文件单独占47.2%）。咨询/产出拆分（表7）：agent-facing主导在两侧都成立——占咨询的57.4%、产出的63.7%；API参考仅占咨询的2.3%。配置文件最不对称（195次咨询 vs 10次产出），工作笔记则几乎对半（382咨询/367产出）。任务阶段：54.4%的文档事件发生在debugging、27.2%在implementation、15.2%在orientation、3.0%在verification、0.1%在delivery。阶段启发式是「粘性」的（失败信号一出现就停在debugging直到测试通过），所以只推进一个稳健的否定性结论：文档咨询不限于任务开始。

交互类型：Read 1,328、Edit 1,007、Create 394、Search 282、Discover 5。产出（Edit+Create=1,401）以0.87倍于咨询（1,615）的速率发生。初始方案中的三个交互类型完全未被观察到：Compare（对照阅读两份文档）、Follow-reference（沿文档间链接导航）、Verify（用文档核对代码）——可能在模型推理内部发生，但不作为工具调用行为出现，作者选择删除而非报告为罕见。最常见转移概率（会话簇自助95% CI）：

• P(读文档|读文档) = 0.270 [0.232, 0.307] —— 文档阅读成串出现
• P(推理|读文档) = 0.245 [0.205, 0.295]
• P(编辑文档|读文档) = 0.107 [0.081, 0.132]
• P(编辑文档|编辑文档) = 0.350 [0.288, 0.404]
• P(编辑代码|读文档) = 0.002 [0.000, 0.005] —— 1,328次文档阅读中只出现3次

5.2 RQ2：什么触发咨询、咨询之后发生什么

触发分布（表2，n=3,033；仅计咨询时自发62.5%、失败驱动9.7%）：

自发交互以9.3倍多于失败驱动（仅计咨询为6.5倍）。Agent不是「卡住了才查文档」，而是在常规推进中持续用文档。

咨询后三事件窗口内的动作（表3，n=1,615锚点 vs 93,198非锚点基线）：

只有「测试更少」「构建更少」在两种分析下都稳健；两个产出类结果的未调整与调整估计互相矛盾——文档创建调整前升高、调整后含1；代码编辑调整前无差、调整后升高——作者如实标注为「未解析」。没有任何正向的下游动作关联在两种分析下同时稳健——「读文档→写代码→验证」的简单机制得不到一致支持。

失败恢复（表4，2,034个失败episode）：第一个恢复动作是读文档的只有109次（5.4%）；Agent更常读代码（631，31.0%）、直接重试（404，19.9%）、不采取恢复（318，15.6%）、直接编辑（312，15.3%）、搜代码（251，12.3%）。P(读文档|工具错误)=0.020。基于文档的恢复有最高的解决率点估计（7/11=63.6%），但区间35.4-84.8%宽到与所有其他策略重叠——作者明确拒绝据此排名。

5.3 RQ3：消费、产出与先后

会话内：316个有文档活动的会话中，184个（58.2%）既读又写、102个（32.3%）只读、28个（8.9%）只写。

PR层面（表5，AIDev）：

先后顺序（4,386个顺序可观测的多commit PR）：代码先动47.3%、同一commit同触42.6%、文档先动10.0%。当两者在不同commit中变更时，代码先行占82.5%（2,076/2,516，仓库簇CI 78.7-86.0%）——代码先于文档4.7倍。

合并率：改文档的PR合并率81.1% vs 只改代码75.0%，簇化后区间大幅重叠（71.3-85.6% vs 64.9-81.1%），不结论。

Agent修改自己的说明书：AIDev中被改最多的单个文档文件恰是AGENTS.md（692个PR）、CLAUDE.md（362）、copilot-instructions.md（287）。Agent修改塑造Agent行为的文件，闭合了一条现有文档模型未捕捉的回路——从Agent输出回到Agent输入。

5.4 稳健性与变异

• 权重敏感性（表8）：agent-facing占比从60.5%（事件加权）到54.7%（会话等权）与55.1%（Agent重加权）；咨询侧从57.4%降到50.5%与50.1%——恰在50%边界上，即校正后agent-facing文档约占咨询的一半而非明确多数；产出侧反而从63.7%升到67.1%与66.3%。宽模式稳定，具体多数性取决于权重。- 锚点收紧：RQ2锚点只留Read（n=1,328）不改变任何结论（代码编辑lift 1.05→1.10、文档创建1.67→1.83、测试0.23→0.24、构建0.15→0.18）。
• Agent间变异（表9）：会话含文档事件的比例从Gemini CLI的75.0%（9/12）、Claude Code的62.6%（238/380）、OpenCode的45.5%、Codex的37.2%到某Agent的0/11。作者强烈警告不要当行为差异解读——一个Agent几乎全部经shell路由文件操作，路径不解析就零事件，跨Agent比较与抽取覆盖度混杂。## 5.5 双瓣循环模型（第5节）

初始假设的线性旅程「Discover→Retrieve→Interpret→Apply→Validate→Update」被三组证据否定：Validate与Escalate两个阶段零事件；Apply弱证实（仅75个事件，且lift 1.05/OR 1.33互相矛盾）；终段Contribute/Update以1,401个事件成为最大类别（超过Retrieve的1,344）——线性模型把最大的环节排在了最后。替代模型是双瓣循环：

• 咨询瓣（Orient→Discover→Retrieve→Interpret）：内部循环——最强转移是Retrieve自环0.270，最强出边是转入推理0.245。Agent在这一瓣里打转，进入推理多于进入即时行动。
• 产出瓣（Contribute/Update）：文档事件最多的阶段。从咨询进入产出的关联在未调整分析中升高（lift 1.67）但调整后含1——两个连接没有一致的证据。
• 失败几乎不喂入咨询瓣（5.4%），也没有任何观测到的边从任何一瓣进入验证。

十个候选阶段的证据：Contribute/Update 1,401（强）、Retrieve 1,344（强）、Orient 462、Interpret 413、Revisit 360、Discover 287、Recover 109（弱）、Apply 75（弱）、Validate 0、Escalate 0（未证实）。

六、效果优势的根源解释

本文是实证研究而非方法论文，没有「我们的方法优于baseline」；它的「效果」是证据的杀伤力：双数据集的行为证据如何逐条击穿agent-friendly documentation的行业假设。根源解释要回答的是：为什么这些假设在行为数据面前站不住？## 6.1 假设一被击穿的根源：新读者催生了新文体，而行业建议还在优化旧文体

「改进API参考文档质量以帮助Agent」这个建议隐含一个前提：API参考是Agent的主要信息源。60.5% vs 1.3%的悬殊分布击穿了这个前提。机制层面可以追出一条因果链：

Agent的工作方式 → 决定了它读什么 → 决定了哪类文档值得投入。

具体地说，Agent被明确要求遵守指令文件（AGENTS.md是「必须读」的契约），又在有界上下文窗口下需要外部化推理——于是计划、thoughts/目录、验证日志成为工作记忆的载体而非参考资料。这两类工件都是「因为Agent的存在才存在的文档」，而2024年之前的文档分类学根本没有这两个类别——任何没有agent_instruction与agent_working_note类别的分类器都会把多数Agent文档交互扔进残余桶（本文自己的Tier 1最初就把54%的事件放进了残余）。行业建议优化的是1.3%的API参考散文，而Agent实际消费的是60.5%的自有工件——资源错配的根源是测量缺位。

AIDev侧补上了另一环：AGENTS.md被692个PR修改——Agent不仅读指令文件，还改指令文件，形成「输出改输入」的自指回路。这解释了为什么产出侧agent-facing占比（63.7%）甚至高于咨询侧：这个文体的作者和读者是同一个群体。

6.2 假设二未获解析的根源：文档在Agent的工作流中不是「输入→行动」的接点

「可操作性」（actionability）假设：文档写得让Agent能直接照着做，隐含「读→做」耦合。相邻转移概率0.002意味着1,328次阅读只有3次紧跟着代码编辑；读后更常见的是再读（0.270）和推理（0.245）——文档阅读成串、且通向思考而非行动。

为什么耦合这么弱？论文给出两个候选机制（并明确说区分它们需要未来工作）：其一，工作记忆假说——Agent把推理外化到文件是因为上下文窗口有界，文档是工作记忆不是参考手册，读笔记是为了恢复上下文而非获取「可以照做的指令」，thoughts/目录的显著性与此一致；其二，更廉价的神谕假说——Agent不对照散文核验，因为测试套件是更便宜的oracle，直接调用即可。

lift 1.05与OR 1.33的矛盾本身就是证据的一部分：咨询集中在特定轨迹阶段（比如debugging），不调整阶段就把真实的阶段效应误读为文档效应——「读文档的人随后常写代码」可能只是「debugging阶段的人又读文档又写代码」。作者用「未解析」承认了仪器与设计的极限，而不是挑一个好看的数字讲故事。

6.3 假设三被否定的根源：散文不可执行，验证必须被设计出来

「可验证性」（verifiability）假设：文档写得让Agent能对照核验工作。但Validate阶段零事件、Follow-reference零事件、Verify交互类型零事件——没有任何一次观测到的行为是「以文档为oracle核对代码」。且咨询与更少的即时测试（lift 0.23）和构建（lift 0.15）相关。

根源在介质的物理性质上：散文对Agent而言是不可执行的——核对需要Agent「自愿」遵守一段无法强制执行的文字。而测试套件、构建脚本是可执行的oracle，调用即验证。当存在更廉价且强制的验证通道时，依赖Agent自觉的验证通道不会被使用。由此论文给出一个可检验的设计假设而非结论：要让文档验证可观测，需要Agent能执行的工件——可运行示例、doctest、schema契约——而不是必须被信任的散文。这一条在论文里被明确标为「干预研究的假设，不是本研究的发现」，纪律性值得所有实证论文学习。

6.4 「文档滞后于代码」的根源：文档是工作的记录而非规格

代码先于文档4.7倍（可排序场景82.5%代码先行）、41.5%的Agent PR改文档、生产速率为咨询的0.87倍——这些数字合起来描绘的图景是：Agent的文档是事后追认的产出物，不是事前的规格说明。这与「读文档→写代码」的输入模型完全相反：文档跟着代码走，为已完成的工作留下可读的痕迹。协同演化文献里「注释更新滞后于代码」的老问题在Agent身上不仅复现，还被放大——只不过Agent的「文档」更多是给自己（或下一个Agent实例）看的工作笔记。

6.5 反事实推理：如果仪器设计有缺陷，结论会怎样？

论文的两个抽取缺陷提供了天然的反事实：如果不解析shell内嵌路径，一个Agent族的文档事件为零——不是「少一些」，是结构性不可见；如果不支持非字符串工具输出，9个会话、4,358个事件会丢失。这反证了论文给数据集与工具构建者的警告：只按工具名做语料分析会系统性低估shell中心型Agent；没有agent_instruction/agent_working_note类别的分类器会把多数交互扔进残余桶。仪器的边界就是结论的边界。

七、必要知识反推

假设把一个毫无背景的人放到这项工作面前，他最少需要知道什么？

7.1 领域知识层

• 编码Agent的运作机制：Agent CLI如何工作（读仓库、调工具、开PR）、转录长什么样（用户消息/Agent消息/工具调用/工具返回/代码变更五要素）、指令文件（AGENTS.md/CLAUDE.md/SKILL.md、Cursor与Copilot规则文件）是什么。不懂这些，连「文档事件」的边都画不出来。
• 文档体裁谱系：README、ADR、API参考、故障排查、安装部署、变更日志……以及2024年后新涌现的agent-facing体裁。分类器的15+2个类别每一个都需要领域判断。
• 软件仓库结构常识：vendored路径、node_modules——决定哪些文件属于「仓库拥有的文档」。

7.2 方法论知识层

• 实证软件工程方法：软件仓库挖掘（co-change mining传统）、过程挖掘、IDE交互流序列挖掘——三者的结合给出了「事件流+文件级变更」的双单元设计。
• 统计推断：簇自助（为何嵌套数据不能假设独立——最大仓库贡献8,911个PR）、GEE（相关结构+协变量调整）、lift vs 条件概率的区别、Wilson区间的独立性假设与小样本行为。
• 测量理论：构念效度（路径识别会系统性漏掉docstring）、为何不编码意图（不可证伪）、信度框架（Cohen κ / Krippendorff α——知道自己缺什么并如实承认）。

7.3 工程知识层

• 异构JSON解析：四种转录格式各自的坑（行分隔、parts数组、payload事件、messages数组）、非字符串类型的工具输出。
• shell命令文本挖掘：从apply_patchhere-document里抽路径——不懂这个，shell中心的Agent族直接隐形。- LLM辅助分类的工程化：500个标注+27个关键词回退的fallback设计、覆盖率报告（98.4%）、对LLM标签「未做人工验证」的显式坦白。

7.4 知识融合的关键节点

• 节点一（抽象层）：把「Agent用文档吗」翻译成「事件流上的lift」——领域直觉×流行病学统计量的化学反应。
• 节点二（涌现层）：Tier 2分类发现agent_working_note——如果不既有分类学功底又对「奇怪路径」保持开放，25.1%的核心发现就会被埋在残余桶里。
• 节点三（工程-统计层）：簇自助+三权重+GEE三件套——抽样设计的自觉驱动了统计处理的复杂度，缺任何一件都会产生虚假的确信。
• 节点四（诚实处）：把「未解析」「不可结论」「未验证」写成正式结论的一部分。

八、论文中可以提取的通用性灵感

8.1 先测量新读者的行为，再为新读者设计

核心思想：当一类新消费者（Agent、机器、新用户群）进入一个为旧消费者设计的系统时，设计建议必须建立在对新消费者实际行为的观察上，而非对它「应该如何」的想象。

论文证据：agent-friendly documentation建议（清晰标题、可运行示例、llms.txt）建立于直觉；行为数据显示60.5%交互指向行业建议完全未覆盖的agent-facing工件、API参考仅1.3%、可操作性与可验证性两大假设无一致行为支撑。

推广场景：AI搜索时代的网页设计（先测量爬虫/Agent实际如何抓取）；自动驾驶时代道路标识设计；无障碍界面设计（先观察辅助技术实际读取什么）。

8.2 新读者会催生新文体——警惕分类学的时代盲区

核心思想：新受众的出现不只是「多了一类读者」，而是会创造出一类「因它而生」的新工件；旧分类学看不见它们，于是最重要的交互落入残余桶。

论文证据：Tier 1把54%文档事件放入残余类别；agent_working_note从残余中涌现并占25.1%；论文明确警告「2024年前构建的文件类型分类学看不见agent-facing文档」。

推广场景：日志分析中新型客户端产生的新日志格式；文献计量中新学术体裁（预印本、代码仓库）长期不在索引体系内；数据治理中「为机器生成的表」成为新的治理对象。

8.3 不解析载体内的信息，行为就是不可见的

核心思想：当一个行动者把操作路由到间接通道（shell命令内嵌路径），只看显式工具名的测量仪器会把它记为零——测量之前先问：仪器能看见我要测的东西吗？

论文证据：不解析apply_patch here-document里的路径，一个Agent族文档事件为零；跨Agent比较与抽取覆盖度混杂，论文拒绝把Agent间差异解读为行为差异。

推广场景：API审计中经网关转发的调用丢失来源；数据库慢查询日志看不见被ORM内嵌的SQL；安全分析看不见编码进base64的载荷。

8.4 区分「否定」「未解析」与「不可结论」——认识论诚实作为方法

核心思想：数据不支持一个假设时，要区分三种情况：有证据的否定（验证零事件）、调整前后矛盾（未解析）、样本太小（不可结论）——混为一谈就是把不确定性当结论贩卖。

论文证据：lift 1.05 vs OR 1.33被如实标为未解析；文档恢复解决率63.6%因n=11被拒绝排名；Validate零事件被限定为「定义模式的零，不证明任何形式的验证都不存在」。

推广场景：A/B测试中调整混杂前后符号翻转的指标；临床试验亚组分析的小样本「有效」；金融回测中参数敏感的策略收益。

8.5 有界记忆的行动者会把推理外化为工件

核心思想：上下文有限的智能系统会把中间推理写进持久化文件——文档从「参考」变成「工作记忆」，读写趋于对称。

论文证据：生产速率为咨询的0.87倍；58.2%有文档活动的会话既读又写；工作笔记咨询382次/产出367次几乎对半；plans与thoughts/目录的显著性。

推广场景：长程多Agent系统中的共享外部记忆设计；机器人任务的持久化任务状态文件；任何需要跨会话/跨实例延续状态的Agent架构。

8.6 可执行的契约优于需要被信任的散文

核心思想：想让验证行为可观测，就要提供能被直接执行核验的工件——依赖行动者自觉遵守的文字不会被系统性地使用。

论文证据：零验证事件；咨询与更少的测试/构建相关（lift 0.23/0.15）；论文据此提议doctest、schema契约、可运行示例作为干预假设。

推广场景：服务间契约测试（OpenAPI+契约测试而非文字API文档）；数据质量的可执行断言；Agent指令文件中的「硬约束」应尽量替换为CI强制检查。

8.7 警惕自指回路：行动者在改写塑造自己的规则

核心思想：当Agent修改AGENTS.md这类「自己的说明书」，系统出现了输出反写输入的回路——既有治理模型没有这一层。

论文证据：AGENTS.md（692个PR）、CLAUDE.md（362）、copilot-instructions.md（287）是被改最多的文档文件。

推广场景：推荐系统修改用户画像再喂回推荐；Agent修改自己的权限边界带来的安全问题；组织流程自动化中流程修改流程文档的风险。

附录：核心数字速查与局限

A.1 核心数字速查

A.2 论文自陈的主要局限

• Tier 2标签未经人工验证：占25.1%的工作笔记类别依赖LLM分类，精确份额是暂定的；「Agent自写工作文档构成大类别」这一质性发现比其精确量级更稳健。必要后续是对200-300事件子样本做双人编码并报告κ/α。
• 仪器边界：docstring、浏览器阅读的API网站、模型权重内知识不可见；指令文件计数只是暴露下界。
• 一阶转移：相邻转移的0.002不排除更长程或经推理中介的影响；触发回看窗口固定（四事件），窗口外动因可能被误记为「Agent自发」。
• 外部效度：SWE-chat是自愿遥测（87%单一Agent族）、AIDev是早期采纳者仓库；皆不一定推广到私有代码库；60.5%刻画的是快照而非稳定常数。
• 阶段启发式粘性：debugging份额被膨胀，阶段分布不应作精确分配解读。

A.3 一句话总结

这篇论文做的事情很朴素也很有力：在一个行业正凭直觉快速重塑「文档该为Agent怎么写」的时刻，它把557个真实会话和33,097个Agent PR放到桌面上说——**你们以为Agent在读的文档，Agent基本没在读；Agent真正在读写的文档，你们的分类学里还没有名字；你们许诺的两个品质，行为上还看不到。**对文档工程，它把资源优先级从API参考散文扳向指令文件与工作笔记；对实证方法，它示范了「未解析」也可以是结论；对更广的Agent系统设计，它留下了一个待检验的设计假设：验证不要靠散文，要靠可执行的东西。