Quartz 4

Agent READMEs — 代理程式自述文件研究

8 min read

Abstract

本研究是首篇大規模實證研究 Agent Context Files（又稱 Agent Manifests）的學術論文，收集分析了 1,925 個開源軟體 repositories 的 2,303 份 Agent Context Files，發現這些檔案並非靜態文件而是持續維護的動態設定製品，59%–67% 經歷多次提交維護，且呈現「語境債務」（Context Debt）——當 Agent Context Files 累積大量難以維護的指令時，對人類開發者造成認知負擔。

Agent READMEs

Overview

Agent READMEs: An Empirical Study of Context Files for Agentic Coding 是首篇大規模實證研究 Agent Context Files（又稱 Agent Manifests） 的學術論文，發表於 2025 年 11 月，由來自泰國 Kasetsart 大學、加拿大 Queen’s University、日本奈良先端科學技術大學院大學的研究團隊完成。

研究收集並分析了來自 1,925 個開源軟體 repositories 的 2,303 份 Agent Context Files，涵蓋三種主流 Agentic Coding 工具：Claude Code（922 份）、OpenAI Codex（694 份）與 GitHub Copilot（687 份）。研究發現，這些所謂的「Agent README」並非靜態文件，而是持續維護的動態設定製品，透過頻繁的小幅度增量更新來演化，其行為更接近設定代碼而非傳統技術文檔^[raw/papers/agent-readmes.md]。

Core Contributions

研究團隊提出四個核心研究問題（Research Questions），並據此作出以下主要貢獻：

研究問題核心發現
RQ1: Agent Context Files 的特徵為何？這些檔案普遍冗長且難以閱讀，遵循一致的淺層結構（單一 H1 標題，搭配 H2、H3 子標題）
RQ2: 開發者多久維護一次這些檔案？59%–67% 的檔案經歷多次提交維護，維護模式以短暫突發和增量新增為主，刪除量極少
RQ3: 這些檔案包含哪些指令？功能導向指令（建置執行、實作細節、架構、測試）高度普遍；安全、效能等非功能性需求則極少見
RQ4: 這些指令能否自動分類？GPT-5 可達到 0.79 的 micro-average F1 分數，對具體功能類別效果佳，但對抽象或稀疏類別效果較弱

論文還引入了 「Context Debt」（語境債務） 概念——當 Agent Context Files 累積大量難以維護的指令時，對人類開發者造成認知負擔，形成一種新型技術債務^[raw/papers/agent-readmes.md]。

Architecture / Approach

研究資料收集

研究團隊基於 AIDev 數據集，篩選擁有至少 5 顆 GitHub stars 的 repositories，並使用 GitHub API 掃描根目錄中符合各工具官方命名規範的檔案：

工具檔案名稱收集數量
Claude CodeCLAUDE.md922
OpenAI CodexAGENTS.md694
GitHub Copilotcopilot-instructions.md687

平均而言，開發者在 repository 建立後約 994–1,567 天才首次採用 Agent Context Files^[raw/papers/agent-readmes.md]。

分析維度

研究採用三種分析維度：

  1. 可讀性分析：使用 Flesch Reading Ease（FRE）指標量化文本難度
  2. 維護行為分析：透過 Git 提交歷史追蹤檔案演化模式（提交頻率、提交間隔、增刪行數）
  3. 內容分類分析：兩階段人工標註流程（80 個初始標籤 → 合併為 16 個核心類別），爾後以 GPT-5 進行自動分類準確性評估

16 種指令類別

研究識別出 16 種指令類別，其中功能導向類別佔主導地位：

類別涵蓋率
Testing75.0%
Implementation Details69.9%
Architecture67.7%
Development Process63.3%
Build and Run62.3%
System Overview59.0%
Configuration & Environment38.0%
Maintenance43.7%
Documentation26.8%
AI Integration24.4%
Debugging24.4%
DevOps18.1%
Performance14.5%
Security14.5%
UI/UX8.7%
Project Management5.4%

非功能性需求（Security、Performance、UI/UX）顯著低於功能性類別，揭示 Agent 配置中對安全性與效能的集體性盲點^[raw/papers/agent-readmes.md]。

Key Results

檔案特徵（RQ1）

  • 長度：Claude Code（中位數 485 words）與 GitHub Copilot（中位數 535 words）顯著長於 OpenAI Codex（中位數 335.5 words）
  • 可讀性：Claude Code 最難閱讀（FRE 中位數 16.6，「非常困難」），Codex 最易讀（FRE 39.6，「困難」）
  • 結構：幾乎全部為單一 H1 標題，中位數 6–7 個 H2 節，H4 以上極少，整體呈淺層一致結構

維護模式（RQ2）

  • 67.4% 的 Claude Code 檔案經歷多次提交修改（對比靜態文件假設）
  • 維護間隔短暫：Claude Code 約 22–24 小時，GitHub Copilot 約 70.7 小時
  • 演化幾乎完全由增量新增驅動（中位數每次提交新增 57 words），刪除量極低

內容優先順序（RQ3）

  • 開發者高度關注功能運作（Build & Run 62.3%、Implementation Details 69.9%、Architecture 67.7%）
  • Security 僅 14.5%、Performance 僅 14.5%，顯示 Agent 被訓練優先執行而非優先安全或高效執行
  • 24.4% 的檔案明確定義 Agent 角色與責任（如「你是一個 React 專家」），反映 Agent 身份配置已成為常見實踐

自動分類（RQ4）

GPT-5 自動分類 micro-average F1 達 0.79，具體類別表現優異（Testing 0.94、Architecture 0.93），抽象類別掙扎（Project Management 0.42、Maintenance 0.56）^[raw/papers/agent-readmes.md]。

Limitations

研究本身識別出以下主要限制：

  1. 外部效度受限：資料集僅涵蓋 2,303 份來自 1,925 個 repositories 的檔案，雖然已較先前研究（253 份）大幅擴展，仍可能無法完全推論至所有 Agent Context Files 生態
  2. 建構效度：內容分類為二元判斷（有/無該類別），未能反映該類別在檔案中的深度或豐富程度
  3. 內部效度：人工標註存在主觀偏差，經獨立標註後達成 80.3% 一致率，再由第三方調解爭議
  4. 工具覆蓋性：研究僅纳入三種主流工具，隨著 Agentic Coding 生態快速演化，新工具和新檔案格式可能未被涵蓋
  • openhands — 通用 AI Agent 平台，專注軟體開發任務，支援多種工具整合
  • claude-code-analysis — Claude Code 的實證研究（為本論文的先驅工作，研究 253 份 Claude Code 檔案）
  • memos — 另一與 Agent 記憶和上下文管理相關的研究
  • tool-attention-mcp-tax — MCP（Model Context Protocol）安全性研究，與 Agent 工具使用上下文相關
  • agent-memory — Agent 記憶機制概念頁，與 Agent Context Files 作為持久化上下文的概念相關聯

References

  • 原始論文：arXiv:2511.12884v1 [cs.SE]，2025 年 11 月
  • 作者：Worawalan Chatlatanagulchai, Hao Li, Yutaro Kashiwa, Brittany Reid, Kundjanasith Thonglek, Pattara Leelaprute, Arnon Rungsawang, Bundit Manaskasemsak, Bram Adams, Ahmed E. Hassan, Hajimu Iida
  • 先前研究：同一團隊之 On the Use of Agentic Coding Manifests (PROFES’25)，研究 253 份 Claude Code 檔案
  • Replication Package：https://github.com/woraamy/Agent-Context-File-Analysis

Graph View

Backlinks