ここだめAGENTS.md
AGENTS.md
AIコーディングエージェントをガイドするためのシンプルなフォーマット「AGENTS.md」を案内するサイトをOpenAIが公開しました。
早速自作コーディングエージェントShaftはコンテキストファイルとして以下のファイル、ディレクトリを読み込めるようアップデートしました。
./AGENTS.md
./.shaft/AGENTS.md
./.shaft/agents
~/.shaft/AGENTS.md
~/.shaft/agents
もちろん以前から対応していた以下コンテキストファイルも引き続き読み込めます。
./SHAFT.md
./.shaft/SHAFT.md
./.shaft/shaft
~/.shaft/SHAFT.md
~/.shaft/shaft
実は今回のAGENTS.mdファイルなどを読み込むアップデート、AGENTS.mdのウェブサイトに記載されているルールを守っていません。
現在のAGENTS.mdのどこがだめなのか、一つずつ紹介していきたいと思います。
ここだめ
- OpenAIが作った
- AGENTS.mdドメインを取得したのでXとかにPostするとリンクになる
- 「View 20k+ examples on GitHub」という謎アピール
- 完全一致でカウントしていない
- Clineが参加していない
- .clinerulesに統一しているので
- Claude Codeが参加していない
- CLAUDE.mdに統一しているので
実は少し前からAGENTS.mdでツール間の相互運用性を促進するサイトは別にあったのですが、巨人の肩に乗ったほうがよいと判断したのか、プロジェクトを廃止する予定のようです。
AGENTS.mdというファイル名
とにかくAGENTS.mdというファイル名は最悪です。
AGENTS.md をエージェント用の README として考えてください：AI コーディング エージェントがプロジェクトで作業する際の文脈と指示を提供する、専用で予測可能な場所です。
www.DeepL.com/Translator（無料版）で翻訳しました。
エージェントとは何でしょうか？
John F. Sowa著"Knowledge Representation"において、エージェントとは、意図的に何かをすることができる生体と定義しています。
エージェントとは、意図的に何かをすることができる生体のことである。この定義は、人間やその他の動物、行動を表す動詞の主語、そしてコンピュータ化されたロボットやソフトボットを含めるのに十分広い。しかし、この定義は、animate、capable、doing、purposeといった、同じように意味の難しい単語によって左右される。これらの言葉を定義する作業は、存在論の他のほとんどすべての側面に関わる問題を提起する。
AGENTS.mdが指すエージェントが人間のエージェントを指すのかAIエージェントを指すのかファイル名を見ただけでは分かりませんし、さらにAIエージェントなのかAIコーディングエージェントなのかも分かりません。
更にこのAGENTS.mdは主にContext（文脈）とInstruction（指示）を提供するよう定義されていますが、少なくともAGENTS.mdのファイル名だけでは文脈と指示を提供してくれるようには思えません。
自動的に読み込むのでコーディングエージェントにとってファイル名は関係ないのかもしれませんが、AGENTS.mdを知らない人がGitの公開リポジトリに置いたものをそのように理解できるとは思えません。
万能ではないコンテキストファイル
そもそもなぜCLAUDE.mdやGEMINI.mdのようにAGENTS.mdではないファイル名をわざわざつけているのかというと、これらのコンテキストファイルは各モデルやコーディングエージェント用に適した内容だからであって、AGENTS.mdに統一することによって神コンテキストファイルが出来上がるわけではないし、CLAUDE.mdやGEMINI.mdを使わなくて良くなるわけでもありません。
仮に、CLAUDE.mdやGEMINI.mdの代わりにAGENTS.mdをGitの公開リポジトリに置いたとしましょう。
このAGENTS.mdがどのコーディングエージェントで使用したものなのか、どのモデルと組み合わせることで良い結果を出力するかどのように知ればいいのでしょうか？
結果、GitHubのdescriptionやREADME.md、AGENTS.mdの最初に「コーディングエージェントとして○○を使いました」と書かなければいけなくなりますし、ユーザーも確認する手間がかかります。
そして特定のコーディングエージェントを使えない人にとっては、Gitの公開リポジトリからクローンしてきたときについてくるAGENTS.mdは、別途使用しているコーディングエージェントのコンテキストを汚染するものでしかありません。
.gitignoreにAGENTS.mdをGitで公開しないよう書いたほうがいいんですかね？
なぜかプロジェクトディレクトリをWalk Directoryする
AGENTS.mdの「How to use AGENTS.md?」には以下のように書かれています。
- 大規模なモノレポ？サブプロジェクト用にネストされたAGENTS.mdファイルを使用してください
各パッケージ内に別のAGENTS.mdファイルを配置します。エージェントはディレクトリツリー内で最も近いファイルを自動的に読み込むため、最も近いファイルが優先され、各サブプロジェクトはカスタマイズされた指示を配信できます。
この優先順位とは誰が判断するのでしょうか？ コーディングエージェントでしょうか？ モデルでしょうか？
もしモデルがAGENTS.mdを読み込むとして、node_modulesやvendorディレクトリが存在する場合、この中にあるAGENTS.mdはコンテキストを汚染しないのでしょうか？
.gitignoreや.ignoreに無視するよう記載して、コーディングエージェントが処理すればいいのでしょうか？
ただ
例えば、執筆時点ではメインのOpenAIリポジトリには88個のAGENTS.mdファイルが存在します。
と書かれているので、OpenAIのCodexを中心に書かれた文章のように見受けられます。
FAQを読み進めてもやはり似たような記述になっています。
Q. 指示が矛盾した場合、どうなりますか？
A. 編集されたファイルに最も近いAGENTS.mdが優先されます。明示的なユーザーチャットプロンプトはすべてを上書きします。
Q. エージェントは、AGENTS.md に記載されているテストコマンドを自動的に実行しますか？
A. はい—それらをリストアップした場合です。エージェントは、タスクを完了する前に、関連するプログラム的なチェックを実行し、失敗を修正しようとします。
でも特定のディレクトリはWalk Directoryしてほしい
そもそもAGENTS.mdというMarkdown一つでコンテキストファイルを管理するのは無理があるので、.agentsディレクトリにあるファイルをすべて読み込む設計が一番楽なのでそうしてほしいんですよね。
Issuesにもあります。
ただこうすると.agents/rulesにはルールを置いて、.agents/agentsにはFrontmatterで書いたカスタムエージェントを置いて、.agents/specには要件定義と設計のような仕様を置くようなオレオレDirectory Structureが作られていくので収集つかなくなりそうですね（もう大体のコーディングエージェントはそうなってそう）
また、Claude CodeのCLAUDE.mdではチャットと同様にアットマークをパスの先頭につけることで異なるコンテキストファイルを読み込む仕組みになっています。
- 要件定義は @spec/requirements.md を確認してください。
- 設計は @spec/design.md を確認してください。
AGENTS.mdには今のところこのような仕様について記載がありません。
ではどうすれば？
- AGENTS.mdをより良いものにしていく
- AGENTS.mdを使わない
- AGENTS.mdを自動的に読み込むコーディングエージェントを作らない
- あるいはAGENTS.mdのウェブサイトに記載されているルールを守らずに実装する
まだまだ他にも色々書きたいのですが、なんかもう疲れたのでHacker Newsあたりに任せます。
-
Source: https://jfsowa.com/ontology/agents.htm Copyright ©2001, 2005, by John F. Sowa. Permission is hereby granted for anyone to make verbatim copies of these documents for teaching, self-study, or other noncommercial purposes provided that the copies cite the author, the URL of this document, and this permission statement. ↩︎
Discussion