代理程式文件行為

資料來源#

• From Agent Behaviour to Agent-Friendly Documentation

摘要#

資料庫中每一條關於如何撰寫代理程式會使用的文件的建議——脈絡檔案、SKILL.md 漸進式揭露、以 AGENTS.md 作為目錄、「讓內容可採取行動」、「讓內容可驗證」——都建立在一套尚無人測量過的代理程式如何處理文字的模型之上。Gao & Chen（Peking University，arXiv 2608.20195，2026-08-20，empirical）從追蹤紀錄測量，而非提出假說；研究領域的四項工作假設都未能成立。

研究設計採用兩個單位互補、彼此不合併的公開資料集。SWE-chat：557 個真實的代理程式編碼工作階段（從 5,850 份公開逐字稿中抽樣，按代理程式與工作階段長度分成四個層級進行分層抽樣，對少數代理程式過度抽樣，排除大於 25 MB 的逐字稿），共得到 94,813 個開發事件，其中 3,033 個（3.2%）是文件互動。AIDev：從 2,807 個星數超過 100 的儲存庫中挑選 33,596 個代理程式 PR，再篩選為 33,097 個 PR 與 690,260 筆檔案×提交列，涵蓋 278,192 個不重複路徑，其中 29,597 個是文件路徑。不確定性以叢集自助法估計（2,000 次重抽樣；SWE-chat 以工作階段為叢集，AIDev 以儲存庫為叢集），這是正確且影響重大的選擇：AIDev 最大的單一儲存庫就貢獻 8,911 個 PR，前十大儲存庫占 44.7%，因此與 Wilson 等價區間相比，叢集法會使區間最多擴大 14.4 倍。

文件互動很常見，但並非普遍存在：**557 個工作階段中有 316 個（56.7%，叢集 CI 52.6–60.5%）**至少包含一次。

研究領域忽視的文件類型，正是代理程式會使用的類型#

核心結果是文件類型分布，它顛覆了所有前 LLM 時代的文件分類法所強調的重點：

文件類型	事件數	占比
代理程式指示（AGENTS.md、CLAUDE.md、SKILL.md、Cursor/Copilot 規則檔）	1,074	35.4%
代理程式工作筆記（計畫、thoughts/、腦力激盪、驗證紀錄）	760	25.1%
任務／需求	301	9.9%
組態	205	6.8%
README	197	6.5%
架構／ADR	120	4.0%
API 參考	40	1.3%
疑難排解	11	0.4%

面向代理程式的文件合計：3,033 個事件中的 1,834 個，占 60.5%（叢集 CI 53.9–66.5%）。文件研究傳統核心中的九種類型——API 參考、疑難排解、架構、綱要、安裝、範例、測試、貢獻指南、變更記錄——合計只有 323 個事件，占 10.6%。指示檔的互動次數約為 API 參考的 27 倍。

作者自己提出三項限定，本頁也完整保留：

• **分類界線可以爭議，作者也明言如此。**若把 README、組態與需求加入「傳統」文件，10.6% 會升至 33.8%；作者所捍衛的主張僅是兩端極端值的對比：1.3% 對 35.4%。若完全排除工作筆記，單是指示檔就占 2,273 個事件中的 1,074 個，達 47.2%。
• **多數比例取決於查閱端的加權方式。**以工作階段等權或依代理程式重新加權估計，面向代理程式的內容占所有互動比例會從 60.5% 降至 54.7%／55.1%；占查閱活動本身的比例則從 57.4% 降至 50.5%／50.1%，剛好落在 50% 線上。產出活動的比例則反向變動（63.7% → 67.1%／66.3%）。這個類別確實存在且相當醒目，但「代理程式讀取內容中明顯過半」並不穩定。
• **agent_working_note 是論文中驗證最不足的核心結果。**它不在初始編碼架構中，而是從第二層語言模型對 527 個模糊路徑的分類中產生（500 個經標註，占模糊事件的 98.4%；另 27 個使用關鍵字回退），沒有人工驗證，也未報告評分者間統計量。作者指出，下一步必須對 200–300 個事件的子樣本進行雙人編碼，並表示確切占比應視為暫定值。

文件幾乎同樣常是產出，也是輸入#

互動類型：讀取 1,328 次、編輯 1,007 次、建立 394 次、搜尋 282 次、發現 5 次。**產出（編輯＋建立＝1,401 次）是查閱（讀取＋搜尋＋發現＝1,615 次）的 0.87 倍。**在 316 個有文件活動的工作階段中，184 個（58.2%）同時讀取與撰寫，102 個（32.3%）只讀取，28 個（8.9%）只撰寫。

在產物層級也呈現相同形態：33,097 個代理程式 PR 中，有 13,750 個（41.5%，儲存庫叢集 CI 35.8–45.4%）變更文件——相較於共同變更研究中的人類註解維護率，比例偏高。程式碼與文件共同變更的比例為 32.0%（在 28,574 個觸及程式碼的 PR 中占 37.0%），而僅變更文件的比例為 9.6%。

循環也回到了代理程式自身的輸入。在 AIDev 中變更最多的個別文件裡，有 AGENTS.md（692 個 PR）、CLAUDE.md（362 個）、copilot-instructions.md（287 個）。代理程式會修改設定代理程式的檔案——這是一條現有文件模型中沒有的產出→輸入邊，也是 Agent Context Files 中可自行修改脈絡檔案安全攻擊面的實證對應。

順序：文件晚於程式碼#

在 4,386 個可觀察先後順序的多提交 PR中，47.3% 先觸及程式碼，42.6% 在同一次提交中同時變更，10.0% 先變更文件——因此有 4.7 倍這個核心數字。若限縮至程式碼與文件分別提交的 2,516 個案例，82.5%（2,076/2,516，儲存庫叢集 CI 78.7–86.0%）是程式碼先提交。

合併率沒有明顯差異：變更文件的 PR 為 81.1%，只變更程式碼的 PR 為 75.0%；但採用儲存庫叢集後，區間分別為 71.3–85.6% 與 64.9–81.1%，且大幅重疊。作者不下結論，並指出若假設樣本彼此獨立，差異看起來會很明確。這份克制與研究發現本身一樣，是論文的方法論教訓。

研究領域假設的讀取→行動連結並不存在#

這是對資料庫後續影響最大的部分；結果確實尚未有定論，並非負面結論。

• 相鄰轉移：P(edit code | read doc) = 0.002 [0.000, 0.005]——1,328 次文件讀取中只有三次出現。
• **讀取後實際發生的事：**再次讀取文件（0.270 [0.232, 0.307]）或進行推理（0.245 [0.205, 0.295]）。文件讀取會連續成串出現，而非孤立發生。P(edit doc | edit doc) = 0.350。
• 在三個事件的範圍內，未調整的程式碼編輯 lift 為 1.05 [0.86, 1.27]——與工作階段基準率無法區分；但經階段調整的邏輯 GEE 得出高於 1 的 OR 1.33 [1.09, 1.62]。兩種撰寫結果的方向則相反：未調整時，文件建立比例較高（lift 1.67 [1.14, 2.31]），調整後的區間則包含 1（OR 1.41 [0.98, 2.02]）。

應採納作者自己的判斷：這些資料無法判定查閱→程式碼與查閱→撰寫的關聯，唯一穩健的結果是下方的負面結果。這裡並沒有說文件不會影響程式碼；一階轉移無法看見透過工具未觀察到的推理過程所中介的影響，作者也明確指出這點。

查閱後驗證減少，而且未觀察到任何驗證事件#

查閱後三個事件的範圍內，有兩種行為出現頻率較低，且在調整後仍然如此：執行測試（lift 0.23，叢集 CI 0.08–0.45；調整後 OR 0.39 [0.25, 0.60]）與建置（lift 0.15，CI 0.02–0.33；OR 0.25 [0.14, 0.44]）。此外，研究未觀察到任何明確以文件作為基準來檢查程式碼的案例——Validate 階段與 Escalate 都是零事件；Verify 互動類型（依文件檢查程式碼）也未曾出現，Compare 與 Follow-reference 同樣如此。

這是對 Layered Supervision 定義特性的行為測量：預防性護欄是一種沒有任何東西會自動檢查的產物。在這裡，代理程式也不會依據它檢查。作者提出兩種可能機制，但不選擇其一：由於脈絡視窗有限，代理程式可能把推理外化至檔案，讓文件成為工作記憶而非參考資料（與計畫和 thoughts/ 的顯著占比相符）；或者代理程式可能略過文字驗證，直接呼叫更便宜的預言機——測試套件。無論是哪種情況，「我們沒有觀察到文字作為規格發揮作用」，這與資料庫從另一個完全不同的語料得出的權威性結論一致。

查閱是日常流程，不是困境訊號#

3,033 次互動中的觸發原因分布：代理程式主動發起 1,236 次（40.8%）、實作需求 893 次（29.4%）、使用者指示 618 次（20.4%）、工具失敗 217 次（7.2%）、規劃 58 次（1.9%）、測試失敗 7 次、建置錯誤 4 次。自行發起有 2,129 次（70.2%，CI 66.7–73.3%），失敗觸發有 228 次（7.5%，CI 6.0–9.3%），比率為 9.3 倍（若只看查閱活動，比例為 6.5 倍，兩者占 62.5% 與 9.7%）。

復原分析得出相同結果。在 2,034 起失敗事件中，之後的第一個行動是讀取程式碼 631 次（31.0%）、直接重試 404 次（19.9%）、在觀察範圍內沒有行動 318 次（15.6%）、直接編輯 312 次（15.3%）、搜尋程式碼 251 次（12.3%）、讀取文件 109 次（5.4%）、詢問使用者 9 次（0.4%）。P(read doc | tool error) = 0.020。以文件為基礎的復原，其點估計解決率最高（7/11＝63.6%），但作者明確拒絕將此視為研究發現：區間為 35.4–84.8%，與所有其他選項重疊。

論文有報告階段分布，但刻意不加以解讀：除錯 54.4%、實作 27.2%、熟悉環境 15.2%、驗證 3.0%、交付 0.1%；採用的階段判定規則具有黏性，會讓工作階段一直停留在「除錯」，直到測試或建置成功。作者提出的唯一主張是負面結論——文件查閱不只出現在熟悉環境階段，因此任何把文件視為任務起始活動的模型都與追蹤資料不符。

雙葉循環#

論文第 5 節的模型是綜合結論，從轉移結構推導而來，而非預先假定。各候選階段的證據如下（表 10；階段可以重疊，因此加總不等於 3,033）：

階段	事件數	狀態
貢獻／更新	1,401	有強力證據支持
擷取	1,344	有強力證據支持
導覽	462	有證據支持
詮釋	413	有證據支持
重訪	360	有證據支持
發現	287	有證據支持
復原	109	有證據支持，但較弱
套用	75	證據較弱
驗證	0	沒有證據支持
升級處理	0	沒有證據支持

假設的線性流程（發現 → 擷取 → 詮釋 → 套用 → 驗證 → 更新）在三方面失效：兩個階段沒有證據支持；線性模型視為核心步驟的 Apply 是證據最弱的階段，只有 75 個事件；而末端階段反而最大，貢獻／更新（1,401）多於擷取（1,344）。

取而代之的是兩個鬆散耦合的葉瓣。一個查閱葉瓣（導覽 → 發現 → 擷取 → 詮釋）會在內部反覆循環——最強的轉移是從擷取回到擷取本身，機率為 0.270；最強的外向轉移是進入推理，機率為 0.245。另一個是產出葉瓣（貢獻／更新），也是單一最大的類別。失敗很少會流入查閱葉瓣（占 5.4% 的事件），而且沒有觀察到任何一個葉瓣連到驗證的邊。修訂後的描述不再是從資訊需求走向經驗證實作的管線，而是反覆進行的查閱流程，產生推理與更多文件，並與大致獨立的程式碼修改流程鬆散耦合。

論文指出資料不支持的主張#

第 6.2 節列出少見的明確否定清單。本頁之所以記錄這一節，是因為其中四項裡有三項是資料庫自身語料不斷重複的建議：

• 可操作性（「撰寫成代理程式能直接依此行動的內容」）預設讀取→行動之間有關聯。相鄰機率為 0.002，未調整 lift 為 1.05，調整後 OR 為 1.33——沒有一致的行為證據支持這種關聯；而且觀察性研究設計無法證明提升可操作性會改變行為。
• 可驗證性（「撰寫成代理程式能據此檢查工作成果的內容」）描述的行為從未觀察到：驗證事件為零。設計時仍可考慮這項特性，但不能以觀察到的代理程式行為作為依據。
• 將文件作為失敗復原工具，既沒有觸發原因分布（7.5% 由失敗觸發）支持，也沒有復原分析（占 5.4% 的事件）支持。
• 為復原策略排序——作者直接拒絕，因為可觀察結果僅有 n=11。

有證據支持的含意相對有限：優先確保指示檔正確（27 倍曝光量的論據）；偏好自成一體、可在本地擷取的文件，而非大量交互連結的文件，因為讀取後常接著讀取（0.270），且 Follow-reference 完全沒有出現；把代理程式撰寫的工作筆記視為一種新的維護面向，目前的儲存庫整潔工具、審查清單與文件品質指標都沒有對應類別；並把可執行產物（可執行範例、doctests、綱要契約）視為讓驗證變得可觀察的假說——這是介入研究的假說，而非研究發現。

這套測量工具看不見的事#

研究範圍限制會左右結論，作者對此的說明也格外明確。

• 文件依檔案路徑識別。文件字串、行內註解與原始碼檔案中的文字都無法看到；絕對比率都是下限，且不同語言和專案的漏計程度並不一致。
• 執行階段注入的脈絡檔案，在重新讀取前都不可見。「執行階段在工作階段開始時載入的脈絡檔案，只有當代理程式之後明確讀取或編輯時才會被觀察到，因此指示檔數量是曝光量的下限。」35.4% 是代理程式注意力有多少放在 CLAUDE.md／AGENTS.md 上的下限，而不是上限——這與前述加權限制的方向相反。
• 研究刻意不編碼目的——工具呼叫紀錄無法還原目的，若自行推斷則無法證偽。因此研究改為報告觸發原因、互動類型與結果。
• 代理程式間的比率受到擷取涵蓋率混淆，不能反映行為。工作階段層級的文件比例從 62.6%（Claude Code，238/380）到 37.2%（Codex，16/43），另有一個代理程式為 0/11（Cursor）；有一個代理程式家族的擷取器學會從 apply_patch heredoc 命令字串中解析路徑前，文件事件數一直是零。這個問題不只限於本研究：任何以工具名稱為索引的語料分析，都會系統性低估以 shell 為主的代理程式；跨廠商比較測到的將是擷取器。資料庫中的跨廠商頁面應將代理程式欄視為無法解讀。
• 解決率只涵蓋 2,034 起事件中的 662 起（有可由 regex 偵測之結果的事件），其選擇效應無法量化。
• 外部效度：SWE-chat 是自願加入的遙測資料，87% 語料來自單一代理程式家族；AIDev 過度代表早期採用代理程式的儲存庫；兩者都不能推廣至私人程式碼庫。此外，作者也如此描述核心占比：面向代理程式的文件慣例大約只有兩年歷史，所以「60.5% 這個特定比例描述的是當下快照，不是穩定常數；我們預期會持續成立的發現，是這個類別的存在與顯著性，而非其確切規模。」

相關文章#

• Agent Context Files——本頁為這類產物提供了曝光分母。該頁對如何撰寫與注入 CLAUDE.md／AGENTS.md 的所有主張，如今都有代理程式文件注意力的實測占比（35.4%，且是下限）、代理程式在 PR 中重寫相同檔案的實測頻率（AGENTS.md 692 次、CLAUDE.md 362 次），以及「規格」論述所假定的驗證步驟並不存在這項實測結果
• Harness Activation and Adherence——同樣的兩道關卡，這次是在真實使用情境中觀察，而非在基準測試上評分。56.7% 的真實工作階段至少有一次文件互動；由於執行階段注入的檔案在重新讀取前不可見，指示檔數量明確是曝光量的下限——這是在外部測得的啟動關卡，無須考慮執行器的行動語法
• Layered Supervision——預防性護欄的定義（沒有任何東西會自動檢查的產物）有了行為測量：驗證事件為零，Verify 未作為互動類型出現，查閱後的測試也減少（lift 0.23）。實務工作者的規則——把重要內容複製到啟動與否不構成變數的層級——正是對這種追蹤結構的正確回應
• Context Lifecycle Management——論文對缺少驗證邊所提出的第一種可能機制：脈絡有限，所以代理程式把推理外化至檔案，讓文件成為工作記憶而非參考資料。工作筆記占 25.1%，而編輯文件後再次編輯文件的自我轉移率為 0.350，正是這種情況在追蹤資料中的樣貌
• Unknowns as the Agentic Bottleneck——Shihipar 的 implementation-notes.md 及其 Deviations 章節，是這篇論文以 25.1% 占比發現的文件類型之人工設計實例；論文提醒，此類文件在任何審查清單或品質指標中都沒有歸屬位置
• Agentic Technical Debt——共同變更的另一面：41.5% 的代理程式 PR 會變更文件，相較於人類註解維護研究比例偏高；但債務特徵在於變更順序——程式碼先於文件的情況多出 4.7 倍，若兩者分屬不同提交，82.5% 是程式碼先行
• Misalignment in Production Agent Traffic——資料庫中另一項 SWE-chat 研究，也是對語料規模的交叉檢查：Transluce 評估了同一公開釋出資料中的 4,990 個 SWE-chat 工作階段，而本論文的 557 個工作階段樣本也來自該資料集。兩者都是對未提示真實使用情況的追蹤測量；這篇測量代理程式讀寫什麼，另一篇測量代理程式如何談論這些內容
• Security Debt of Agent-Generated Code——資料庫中 AIDev 語料的主要參照。兩者使用同一個精選子集，資料形態相同（33,596 個 PR／2,807 個星數超過 100 的儲存庫），但檔案分類器不同：前者分析高風險路徑與新增行數，本文則使用 15 種文件分類法與 vendored 標記
• Agent-Vendor Heterogeneity——本論文第 6.3 節提醒不要從追蹤資料做出的跨廠商比較：某個代理程式家族直到解析 shell 內嵌路徑後，才不再是零文件事件；因此各代理程式的文件比率測量的是擷取涵蓋率，而非行為。任何標記廠商的追蹤統計都會受到這項風險影響
• Telemetry vs. Survey Measurement——把追蹤遙測用到合理範圍的範例：作者拒絕編碼目的，因為工具呼叫紀錄無法還原目的，推斷目的也無從證偽；因此改為報告觸發原因／互動／結果。這是語料中對紀錄能回答與不能回答之問題最明確的說明
• Human-Governed Skill Maintenance——本論文統計的這類產物，其維護面向包括誰會編輯面向代理程式的檔案、頻率如何、造成什麼效果。本文指出這些檔案經常被撰寫（產出活動是查閱活動的 0.87 倍，AGENTS.md 是 AIDev 中變更最多的檔案之一）；另一篇指出那些編輯是人類撰寫，而且在遷移任務上沒有帶來可測量的收益
• Verification as the New Bottleneck——把減少現象視為驗證落差的測量：查閱文件後三個事件內，代理程式執行測試的比率是基準率的 0.23 倍，執行建置的比率是 0.15 倍

延伸推導#

• Agent Control Plane Patterns: Tickets, Loops, Specs, and Memory Files——政策平面層現在有了行為占比，而驗證邊不存在也削弱了「規格」的解讀
• Is Persistence the Line Between Prompting and Spec-Driven Development?——獨立佐證該頁的結論：若持續保存且會被再次取用的產物，沒有任何東西會依據它接受檢查，它就不是規格。在 3,033 次觀察到的互動中，代理程式也沒有依據它檢查

待解決的問題#

• 若產物是可執行而非文字，缺少的驗證邊會不會出現？第 6.1 節提出此假說（可執行範例、doctests、綱要契約），而本研究無法檢驗。可用同一套工具驗證：對含有 doctests 或綱要契約的儲存庫重新執行擷取，檢查 read doc → run test 轉移率是否明顯高於本研究測得的 0.005。若沒有，那麼「可驗證性」就是產物的某項特性，任何交付格式都無法帶來這項特性。
• agent_working_note 真的是 25.1% 嗎？這個類別是論文影響最大的創新，也是測量驗證最不足之處——對 527 個模糊路徑使用第二層語言模型標註，沒有人工編碼，也沒有報告 κ 或 α；作者自己也指出，下一步必須對 200–300 個事件的子樣本進行雙人編碼。完全依照作者的說法即可驗證；在此之前，質性主張（存在一個規模龐大、過去未分類的類別）遠比該占比可靠。
• 指示檔的曝光量是否能反映指示檔的互動量？35.4% 只計算明確的讀取與編輯；除非代理程式重新開啟，否則工作階段開始時由執行階段注入的檔案不可見，因此這個數字是下限，但無法知道下限與真實值相差多少。若在 harness 端同時記錄注入內容與開啟內容，就能得出兩者比例；這個數字可判斷 35.4% 低估了多少：是略微低估，還是差了一個數量級。

資料來源#

• From Agent Behaviour to Agent-Friendly Documentation — Zhijun Gao & Jing Chen（Peking University），From Agent Behaviour to Agent-Friendly Documentation: An Empirical Study of How Coding Agents Discover, Read, and Write Technical Documentation，arXiv 2608.20195，2026-08-20，14 頁，empirical。作者沒有廠商隸屬關係，也沒有第一方資料集——兩個語料都是第三方公開釋出資料（2026 年 8 月 19 日的 SWE-chat 快照；AIDev 精選子集），擷取管線、編碼架構與事件層級資料均已公開。尚未經同儕審查。論文全部十個編號表格都已逐列與 pdftotext -layout 參考解析結果，以及圖 1 的五個面板核對；圖中也獨立以圖表標籤列出表 1、2、3、5(b) 與 10 的數值；未發現解析損壞。本頁完整保留作者提出的所有效度限制，未予摘要略過：以路徑識別使所有絕對比率都成為下限；第二層 agent_working_note 標籤未經人工驗證；階段判定規則具有黏性；解決率僅涵蓋 2,034 起事件中的 662 起；轉移為一階轉移；採用工作階段等權與依代理程式重新加權估計時，核心占比會變動（表 8）