Agent READMEs: An Empirical Study of Context Files for Agentic Coding
本研究通过分析2,303个代理上下文文件，揭示其结构、维护习惯及内容偏向，强调安全和性能指导不足。
核心发现
方法论
采用大规模数据采集，分析1,925个开源仓库中的代理上下文文件，结合内容分类、结构分析和自动化分类模型。具体包括：统计文件长度、可读性（Flesch评分）、Markdown标题层级，利用Lizard工具计算代码复杂度，并通过统计检验分析不同工具的差异。
关键结果
- 文件长度方面，Claude和Copilot的上下文文件显著长于Codex（中位数535与335字），且结构呈浅层层级，内容偏向功能性（如测试75.9%、实现70.8%），而非非功能性（安全14.8%、性能14.5%）偏少。内容分类模型在功能性主题（如架构、测试）上的F1-score达0.79，表现优异，但在抽象主题（维护）上效果较差。
- 文件维护表现为频繁小规模更新，非删除为主，表现出“活文档”特征。代码复杂度与内容长度相关，长文件对应更高复杂度，但不同工具间差异有限。
- 内容偏向功能性，安全和性能等非功能性要求缺失，反映出开发者对代理安全性和性能保障的关注不足，存在潜在风险。
- 自动分类模型在功能性主题识别中表现优异，未来可用于持续监控和优化代理配置策略。
研究意义
本研究揭示了代理上下文文件的实际结构和内容偏向，为理解自动化编码环境中的配置实践提供基础。强调了安全和性能指导的缺失，提示未来在工具设计中应强化非功能性需求的表达。对推动自动编程的安全性、可靠性和可维护性具有重要意义，有助于行业标准制定和工具优化。
技术贡献
首次系统性分析了多工具、多仓库中的代理上下文文件，结合内容分类、结构分析和自动化模型，提出了文件的复杂性、维护习惯及内容偏向的定量描述。引入基于Markdown的结构分析和FRE可读性评估，为配置文件的自动化监控提供技术基础。
新颖性
本研究首次大规模系统分析代理上下文文件，揭示其结构、内容偏向和维护习惯，填补了该领域缺乏实证数据的空白。提出基于内容分类的自动化识别模型，为未来智能监控和优化提供技术路径。
局限性
- 分析仅基于公开仓库，可能存在偏差，未覆盖企业内部或私有仓库的配置习惯。
- 内容分类模型在抽象主题（如维护）上的表现仍有限，未来需引入更复杂的语义理解机制。
- 研究未深入探讨上下文文件对代理性能的直接影响，未来应结合性能指标进行关联分析。
未来方向
未来将结合代码质量和性能指标，深入分析上下文文件对代理行为的影响，探索多模态内容融合，提升配置文件的自动生成和优化能力。同时，推动行业标准制定，强化非功能性需求的表达和验证。
AI 总览摘要
随着大规模语言模型（LLMs）在软件开发中的广泛应用，代理编码（Agentic Coding）成为推动自动化编程的重要方向。此技术依赖于代理上下文文件，作为项目的“长效记忆”，定义代理行为、架构规范及操作规则。本文通过分析1,925个开源仓库中的2,303个上下文文件，系统揭示了其结构特征、维护习惯和内容偏向。
研究发现，这些文件普遍较长，结构浅显，内容偏重功能性，如测试和实现细节，而非安全和性能等非功能性要求。内容分类模型在识别功能性主题方面表现优异（F1-score达0.79），但在抽象主题上仍有提升空间。维护方面，文件表现出频繁小规模更新的特征，体现出“活文档”的特性。文件的复杂度与长度相关，但不同工具间差异有限。
这些发现表明，当前开发者更关注代理的功能实现，而对安全和性能的重视不足，潜藏风险。自动化分类模型有望成为监控和优化配置的工具。未来，结合代码性能指标，深入研究上下文文件对代理行为的影响，将推动自动编程的安全性和可靠性提升。这项工作为自动化软件开发提供了宝贵的实证基础，指引未来工具和标准的设计方向。
深度分析
研究背景
近年来，大型语言模型（如GPT-3、Codex）推动自动化编程，代理编码（Agentic Coding）作为新兴技术，允许模型在自然语言指引下自主生成代码。已有研究关注模型能力、交互策略，但对实际应用中的配置文件缺乏系统分析。代理上下文文件（如AGENTS.md、CLAUDE.md）作为项目的“指令集”，定义代理行为和规范，扮演着关键角色。尽管如此，关于其结构、内容和维护习惯的实证研究尚缺乏，限制了对其优化的理解。
核心问题
代理上下文文件在实际项目中的作用日益重要，但缺乏系统性分析，导致开发者难以设计高效、安全的配置。现有文档多为高层指导，缺少标准化结构，内容偏重功能，忽视非功能性需求。文件维护频繁且多样，缺乏自动化监控手段，增加了配置误差和安全风险。解决这一问题，需深入理解这些文件的实际特征和内容偏向，为自动化配置提供数据支持。
核心创新
本研究首次大规模分析代理上下文文件，结合内容分类、结构分析和自动化模型，揭示其长度、可读性、内容偏向和维护习惯。引入基于Markdown的结构分析和FRE评分，量化文件复杂度和可读性。提出自动分类模型，识别功能性和非功能性内容，为未来配置监控提供技术基础。这些创新推动了自动化配置文件的理解和优化。
方法详解
- �� 数据采集：从AIDev数据集筛选出8,370个仓库，利用GitHub API检测特定文件名（如CLAUDE.md、AGENTS.md、copilot-instructions.md）共计采集2,303个文件。• 内容分析：统计文件长度（词数）、可读性（FRE评分）、Markdown标题层级。• 结构分析：提取标题层级，分析内容组织。• 复杂度评估：用Lizard计算代码复杂度和行数。• 内容分类：训练模型识别16个指令类别，评估F1-score。• 统计检验：采用Mann-Whitney U检验分析不同工具间差异，计算Cliff’s delta效果大小。
实验设计
实验基于真实仓库数据，比较不同工具（Claude、Codex、Copilot）上下文文件的长度、结构和内容偏向。采用FRE评分评估可读性，利用Lizard分析代码复杂度。内容分类模型（如BERT）训练识别指令类别，评估性能指标。通过统计检验验证差异显著性，确保结果的可靠性。还分析了文件维护频率和内容变化特征，验证其“活文档”特性。
结果分析
Claude和Copilot的上下文文件显著长于Codex（中位数535 vs. 335字），内容偏向功能性（如测试75.9%、实现70.8%），非功能性（安全14.8%、性能14.5%）偏少。内容分类模型在功能性主题识别中F1-score达0.79，表现优异。文件维护表现为频繁小规模更新，内容偏向功能，复杂度与长度正相关，但不同工具差异有限。安全和性能指导不足，存在潜在风险。模型可用于持续监控配置质量。
应用场景
该研究为自动化编码环境中的配置优化提供基础，帮助开发者设计更规范、易维护的上下文文件。自动分类模型可应用于持续监控和风险预警，提升软件安全性和性能保障。未来结合性能指标，可实现动态优化和自动修正，推动行业标准制定，增强自动编程的可靠性。
局限与展望
分析仅基于开源仓库，可能偏离企业实际实践。内容分类模型在抽象主题上的表现仍有限，需引入更深层语义理解。未直接关联上下文文件与代理性能，未来应结合性能指标进行关联分析。模型泛化能力待验证，需扩展多场景、多语言数据集。
通俗解读 非专业人士也能看懂
想象你在厨房做饭，菜单上写着各种菜肴的步骤。代理上下文文件就像厨房的食谱，告诉机器人（代理）如何做饭。不同的厨房（项目）有不同的食谱，有的只写简单的步骤，有的详细到每个调料的用量。开发者写这些“食谱”，让机器人知道怎么操作，但很多时候只写了基本的功能，比如“煮饭”、“炒菜”，很少提到安全（比如火候）或效率（节省时间）的问题。文件越长，内容越详细，但也越难理解。研究发现，这些“食谱”大多偏重功能，安全和性能方面的指导很少，就像厨房里没有明确标注“火太大会烧焦”。这让机器人虽然能做出菜，但可能会出错或不安全。自动识别这些食谱的内容，有助于未来改进厨房管理，让机器人做菜更安全、更快、更好。
简单解释 像给14岁少年讲一样
想象你在学校的科学实验室里，老师给你一份实验指南，让你知道怎么做实验。代理上下文文件就像这个指南，告诉电脑（代理）在写代码时要遵循的规则。不同的项目有不同的指南，有的只写了基本的步骤，比如“安装软件”、“运行测试”，而没有提到安全措施或性能优化。开发者就像写指南的老师，他们写这些文件，帮助电脑知道怎么工作，但很多时候只关注功能，不太考虑安全或速度。文件越长，内容越丰富，但也越难理解。研究发现，这些指南主要讲功能，安全和性能的内容很少，就像老师没有强调“实验要安全”或“节省时间”。这样，电脑虽然能完成任务，但可能会出错或不安全。自动分析这些指南，未来可以帮老师改进，让实验更安全、更快、更顺利。
原文摘要
Agentic coding tools receive goals written in natural language, break them down into specific tasks, and write or execute code with minimal human intervention. Central to this process are agent context files (e.g., AGENTS.md and CLAUDE.md) that provide persistent, project-level instructions. In this paper, we conduct the first large-scale empirical study of 2,303 agent context files from 1,925 repositories to characterize their structure, maintenance, and content. We find that these files are not static documentation but complex, difficultto-read artifacts that evolve like configuration code through frequent, small additions. Our content analysis of 16 instruction types shows that developers prioritize functional context, such as test procedures (75.9%), implementation details (70.8%), and architecture (68.1%). We also identify a significant gap: non-functional requirements such as security (14.8%) and performance (14.5%) are rarely specified. These findings indicate that while developers use context files to make agents functional, they provide few guardrails to ensure that agent-written code is secure or performant, highlighting the need for improved tools and practices.