論文が実際に測定したもの
指示ファイルが主要なドキュメント領域である
細かく見ると、60.5%という数字は2つのカテゴリに分かれます。エージェントの指示ファイルは「最も頻繁に使用されるドキュメントタイプ（1,074イベント、35.4%）」であり、「エージェントによるプルリクエストにおいて最も頻繁に変更されるファイルの一つ」です。エージェントの作業メモ（計画、thoughts/ ディレクトリ、検証ログなど）は25.1%を占めています。
これに対し、APIリファレンスはわずか40イベント（ドキュメント操作の1.3%）に留まります。このギャップについて論文は、「指示ファイルはAPIリファレンスの約27倍の操作を受けている」とまとめています。
著者らが導き出した推奨事項は、限定的かつ実用的なものです。「エージェントのコントリビューターをサポートするために限られたドキュメントリソースを割り当てるプロジェクトにおいて、この違いは指示ファイルの正確性と明確さを優先すべきであることを示唆している。」これは「APIドキュメントの作成をやめろ」という意味ではありません。APIドキュメントは、この研究が対象としていない人間やツールに役立つからです。ただ、エージェントのために1時間をどこに費やすべきか迷っているなら、アクセスが集中するのは AGENTS.md であるということです。
エージェントはリンクをたどらない
この事実は、ほぼすべてのツールが提示するアドバイスを静かに覆すものです。「ドキュメントの閲覧の後は、さらに別の閲覧が続くことが頻繁にあります（遷移確率 0.270）。一方で、参照の追跡（Follow-reference）はまったく確認されませんでした。」
「まったく確認されなかった」とは、エージェントがあるドキュメントから別のドキュメントへの参照をたどった事例が、観察された中でゼロだったことを意味します。著者らの結論は慎重に表現されています。「このパターンは、エージェントがリンクの豊富なドキュメントをナビゲートすると仮定するのではなく、ローカルで検索可能な構造を持つ自己完結型のドキュメントを研究する動機となります。ただし、リンクの整理が行動にまったく影響を与えないと断定するものではありません。」
もしあなたの指示ファイルがほとんど他のファイルへのポインタ（リンク）で構成されているなら、この事実を重く受け止めるべきです。「理由は docs/architecture.md を参照してください」という一文は、美しく書かれていても、エージェントには一切実行されない可能性があります。
ドキュメントの参照とコードの編集は切り離されている
この点について、論文は自らの不確実性に対して非常に実直です。率直にまとめると、両者の結びつきは「存在しない」のではなく「未解明」であるということです。ドキュメントの閲覧からコードの編集への直接の遷移確率は 0.002 です。調整前の3イベントリフトは1.05であり、実質的にほぼゼロです。段階調整モデルでは1を超え、オッズ比（OR）は1.33 [1.09, 1.62] となります。ドキュメントの作成は逆の傾向を示します。調整前のリフトは1.67と上昇しますが、「調整後の区間には1が含まれます」。著者らが述べるように、「どちらの関連性も、仕様全体で一貫していません」。
つまり、エージェントはドキュメントを読んだ後、ほとんどの場合、推論するか、あるいはもう一度読むだけです。参照ループ内での最も強い遷移は、閲覧から閲覧への再帰（0.270、信頼区間 0.232–0.307）であり、そこから外へ向かう最も強い動きは推論への移行（0.245、信頼区間 0.205–0.295）です。
ドキュメントに基づいた検証は行われず、ドキュメントの参照はテストの減少と相関している
「ドキュメントに基づく明示的な検証シーケンスは観察されず、ドキュメントの参照は直後のテストの減少と関連しています（リフト 0.23、クラスター信頼区間 0.08–0.45、調整後OR 0.39 [0.25, 0.60]）。」別の箇所では、きっぱりと「検証イベントはゼロ」と述べられています。
これは観察データにおける相関関係であり、因果関係を主張するものではなく、著者らもそのような主張はしていません。しかし、これは「エージェントが自分の成果物をチェックできるようにドキュメントを書くべきだ」というよくあるアイデアが、今回の調査対象においては全く実行されていなかったことを意味します。
エージェントは行き詰まったからではなく、自ら進んでドキュメントを読む
ドキュメントの参照は、70.2%が自発的に行われており、エラーや失敗をきっかけとするものはわずか7.5%でした。また、失敗イベントの中でドキュメントの参照にフィードバックされた割合はわずか5.4%に過ぎません。さらに、ドキュメントはコードを先導するのではなく、後を追う傾向があります。「両方を変更するマルチコミットのプルリクエストにおいて、コードが最初に変更される頻度は、ドキュメントが最初に変更される頻度の4.7倍でした。」
著者ら自身の考察が最も興味深い部分である
これまでの文献が説明する人間の開発者の行動パターンとは一致しないループを発見した著者らは、2つの仮説を提示し、どちらか一方に決定することを避けています。
「エージェントはコンテキストウィンドウが制限されているため、推論をファイルに外部化している可能性があります。これにより、ドキュメントは参照用ではなく、一種のワーキングメモリ（作業記憶）として機能していると考えられます。計画や thoughts/ ディレクトリが目立つことは、この可能性と一致しています。あるいは、より手軽な検証手段であるテストスイートが直接呼び出されるため、テキストによる検証を行わないのかもしれません。いずれにせよ、テキストが仕様書として機能している様子は観察されませんでした。」
この1つの仮説は、60.5%という数字全体の捉え方を変えてしまいます。エージェントが「読んでいる」ものの大部分は、他に保存する場所がないために、10分前に自分自身で書き残したメモである可能性があるのです。そしてこれは、現在誰もツールを用意していない問題を引き起こします。「計画、thoughts/ ディレクトリ、検証ログは、永続的な成果物としてリポジトリに蓄積されます。しかし、現在のリポジトリ整理ツール、コードレビューのチェックリスト、ドキュメント品質の測定基準には、これらを分類するカテゴリが存在しません。」
この研究が証明すること、証明しないこと
見出しの数字よりも、その境界線を正しく理解することの方が重要です。この論文の「制限事項（Limitations）」セクションは、驚くほど率直に書かれています。
60.5%という数字は「ドキュメント操作」に占める割合であり、エージェントが読むすべてのものに対する割合ではありません。 分母は、94,813件の開発イベントのうち、3,033件のドキュメント操作です。「エージェントが読むものの60.5%」ではありません。これをエージェントの全活動における割合として引用している人がいれば、それは主張を歪めています。
この数字の4分の1は、明示的に「暫定的」なものです。 これは、多くの二次情報が省略しがちな注意書きであり、著者らも以下のように明記しています。「ドキュメントイベントの25.1%を占め、今回の主要な発見の一つである agent_working_note カテゴリは、500個の曖昧なパス（曖昧なイベントの98.4%）に対する言語モデルによる分類に基づいており、27個のパスはキーワードルールにフォールバックしています。これらのラベルに対する人間による検証は行われていません。そのため、このカテゴリの正確な割合は暫定的なものとして扱う必要があります。」ただし、定性的な発見は数字よりも確実であるとも付け加えています。エージェントが作成した作業ドキュメントは、正確な割合がどうであれ、生のパスから確認できる「大規模で、これまで分類されていなかったクラス」です。
絶対的な割合は下限値です。 「ドキュメントはファイルパスによって識別されています。ドックストリング、インラインコメント、ソースファイルに埋め込まれたテキストは、私たちの測定ツールでは検出できません。」ソースコード内ドキュメントを好むプロジェクトは過小評価されている可能性があり、著者らもその旨を述べています。
エージェントがなぜ読むのかという目的は測定されていません。 「目的は測定されていません。設計上、エージェントが特定のドキュメントを読む理由の分析は行っていません。」この研究が報告しているのは、トリガー、操作のタイプ、および結果であり、意図ではありません。
これは観察研究であるため、ドキュメントを変更すれば行動が変わるということを示すものではありません。 特に実行可能性（actionability）について、「これらの分析は、結びつきを示す一貫した行動の証拠を提供しておらず、私たちの観察設計では、実行可能性を向上させることが行動を変化させることを示すことはできません」と述べられています。
著者らは、最も引用しやすい比較をあえて避けています。 「ドキュメントに基づくエラー回復が最も高い点推定値（63.6%）を示したにもかかわらず、それがより効果的であると結論付けることは明示的に避けます。観察可能な結果がわずか11エピソードしかなく、信頼区間は35.4〜84.8%に及び、他のすべての選択肢と重複しているためです。」これは、研究チームが安易な見出しを狙わずに誠実な研究を行った証拠であり、だからこそ他の部分も信頼に値します。
また、この研究は異なる方向性を示す他の研究とも並行しています。 2026年の他の研究では、コンテキストファイルのパフォーマンスへの影響を測定し、その効果が弱いか、あるいはマイナスであることを発見しました。また別の研究では、モデルの能力に応じてスケールする、厳選された検索による効果を測定しています。これについては「AIエージェントにどの程度のメモリを与えるべきか」で詳しく解説しています。本論文はそのどちらも測定しておらず、測定しているのは「行動」です。この2つのアプローチを調和させることは今後の課題であり、2日前に発表された別の論文では、現在の測定手法がまだその段階に達していないと主張しています。これについては「エージェントのメモリは実際にパフォーマンスを向上させるのか」で議論しています。
MemoryLakeはこの研究に参加していません。 本論文では、当社のものを含め、いかなるメモリーレイヤーの評価も行っていません。
人々がこの研究から誤解しがちなこと
「エージェントは指示ファイルを無視する」 これは発見された事実とは真逆です。指示ファイルは、圧倒的な差で最も読まれているドキュメント領域です。弱いのは、読むことと次のアクションとの間の結びつきです。これは異なる主張であり、以前「なぜエージェントはあなたが書いた指示ファイルを無視するのか」で指摘した「読み込むことと、従うことは別である」という区別を裏付けるものです。本論文はこの点をさらに明確にしています。エージェントはファイルを読み込み、熱心に読みますが、それでも読むことが行動を確実に決定づけるわけではありません。
「だからドキュメントは重要ではない」 論文は、このコーパスにおいて2つの具体的な主張（実行可能性と検証可能性）に行動上の裏付けが欠けていると述べているだけです。ドキュメントが無用であるとは言っておらず、むしろ指示ファイルの正確性に投資することを明示的に推奨しています。
「エージェントは行き詰まったときにドキュメントを読む」 エラーをきっかけとするものはわずか7.5%です。この思い込みは、トリガーの分布データによって最も直接的に否定されています。
「相互リンクは無意味である」 今回のトレースにおいて参照の追跡（Follow-reference）は確認されましたが、著者らはリンクの整理に意味がないと結論付けることは避けています。これらは異なる主張です。
「これはエージェントにメモリーシステムが必要であることを証明している」 そのようなことは一切証明していません。エージェントがワーキングメモリに類似したファイルを書き出していることを観察し、それを行動パターンの2つの仮説の1つとして提示しているに過ぎません。
解決策：メモをメモリとして扱い、リポジトリ以外の最適な場所を提供する
もしワーキングメモリ仮説が正しいとすれば、それらの thoughts/ ディレクトリや計画ファイルの一部は、エージェントが手元にある唯一のツール（あなたのGitリポジトリ）を使ってメモリ管理を行っている結果です。しかし、あなたのレビュープロセスには、これらのファイルを分類するカテゴリがありません。ここから3つの対策が導き出されます。
蓄積されているものを監査する リポジトリ内を検索し、計画ファイル、thoughts/ ディレクトリ、エージェントが作成した検証ログを探します。ディレクトリごとに、それらが永続的な成果物なのか、それとも一時的なメモ（スクラッチ）なのかを判断します。ほとんどのチームは、気づかないうちに両方をコミットしてしまっていることに気づくでしょう。
アクセスの多い指示ファイルに時間を投資する 指示ファイルの正確性と明確さを向上させることは、エージェントが1.3%しか開かないAPIリファレンスに同じ労力を割くよりもはるかに高い効果をもたらします。また、参照の追跡（Follow-reference）が確認されなかったため、確実に伝えたい内容については、ポインタ（リンク）ではなく自己完結型の記述を優先してください。
「制御（ステアリング）」と「記憶（レコーディング）」を分離する 指示ファイルは常に読み込まれ、それを読み取るすべてのツールによって容量制限（キャップ）が課されるため、永続的な知識（決定事項、制約、却下されたアプローチなど）が最初に押し出されてしまいます。その結果、エージェントは計画ファイルを書き出すことで、それを再構築しようとします。
この最後の課題を解決するために設計されたのが MemoryLake です。メモリを、読み取り、修正、削除が可能なエントリとして管理し、リポジトリに副次的にコミットするのではなく、必要なときに関連情報をクエリできるようにします。セットアップは3つのステップで完了します。
ステップ 1: APIキーを作成する
MemoryLake にサインインし、APIキーを作成します。接続するすべてのツールで共通して使用できる1つの認証情報です。
ステップ 2: 最初のメモリをアップロードする
1つのエントリにつき1つの主張を含む、短い内容を登録します。現在、計画ファイルに書き込まれているか、あるいはどこにも残されていない以下のような情報を書き込みます。
それを強制した制約を伴う決定事項。 指示ファイルではルールとしてのみ記載され、その理由が省略されがちなカテゴリです。
すでに却下されたアプローチとその理由。 却下された理由を明文化しておくことで、新しいセッションで同じアプローチが再考されるのを防ぎます。再考のプロセスこそ、まさに thoughts/ ファイルに記録されている作業そのものです。
どこにも明記されていない環境に関する事実。 CIでのみ失敗するテスト、ドキュメント化されていないレート制限、2つのマイグレーション間の順序要件などです。
これまでに複数回行った修正指示。 人間が2回以上指摘しなければならなかったことは、終了した会話の中に埋もれさせるのではなく、検索可能な場所に保管すべきです。
ステップ 3: AIとエージェントを接続する
お使いのツールを接続します。MemoryLake は MCP（Model Context Protocol）および API 経由でアクセス可能です。そのため、Claude Code、Codex、OpenClaw などの MCP ネイティブなエージェントは MCP サーバーを指定するだけで接続でき、その他のアシスタントは API を通じて同じメモリを読み取ることができます。取得された情報は、常に読み込まれる指示ファイルの容量を圧迫せず、コミット履歴に残ることもありません。
ここで、3つの率直な制限事項を挙げます。最初の1つは、この記事の核心でもあります。MemoryLake はこの研究に参加しておらず、この論文はメモリーレイヤーがエージェントの行動を変化させる証拠にはなりません。 この研究は観察に基づくものであり、著者らもドキュメントの改善がエージェントの行動を変化させることを示すものではないと明言しています。MemoryLake は、あなたやエージェントが書き込んだ内容のみを保持します。また、リポジトリを自動的にクリーンアップするわけではありません。エージェントがすでにコミットした計画ファイルを監査するのは、手動の作業となります。
実践においてこれがもたらす変化
指示ファイルが第一級のドキュメントに昇格する。 これらは最も読まれている領域ですが、ほとんどのリポジトリでは README よりもレビューされる機会が少ないのが現状です。
エージェントが作成したメモがレビュー対象になる。 現在、これらには整理ツールも、チェックリストの項目も、陳腐化を測る指標も存在しません。
ポインタ（リンク）はコンテンツの代わりにならなくなる。 参照の追跡（Follow-reference）は確認されませんでした。制約が重要であるなら、それが必要とされる場所に直接記述してください。
ドキュメントはエラー回復プランではなくなる。 エージェントは行き詰まったときではなく、自発的にドキュメントを参照します。そのため、マニュアルというよりもオリエンテーションに近い位置づけであり、そのように記述されるべきです。
エージェントが実際に使用するドキュメントを作成するためのベストプラクティス
最も重要な1時間を指示ファイルに費やす。 指示ファイルは、このコーパスにおいてAPIリファレンスの約27倍も読まれている、最も頻繁に利用されるドキュメントタイプです。
各記述を自己完結させる。 参照の追跡は観察されませんでした。エージェントは開いたファイルだけで読むのを止めると想定してください。
エージェントの作業メモに保管場所とライフサイクルを与える。 何が永続的な成果物で、何が一時的なメモ（スクラッチ）なのか、そして何をコミットすべきでなかったのかを判断します。
ドキュメントを検証手段として頼らない。 検証イベントはゼロでした。テストこそが、エージェントが実際に利用する検証手段です。
常に読み込まれるファイルから推論プロセスを排除する。 すべてのツールはファイル容量に制限を設けており、推論プロセスは最初にカットされます。これについては「なぜRAGはメモリではないのか」で解説しています。そして、散らばったメモをクエリ可能な形に統合することが重要です。これについては「プロジェクトのドキュメントをAIのメモリに変換する」で解説しています。
単一コーパスに基づく行動の発見は暫定的なものとして扱う。 2つのデータセット、ファイルパスによるドキュメント識別、著者らが未検証とする1つの作業メモカテゴリ。これらは有用ですが、確定した事実ではありません。
結論
コーディングエージェントは実際に何を読んでいるのでしょうか？557件のセッションと33,097件のプルリクエストの証拠に基づくと、圧倒的に「彼らのために書かれたファイル」です。エージェントの指示ファイルとエージェントの作業メモがドキュメント操作の60.5%を占め、従来の技術ドキュメントは10.6%、APIリファレンスは1.3%でした。
しかし、割合よりも重要なのはそのプロセスです。エージェントは行き詰まったときではなく自発的にドキュメントを参照し、コードに移行するよりも閲覧と推論のループにとどまり、別のドキュメントへの参照をたどることはなく、テキストに対して成果物を検証する様子も観察されませんでした。著者ら自身の見解では、これらの多くは参照を探しているのではなく、制限されたコンテキストウィンドウによってエージェントが推論をファイルに外部化せざるを得なくなっている、つまり「ドキュメントを参照用ではなく、一種 of ワーキングメモリとして機能させている」可能性があります。
もしこれが正しいとすれば、実用的な結論は「より良いドキュメントを書くこと」ではありません。あなたのリポジトリが、レビュープロセスに認識されないまま、エージェントのスクラッチパッド（一時メモ帳）に静かになってしまっているということです。最も読まれる指示ファイルに投資しましょう。リンクをたどるエージェントはいないため、記述は自己完結させてください。そして、永続的な知識（決定事項、制約、すでに除外されたアプローチなど）には、容量制限のある常時読み込みファイルや、誰もレビューしない thoughts/ ディレクトリではない、適切な保管場所を提供してください。