DOI: https://doi.org/10.1145/3840295
تاريخ النشر: 2026-09-15
المؤلف: Worawalan Chatlatanagulchai وآخرون
الموضوع الرئيسي: أبحاث هندسة البرمجيات
نظرة عامة
تقدم هذه الدراسة أول تحليل تجريبي واسع النطاق لملفات سياق الوكلاء، مثل CLAUDE.md و AGENTS.md، والتي تعتبر ضرورية لتعريف سلوك الوكيل الذكي في الترميز الوكالي. من خلال تحليل 2,303 ملف سياق من 1,925 مستودع، تكشف الأبحاث أن هذه الملفات معقدة وطويلة وصعبة القراءة، وغالبًا ما تُصنف على أنها “صعبة” تشبه المواد على مستوى المدرسة الثانوية. عادةً ما تتميز بنية هذه الملفات بهيكل سطحي، مع عنوان H1 رئيسي وأقسام فرعية H2/H3، مما يسهل التنقل والصيانة. ومن الجدير بالذكر أن هذه الملفات ليست ثابتة؛ بل يتم صيانتها بنشاط حيث يتم تعديل 67.0% من ملفات كود كلود عبر عدة التزامات، وتتميز بتحديثات متكررة وتدريجية.
تسلط تحليل المحتوى الضوء على التركيز القوي على التعليمات الوظيفية، حيث يعطي المطورون الأولوية للإرشادات العملية حول الاختبار (75.9%)، تفاصيل التنفيذ (70.8%)، والهندسة المعمارية (68.1%). ومع ذلك، هناك فجوة كبيرة في معالجة المتطلبات غير الوظيفية (NFRs)، مثل الأمان (14.8%) والأداء (14.5%)، مما يشير إلى أنه بينما يقوم المطورون بتوجيه الوكلاء بفعالية حول الجوانب الوظيفية، فإنهم يقدمون إرشادات غير كافية حول سمات الجودة. وهذا يبرز الحاجة إلى تحسين الأدوات والممارسات لتعزيز الأمان والأداء للكود الذي يتم إنشاؤه بواسطة الوكلاء، حيث قد تؤدي ممارسات التوثيق الحالية إلى ثغرات وعدم كفاءة في الترميز الوكالي.
مقدمة
تناقش مقدمة ورقة البحث التأثير التحويلي لنماذج اللغة الكبيرة (LLMs) على تطوير البرمجيات، وخاصة من خلال نهج جديد يعرف بالترميز الوكالي. يسمح هذا الأسلوب لوكلاء الذكاء الاصطناعي بتفسير الأهداف باللغة الطبيعية، وتفكيكها إلى مهام فرعية، وتوليد الكود بشكل مستقل، مما يقلل بشكل كبير من الحاجة إلى تدخل البشر. ومع ذلك، فإن فعالية هؤلاء الوكلاء تعتمد بشكل كبير على السياق، الذي يتضمن ليس فقط الوصول إلى الكود المصدري ولكن أيضًا إرشادات واضحة بشأن هيكل المشروع والاتفاقيات. لتسهيل ذلك، ظهر نوع جديد من العناصر البرمجية، يسمى ملفات سياق الوكيل (مثل AGENTS.md). تعمل هذه الملفات كدليل شامل للوكلاء، حيث تفصل المعرفة الخاصة بالمشروع، ونظرات عامة معمارية، ومعايير الترميز، وقواعد التشغيل.
تسلط الورقة الضوء على فجوة في الأدبيات الحالية بشأن الدراسة التجريبية لملفات سياق الوكلاء، على الرغم من أن الأبحاث السابقة كانت تركز على قدرات LLM وأنماط التفاعل. بينما يعتمد المطورون حاليًا على التجربة والخطأ لإنشاء هذه الملفات، هناك نقص في الأدلة الملموسة حول هيكلها ومحتواها. لمعالجة ذلك، أجرى المؤلفون دراسة تجريبية واسعة النطاق تحلل 2,303 ملف سياق وكيل من 1,925 مستودع عبر ثلاثة أدوات ترميز: كود كلود، OpenAI Codex، وGitHub Copilot. تهدف الدراسة إلى كشف الخصائص، وعادات الصيانة، واستراتيجيات التعليم لهذه الملفات، مطروحةً أسئلة بحثية حول قابليتها للقراءة، وهيكلها، وتكرار التحديثات. تشير النتائج الأولية إلى أن ملفات سياق الوكلاء طويلة ومعقدة لكنها تحافظ على هيكل هرمي متسق، وأنها تُحدث بنشاط في فترات قصيرة، مما يشير إلى دورها كعناصر تكوين ديناميكية بدلاً من توثيق ثابت.
الطرق
في هذه الدراسة، يبني المؤلفون على أبحاثهم السابقة من خلال جمع وتحليل ملفات سياق الوكلاء (ACFs) من مستودعات مفتوحة المصدر التي تستخدم ثلاثة أدوات ترميز وكالية محددة: كود كلود، OpenAI Codex، وGitHub Copilot. تبدأ عملية جمع البيانات، كما هو موضح في الشكل 2، بتحديد المستودعات ذات الصلة من مجموعة بيانات AIDev، التي تسرد المستودعات التي تساهم فيها هذه الأدوات بنشاط في التطوير. تم اختيار ما مجموعه 8,370 مستودعًا بناءً على معيار وجود 5 نجوم على الأقل في GitHub، مما أدى إلى تصفية المشاريع الأقل أهمية.
استخدم المؤلفون واجهة برمجة تطبيقات GitHub لفحص الدلائل الجذرية لهذه المستودعات بحثًا عن ملفات تتوافق مع الاتفاقيات الرسمية للتسمية الموضحة في الوثائق لكل أداة ترميز. أسفر هذا البحث عن 922 ملفًا لكود كلود، و694 لـ OpenAI Codex، و687 لـ GitHub Copilot، عبر 1,925 مستودع. تقدم الجدول 1 ملخصًا لإحصائيات المستودعات المستضيفة، بما في ذلك النجوم المتوسطة، والفوركات المتوسطة، ومتوسط المدة من إنشاء المستودع إلى الاعتماد الأول على ACFs. تشكل مجموعة البيانات التي تم تشكيلها من خلال هذه المنهجية أساسًا لمعالجة أربعة أسئلة بحثية محددة تتعلق باستخدام وتأثير أدوات الترميز الوكالية.
النتائج
في قسم النتائج، تحقق الدراسة في صيانة وتصنيف ملفات سياق الوكلاء عبر مساعدي الترميز الذكي المختلفين. تكشف التحليلات أن ملفات سياق الوكلاء تُحدث بشكل متكرر، حيث تم تعديل 67.0% من ملفات كود كلود في عدة التزامات، مقارنةً بـ 59.8% لـ GitHub Copilot و59.4% لـ OpenAI Codex. تشير التحليلات الإحصائية باستخدام اختبار مان-ويتني U إلى أن ملفات سياق كود كلود تتلقى عددًا أكبر بكثير من الالتزامات مقارنةً بالآخرين، مما يشير إلى نهج أكثر ديناميكية في التوثيق.
حدد التصنيف اليدوي 16 فئة متميزة من ملفات سياق الوكلاء، بما في ذلك فئتين جديدتين: الصيانة وتصحيح الأخطاء. كانت الفئة الأكثر شيوعًا هي الاختبار (75.9%)، تليها تفاصيل التنفيذ (70.8%) والهندسة المعمارية (68.1%). بالمقابل، كانت الفئات غير الوظيفية مثل الأداء (14.5%) والأمان (14.8%) أقل شيوعًا، مما يشير إلى التركيز على الجوانب الوظيفية لتنفيذ الكود. ومن الجدير بالذكر أن 24.1% من الملفات تضمنت تعريفات واضحة لدور الوكيل الذكي، مما يبرز الغرض المزدوج لهذه الملفات كأدلة تقنية وأطر للتوافق التعاوني. علاوة على ذلك، حقق التصنيف التلقائي لهذه الملفات درجة F1 متوسطة قدرها 0.79، مما يدل على فعالية في التعرف على التعليمات الملموسة، بينما واجه صعوبة مع الفئات الأكثر تجريدًا المتعلقة بإدارة المشاريع وقابلية الصيانة.
المناقشة
في قسم المناقشة من ورقة البحث، يتناول المؤلفون عدة أسئلة بحثية (RQs) تتعلق بملفات سياق الوكلاء، والتي تعتبر حاسمة لتكوين مساعدي الترميز الذكي في تطوير البرمجيات. تشير النتائج إلى انحراف كبير في أنواع التعليمات المدرجة في هذه الملفات، مع تركيز كبير على العمليات الوظيفية (مثل البناء والتشغيل) بينما يتم تمثيل المتطلبات غير الوظيفية الحرجة، مثل الأمان والأداء، بشكل ملحوظ. يبرز هذا الخلل النقاط العمياء الحالية في ممارسات الترميز الوكالي. علاوة على ذلك، يظهر المؤلفون أنه بينما يكون التصنيف التلقائي للتعليمات فعالًا لمواضيع وظيفية ملموسة (محقيقًا درجة F1 قدرها 0.79)، فإنه يواجه صعوبة مع المواضيع الأكثر تجريدًا مثل الصيانة، مما يشير إلى الحاجة إلى تحسين المنهجيات في هذا المجال.
تؤكد الورقة أيضًا على أهمية ملفات سياق الوكلاء كعناصر تكوين متطورة بدلاً من توثيق ثابت. تكشف تحليل تواريخ الالتزام أن هذه الملفات تُصان بنشاط، حيث يخضع الغالبية لعدة تعديلات بمرور الوقت. تشير أنماط الصيانة إلى أن المطورين يقومون بتحديث هذه الملفات استجابةً لمتطلبات المشروع الجديدة بدلاً من خلال تصحيح الأخطاء التكرارية، كما يتضح من الفترات المتوسطة بين الالتزامات. يستنتج المؤلفون أن خصائص ملفات سياق الوكلاء – مثل طولها، وقابليتها للقراءة، وتنظيمها الهيكلي – تتأثر باتفاقيات التوثيق الخاصة بالمنصة، مما يؤثر في النهاية على قابلية الاستخدام وفعالية مساعدي الترميز الذكي في المشاريع الواقعية.
DOI: https://doi.org/10.1145/3840295
Publication Date: 2026-09-15
Author(s): Worawalan Chatlatanagulchai et al.
Primary Topic: Software Engineering Research
Overview
This study presents the first large-scale empirical analysis of agent context files, such as CLAUDE.md and AGENTS.md, which are essential for defining AI agent behavior in agentic coding. Analyzing 2,303 context files from 1,925 repositories, the research reveals that these files are complex, lengthy, and challenging to read, often categorized as “difficult” akin to high school-level material. The structure of these files typically features a shallow hierarchy, with a primary H1 heading and H2/H3 subsections, facilitating easier navigation and maintenance. Notably, the files are not static; they are actively maintained with 67.0% of Claude Code files undergoing revisions across multiple commits, characterized by frequent, incremental updates.
The content analysis highlights a strong emphasis on functional instructions, with developers prioritizing practical guidance on Testing (75.9%), Implementation Details (70.8%), and Architecture (68.1%). However, there is a significant gap in addressing non-functional requirements (NFRs), such as Security (14.8%) and Performance (14.5%), indicating that while developers effectively instruct agents on functional aspects, they provide insufficient guidance on quality attributes. This underscores the need for improved tools and practices to enhance the security and performance of agent-generated code, as the current documentation practices may lead to vulnerabilities and inefficiencies in agentic coding.
Introduction
The introduction of the research paper discusses the transformative impact of Large Language Models (LLMs) on software development, particularly through a novel approach known as Agentic Coding. This method allows AI agents to interpret natural language goals, decompose them into subtasks, and autonomously generate code, significantly reducing the need for human intervention. However, the effectiveness of these agents is heavily dependent on context, which includes not only access to source code but also explicit guidance regarding project architecture and conventions. To facilitate this, a new type of software artifact, termed agent context files (e.g., AGENTS.md), has emerged. These files serve as a comprehensive guide for agents, detailing project-specific knowledge, architectural overviews, coding standards, and operational rules.
The paper highlights a gap in the existing literature regarding the empirical study of agent context files, despite prior research focusing on LLM capabilities and interaction patterns. While developers currently rely on trial and error to create these files, there is a lack of concrete evidence about their structure and content. To address this, the authors conducted a large-scale empirical study analyzing 2,303 agent context files from 1,925 repositories across three coding tools: Claude Code, OpenAI Codex, and GitHub Copilot. The study aims to uncover the characteristics, maintenance habits, and instructional strategies of these files, posing research questions about their readability, structure, and the frequency of updates. Preliminary findings suggest that agent context files are lengthy and complex yet maintain a consistent hierarchical structure, and they are actively updated in short bursts, indicating their role as dynamic configuration artifacts rather than static documentation.
Methods
In this study, the authors build upon their previous research by systematically collecting and analyzing agent context files (ACFs) from open-source repositories that utilize three specific agentic coding tools: Claude Code, OpenAI Codex, and GitHub Copilot. The data collection pipeline, as illustrated in Figure 2, begins with the identification of relevant repositories from the AIDev dataset, which lists repositories where these tools are actively contributing to development. A total of 8,370 repositories were selected based on the criterion of having at least 5 GitHub stars, thereby filtering out less significant projects.
The authors employed the GitHub API to scan the root directories of these repositories for files that adhere to the official naming conventions outlined in the documentation for each coding tool. This search yielded 922 files for Claude Code, 694 for OpenAI Codex, and 687 for GitHub Copilot, across 1,925 repositories. Table 1 provides a summary of the hosting repositories’ statistics, including median stars, median forks, and the average duration from repository creation to the initial adoption of ACFs. The dataset formed through this methodology serves as the foundation for addressing four specific research questions related to the use and impact of agentic coding tools.
Results
In the Results section, the study investigates the maintenance and classification of agent context files across different AI coding assistants. The analysis reveals that agent context files are frequently updated, with 67.0% of Claude Code files modified in multiple commits, compared to 59.8% for GitHub Copilot and 59.4% for OpenAI Codex. Statistical analysis using the Mann-Whitney U test indicates that Claude Code context files receive significantly more commits than the other two, suggesting a more dynamic approach to documentation.
The manual classification identified 16 distinct categories of agent context files, including two new categories: Maintenance and Debugging. The most common category was Testing (75.9%), followed by Implementation Details (70.8%) and Architecture (68.1%). In contrast, non-functional categories such as Performance (14.5%) and Security (14.8%) were less prevalent, indicating a focus on functional aspects of code execution. Notably, 24.1% of files included explicit definitions of the AI agent’s role, highlighting the dual purpose of these files as both technical guides and frameworks for collaborative alignment. Furthermore, the automatic classification of these files achieved a micro-average F1-score of 0.79, demonstrating effectiveness in recognizing concrete instructions, while struggling with more abstract categories related to project management and maintainability.
Discussion
In the discussion section of the research paper, the authors address several research questions (RQs) related to agent context files, which are crucial for configuring AI coding assistants in software development. The findings indicate a significant skew in the types of instructions included in these files, with a predominant focus on functional operations (e.g., Build and Run) while critical non-functional requirements, such as Security and Performance, are notably underrepresented. This imbalance highlights current blind spots in agentic coding practices. Furthermore, the authors demonstrate that while automatic classification of instructions is effective for concrete functional topics (achieving an F1-score of 0.79), it struggles with more abstract topics like Maintenance, suggesting a need for improved methodologies in this area.
The paper also emphasizes the importance of agent context files as evolving configuration artifacts rather than static documentation. Analysis of commit histories reveals that these files are actively maintained, with a majority undergoing multiple modifications over time. The maintenance patterns suggest that developers update these files in response to new project requirements rather than through iterative debugging, as evidenced by the median intervals between commits. The authors conclude that the characteristics of agent context files—such as their length, readability, and structural organization—are influenced by platform-specific documentation conventions, which ultimately affect the usability and effectiveness of AI coding assistants in real-world projects.