Agent READMEs: An Empirical Study of Context Files for Agentic Coding

研究概述

首个大规模实证研究：分析来自1,925个仓库的2,303个agent上下文文件（如AGENTS.md、CLAUDE.md），揭示开发者如何配置AI编码agent。

关键发现

1. 文件特征 (RQ1)

• Agent上下文文件长且难读
• 遵循浅层层级结构：单个一级标题，内容组织在H2和H3下
• 不是静态文档，而是像配置代码一样演化

2. 维护模式 (RQ2)

• 通过频繁的小增量更新维护
• 主要是增加而非删除
• 作为"活配置"而非静态文档

3. 内容分布 (RQ3)

• 功能优先:
  • 构建/运行命令: 62.3%
  • 实现细节: 69.9%
  • 架构: 67.7%
• 非功能需求罕见:
  • 安全: 14.5%
  • 性能: 14.5%

4. 自动分类 (RQ4)

• 自动化分类高效: 0.79 F1-score
• 具体功能主题（测试、架构）效果好
• 抽象主题（维护）分类困难

研究意义

• 揭示当前agentic coding的真实状态：功能优先，安全/性能被忽视
• 开发者使用上下文文件让agent"能用"，但很少提供guardrails确保代码安全或高性能
• 呼吁改进工具和实践来强化安全/性能指导

链接

• 论文: arxiv.org/abs/2511.12884