AGENTS.md


Paper/Blog Link My Issue
#Analysis #NLP #LanguageModel #AIAgents #Coding #SoftwareEngineering #Initial Impression Notes Issue Date: 2026-03-03 GPT Summary- AIコーディング・エージェント（CodexやClaude Codeなど）がソフトウェア・リポジトリに与える影響を調査。AGENTS.mdファイルの有無で、GitHubプルリクエストにおけるエージェントの実行時間とトークン消費が異なることを示し、AGENTS.mdの存在が実行時間を28.64%、トークン消費を16.58%削減する一方、タスク完了挙動は同等であることが分かった。これに基づき、AIコーディング・エージェントの設定やデプロイに関する実務的な含意を議論し、リポジトリレベルの指示の重要性を明らかにする。 Comment

関連:
- [Paper Note] Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?, Thibaud Gloaguen+, arXiv'26, 2026.02

こちらの研究ではどちらかというとAGENTS.mdによってinference costが増大するようなことが示されているが、具体的にAGENTS.mdの内容としてどのような違いがあるだろうか？

元ポスト:

Loading…




Paper/Blog Link My Issue
#NLP #Dataset #LanguageModel #AIAgents #Evaluation #Coding #SoftwareEngineering #read-later #Selected Papers/Blogs #Initial Impression Notes Issue Date: 2026-02-27 GPT Summary- コーディングエージェントのタスク完遂性能を評価するため、LLMが生成したコンテキストファイルと開発者提供のファイルを用いた2つの設定を検討。結果、コンテキストファイルは成功率を低下させ、推論コストを増加させる傾向が見られた。両者はタスクの探求を促進するが、不要な要件がタスクを難化させるため、最小限の要件のみを記述することが推奨される。 Comment

元ポスト:

Loading…

（現時点では）LLMによって自動生成されたコンテキストファイルは性能を劣化させ、inference costを増大させ、人間が作成したコンテキストファイルは性能を向上させる。コンテキストファイルによってoverviewを提供することを推奨しているものがあるが、性能向上には寄与しない。コンテキストファイルに従うことはより多くのthinkingを誘発し、結果的にタスクを難しくする。最小限のrequirementsのみを記述したものを使うことを推奨する、といった内容らしい？

関連:

Loading…


best practiceは以下とのこと:
- # Writing a good CLAUDE.md, Kyle, 2025.11

解説:

Loading…


非常にコンパクトにまとまっている。

解説:

Loading…




Paper/Blog Link My Issue
#Analysis #NLP #LanguageModel #AIAgents #Coding #SoftwareEngineering #ContextEngineering #Initial Impression Notes Issue Date: 2026-03-03 GPT Summary- AGENTS.mdを通じて、AIコーディングアシスタントにおける文脈情報の提供方法を調査。466のオープンソースプロジェクトから得たデータに基づき、情報の提示方法や進化を分析。結果、標準化された構造は存在せず、提供方法に大きなばらつきがあることが明らかに。AI文脈ファイルの設計が内容の品質向上に与える影響を研究する潜在性を示唆。 Comment

元ポスト:

Loading…

オープンソースのリポジトリにおけるAGENTS.mdに関する分析らしい。

関連:
- [Paper Note] Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?, Thibaud Gloaguen+, arXiv'26, 2026.02
- # Writing a good CLAUDE.md, Kyle, 2025.11




Paper/Blog Link My Issue
#Article #NLP #AIAgents #Blog #Selected Papers/Blogs #KeyPoint Notes #Surface-level Notes #Reading Reflections Issue Date: 2026-02-27 Comment

元ポスト:

Loading…

本ブログは CLAUDE.md について記述されているものだが、ブログ冒頭で記述されており、AGENTS.mdに一般的に適用できる話だと考えられるため、以下本文中でCLAUDE.mdとして記述されている部分も、AGENTS.mdと読み替えて記述している。

要するに
- `AGENTS.md` はAI Agentの **全ての会話に対してコンテキストをユーザが明示的に挿入する唯一の手段** であり、
- `AGENTS.md` にはプロジェクトのあらゆるタスクで **普遍的に必要な情報を、過不足なく、簡潔に記述されるべき** であり
- プロジェクトが大規模な場合は、`AGENTS.md` は目次として利用し、必要な情報は個別のファイルに別々に記述し、`AGENTS.md` 内にはその **ポインターのみを記載** する
- `AGENTS.md` の **自動生成は非推奨** であり、理由としては1行でも誤った記述が含まれていた場合全てのエージェントの挙動に影響が出るためであり、全ての内容について慎重に検討をしたうえで記述されるべきである。

という話のようである。

-----

- 原則
- AI Agentはstatelessであり、あなたのコードベースについて何も知らない。このため利用者がコンテキストとしてコードベースの情報を伝える必要があり、そのために有用なツールがAGENTS.mdである
- AGENTS.mdはすべての会話にデフォルトでコンテキストとして含まれる **唯一の** ファイルである
- AGENTS.mdでどのような情報が網羅されるべきか？
- **WHAT**: 技術スタック、プロジェクト構造、コードベースの構成等のリポジトリの基本情報を記述し、Agentが適切に情報を検索できるようにする
- **WHY**: プロジェクトの役割と、リポジトリ内の要素の役割
- **HOW**: Agentがどのような作業をすべきに関する明確な指示を記述し、その指示を実施するために必要な情報を全て含める
- AGENT.md はしばしば無視される
- たとえばClaude CodeではCLAUDE.md (Claudeが利用するAGENTS.md) をコンテキストに含める際に以下のシステムリマインダーを自動的に挿入する:
- つまり、AGENTS.mdに普遍的に利用可能な情報が含まれていない場合は、現在実施しようとしているタスクと関係ないとエージェントが判断し、AGENTS.mdが無視されることがある点に注意が必要

```

IMPORTANT: this context may or may not be relevant to your tasks.
You should not respond to this context unless it is highly relevant to your task.

```
- 優れたAGENTS.mdを作成するベストプラクティス
- **less (instructions) is more**:
- AI Agentが順守できる指示の数には限界があり、指示の数が増えれば増えるほど、指示を遵守できない割合が高まっていく。
- これはモデル依存であり、パラメータ数が大きいモデルほど多くの指示を遵守できる（150--200など）。
- AGENTS.mdがすべての会話に付与されることを考えると、たとえば50個の指示をAGENTS.mdに含めた場合、150個の指示を遵守できるAgentを利用していたら、AGENTS.mdだけで1/3だけを消費することになる。
- また、指示が増えれば増えるほど、均一に指示追従の能力が低下する。
- つまり、ある指示が冒頭・末尾に書かれていようとも、位置に関係なく何らかの指示に追従しない可能性が高まる。
- これらの性質から、可能な限り少ない指示を記述することが必要で、特に冗長性を排除し、あらゆるタスクに普遍的に適用可能な指示のみを記述することが肝要であることが示唆される。
- length & applicability:
- AGENTS.mdは、300行未満などが推奨されているが、要は **適切な普遍的に適用可能な情報が** 簡潔で短く記述されていることが好ましい[^1]。
- Progressive Disclosure
- プロジェクトが大規模化した場合、必要な全ての情報を簡潔にAGENTS.mdに含めることがそもそも困難になる
- この場合はAGENTS.mdに目次を記述し、機能ごとの必要な情報は個別のファイルに記述し、それがどこに格納されているかのポインタを記述することによって解決する
- AGENTS.mdに全ての情報を書いてしまってはいけない。この場合上記の less is more や length の原則に反することになる。
- AGENT (CLAUDE) is not an expensive linter
- コーディング規約を書いている人が多いがやめた方が良いという話で、
- コーディング規約を無視しているか否かを判断させるにはもっと決定論的で安価なツールがあるのでそちらに任せましょうという話と、
- コーディング規約を明示していなくてもAgentはコードスニペットを解釈する過程で暗黙的にどのようなコーディング規約に従っているかは理解できるので、わざわざ明示的に挿入して不要で無関係なコンテキストで埋め尽くす必要はないよね、という話が書かれている。
- `/init` コマンドや、`AGENTS.md (CLAUDE.md)` の**自動生成は非推奨**
- AGENTS.md はAgentの全ての挙動に影響を与えるため、1行でも誤りがあると全ての作業に影響が出る非常にクリティカルなファイルであるため、自動生成等に頼らずに、慎重に検討をした上で記述されるべきである、という話
- 実際、下記研究にてLLMが自動生成したAGENTS.mdでは、タスク性能は劣化しトークン消費量が増えるだけ、という結果が示されている
- [Paper Note] Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?, Thibaud Gloaguen+, arXiv'26, 2026.02

[^1]: 根拠として、ブログ中では、無関係な情報がコンテキストで埋め尽くされているよりも、関連性のある情報が埋め尽くされる場合が一般的に性能が向上すると書かれている。が、文献などは引用されていないように見える。たとえば、この記述に対して、「初期のRAGの研究でrelevantな情報に対してirrelevantな情報が周囲で埋め尽くされていた場合に実は性能が向上します、といった話があったじゃないか」といった鉞を飛ばすことができそうだが、これは古い研究でおそらく当時（数年前）のLLMではcontext中のrelevantな情報を見分ける能力が低かったことに起因する。つまり、このような現象は明らかにirrelevantな情報が混在することで、相対的にrelevantな情報が際立つことによってLLMのcontextの理解力が乏しい部分を補っていた、と管理人は推察しており、現代のLLMではcontextを解釈する性能は大幅に向上していると考えられるため、わざわざirrelevantな情報をcontextに含める必要はなく、この見解には私も同意する。そもそもこの私の見解があまりにも重箱の隅すぎて蛇足すぎるがなんかそういうことを思い出しちゃったので書いた :)

ここで記載されている内容はAGENTS.mdのみならず、そもそものプロンプトエンジニアリング全般で言える話でもある。