<h1 id="agents.md" data-line="0" class="code-line">
<a class="header-anchor-link" href="#agents.md" aria-hidden="true"></a> AGENTS.md</h1>
<p data-line="2" class="code-line"><span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__d53364cbeafd6" src="https://embed.zenn.studio/card#zenn-embedded__d53364cbeafd6" data-content="https%3A%2F%2Fgihyo.jp%2Farticle%2F2025%2F08%2Fagents-md-site" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://gihyo.jp/article/2025/08/agents-md-site" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://gihyo.jp/article/2025/08/agents-md-site</a></p>
<p data-line="4" class="code-line">AIコーディングエージェントをガイドするためのシンプルなフォーマット「AGENTS.md」を案内するサイトをOpenAIが公開しました。</p>
<p data-line="6" class="code-line"><span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__d31e5ac894d54" src="https://embed.zenn.studio/card#zenn-embedded__d31e5ac894d54" data-content="https%3A%2F%2Fgitlab.com%2Ftkithrta%2Fshaft" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://gitlab.com/tkithrta/shaft" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://gitlab.com/tkithrta/shaft</a></p>
<p data-line="8" class="code-line">早速自作コーディングエージェントShaftはコンテキストファイルとして以下のファイル、ディレクトリを読み込めるようアップデートしました。</p>
<div class="code-block-container"><pre><code class="code-line" data-line="10">./AGENTS.md
./.shaft/AGENTS.md
./.shaft/agents
~/.shaft/AGENTS.md
~/.shaft/agents
</code></pre></div><p data-line="18" class="code-line">もちろん以前から対応していた以下コンテキストファイルも引き続き読み込めます。</p>
<div class="code-block-container"><pre><code class="code-line" data-line="20">./SHAFT.md
./.shaft/SHAFT.md
./.shaft/shaft
~/.shaft/SHAFT.md
~/.shaft/shaft
</code></pre></div><p data-line="28" class="code-line">実は今回のAGENTS.mdファイルなどを読み込むアップデート、AGENTS.mdのウェブサイトに記載されているルールを守っていません。</p>
<p data-line="30" class="code-line">現在のAGENTS.mdのどこがだめなのか、一つずつ紹介していきたいと思います。</p>
<aside class="msg message"><span class="msg-symbol">!</span><div class="msg-content">
<p data-line="33" class="code-line">引用文は<code>www.DeepL.com/Translator（無料版）で翻訳しました。</code></p>
</div></aside>
<h1 id="%E3%81%93%E3%81%93%E3%81%A0%E3%82%81" data-line="36" class="code-line">
<a class="header-anchor-link" href="#%E3%81%93%E3%81%93%E3%81%A0%E3%82%81" aria-hidden="true"></a> ここだめ</h1>
<p data-line="38" class="code-line"><span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__1648ea20cbae" src="https://embed.zenn.studio/card#zenn-embedded__1648ea20cbae" data-content="https%3A%2F%2Fagents.md%2F" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://agents.md/" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://agents.md/</a></p>
<ul data-line="40" class="code-line">
<li data-line="40" class="code-line">OpenAIが作った</li>
<li data-line="41" class="code-line">AGENTS.mdドメインを取得したのでXとかにPostするとリンクになる</li>
<li data-line="42" class="code-line">「View 20k+ examples on GitHub」という謎アピール
<ul data-line="43" class="code-line">
<li data-line="43" class="code-line">完全一致でカウントしていない</li>
</ul>
</li>
<li data-line="44" class="code-line">Clineが参加していない
<ul data-line="45" class="code-line">
<li data-line="45" class="code-line">.clinerulesに統一しているので</li>
</ul>
</li>
<li data-line="46" class="code-line">Claude Codeが参加していない
<ul data-line="47" class="code-line">
<li data-line="47" class="code-line">CLAUDE.mdに統一しているので</li>
</ul>
</li>
</ul>
<p data-line="49" class="code-line">実は少し前からAGENTS.mdでツール間の相互運用性を促進するサイトは別にあったのですが、巨人の肩に乗ったほうがよいと判断したのか、プロジェクトを廃止する予定のようです。</p>
<p data-line="51" class="code-line"><span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__4276a30e40e29" src="https://embed.zenn.studio/card#zenn-embedded__4276a30e40e29" data-content="https%3A%2F%2Fagent-rules.org%2F" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://agent-rules.org/" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://agent-rules.org/</a><br style="display:none">
<span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__f42359403a74c" src="https://embed.zenn.studio/card#zenn-embedded__f42359403a74c" data-content="https%3A%2F%2Fgithub.com%2Fagent-rules%2Fagent-rules%2Fissues%2F9" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://github.com/agent-rules/agent-rules/issues/9" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://github.com/agent-rules/agent-rules/issues/9</a></p>
<h2 id="agents.md%E3%81%A8%E3%81%84%E3%81%86%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E5%90%8D" data-line="54" class="code-line">
<a class="header-anchor-link" href="#agents.md%E3%81%A8%E3%81%84%E3%81%86%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E5%90%8D" aria-hidden="true"></a> AGENTS.mdというファイル名</h2>
<p data-line="56" class="code-line">とにかくAGENTS.mdというファイル名は最悪です。</p>
<blockquote data-line="58" class="code-line">
<p data-line="58" class="code-line">AGENTS.md をエージェント用の README として考えてください：AI コーディング エージェントがプロジェクトで作業する際の文脈と指示を提供する、専用で予測可能な場所です。<br>
<code>www.DeepL.com/Translator（無料版）で翻訳しました。</code></p>
</blockquote>
<p data-line="61" class="code-line">エージェントとは何でしょうか？<br>
John F. Sowa著"Knowledge Representation"において、エージェントとは、意図的に何かをすることができる生体と定義しています。</p>
<blockquote data-line="64" class="code-line">
<p data-line="64" class="code-line">エージェントとは、意図的に何かをすることができる生体のことである。この定義は、人間やその他の動物、行動を表す動詞の主語、そしてコンピュータ化されたロボットやソフトボットを含めるのに十分広い。しかし、この定義は、animate、capable、doing、purposeといった、同じように意味の難しい単語によって左右される。これらの言葉を定義する作業は、存在論の他のほとんどすべての側面に関わる問題を提起する。</p>
<p data-line="66" class="code-line">Source: <a href="https://jfsowa.com/ontology/agents.htm" target="_blank" rel="nofollow noopener noreferrer">https://jfsowa.com/ontology/agents.htm</a><sup class="footnote-ref"><a href="#fn-8e8b-1" id="fnref-8e8b-1">[1]</a></sup></p>
</blockquote>
<p data-line="68" class="code-line">AGENTS.mdが指すエージェントが人間のエージェントを指すのかAIエージェントを指すのかファイル名を見ただけでは分かりませんし、さらにAIエージェントなのかAIコーディングエージェントなのかも分かりません。</p>
<p data-line="70" class="code-line">更にこのAGENTS.mdは主にContext（文脈）とInstruction（指示）を提供するよう定義されていますが、少なくともAGENTS.mdのファイル名だけでは文脈と指示を提供してくれるようには思えません。</p>
<p data-line="72" class="code-line">自動的に読み込むのでコーディングエージェントにとってファイル名は関係ないのかもしれませんが、AGENTS.mdを知らない人がGitの公開リポジトリに置いたものをそのように理解できるとは思えません。</p>
<h2 id="%E4%B8%87%E8%83%BD%E3%81%A7%E3%81%AF%E3%81%AA%E3%81%84%E3%82%B3%E3%83%B3%E3%83%86%E3%82%AD%E3%82%B9%E3%83%88%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB" data-line="74" class="code-line">
<a class="header-anchor-link" href="#%E4%B8%87%E8%83%BD%E3%81%A7%E3%81%AF%E3%81%AA%E3%81%84%E3%82%B3%E3%83%B3%E3%83%86%E3%82%AD%E3%82%B9%E3%83%88%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB" aria-hidden="true"></a> 万能ではないコンテキストファイル</h2>
<p data-line="76" class="code-line">そもそもなぜCLAUDE.mdやGEMINI.mdのようにAGENTS.mdではないファイル名をわざわざつけているのかというと、これらのコンテキストファイルは各モデルやコーディングエージェント用に適した内容だからであって、AGENTS.mdに統一することによって神コンテキストファイルが出来上がるわけではないし、CLAUDE.mdやGEMINI.mdを使わなくて良くなるわけでもありません。</p>
<p data-line="78" class="code-line">仮に、CLAUDE.mdやGEMINI.mdの代わりにAGENTS.mdをGitの公開リポジトリに置いたとしましょう。<br>
このAGENTS.mdがどのコーディングエージェントで使用したものなのか、どのモデルと組み合わせることで良い結果を出力するかどのように知ればいいのでしょうか？</p>
<p data-line="81" class="code-line">結果、GitHubのdescriptionやREADME.md、AGENTS.mdの最初に「コーディングエージェントとして○○を使いました」と書かなければいけなくなりますし、ユーザーも確認する手間がかかります。</p>
<p data-line="83" class="code-line">そして特定のコーディングエージェントを使えない人にとっては、Gitの公開リポジトリからクローンしてきたときについてくるAGENTS.mdは、別途使用しているコーディングエージェントのコンテキストを汚染するものでしかありません。<br>
.gitignoreにAGENTS.mdをGitで公開しないよう書いたほうがいいんですかね？</p>
<h2 id="%E3%81%AA%E3%81%9C%E3%81%8B%E3%83%97%E3%83%AD%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E3%83%87%E3%82%A3%E3%83%AC%E3%82%AF%E3%83%88%E3%83%AA%E3%82%92walk-directory%E3%81%99%E3%82%8B" data-line="86" class="code-line">
<a class="header-anchor-link" href="#%E3%81%AA%E3%81%9C%E3%81%8B%E3%83%97%E3%83%AD%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E3%83%87%E3%82%A3%E3%83%AC%E3%82%AF%E3%83%88%E3%83%AA%E3%82%92walk-directory%E3%81%99%E3%82%8B" aria-hidden="true"></a> なぜかプロジェクトディレクトリをWalk Directoryする</h2>
<p data-line="88" class="code-line">AGENTS.mdの「How to use AGENTS.md?」には以下のように書かれています。</p>
<blockquote data-line="90" class="code-line">
<ol start="4" data-line="90" class="code-line">
<li data-line="90" class="code-line">大規模なモノレポ？サブプロジェクト用にネストされたAGENTS.mdファイルを使用してください<br>
各パッケージ内に別のAGENTS.mdファイルを配置します。エージェントはディレクトリツリー内で最も近いファイルを自動的に読み込むため、最も近いファイルが優先され、各サブプロジェクトはカスタマイズされた指示を配信できます。</li>
</ol>
</blockquote>
<p data-line="93" class="code-line">この優先順位とは誰が判断するのでしょうか？ コーディングエージェントでしょうか？ モデルでしょうか？<br>
もしモデルがAGENTS.mdを読み込むとして、node_modulesやvendorディレクトリが存在する場合、この中にあるAGENTS.mdはコンテキストを汚染しないのでしょうか？<br>
.gitignoreや.ignoreに無視するよう記載して、コーディングエージェントが処理すればいいのでしょうか？</p>
<p data-line="97" class="code-line">ただ</p>
<blockquote data-line="99" class="code-line">
<p data-line="99" class="code-line">例えば、執筆時点ではメインのOpenAIリポジトリには88個のAGENTS.mdファイルが存在します。</p>
</blockquote>
<p data-line="101" class="code-line">と書かれているので、OpenAIのCodexを中心に書かれた文章のように見受けられます。</p>
<p data-line="103" class="code-line">FAQを読み進めてもやはり似たような記述になっています。</p>
<blockquote data-line="105" class="code-line">
<p data-line="105" class="code-line">Q. 指示が矛盾した場合、どうなりますか？<br>
A. 編集されたファイルに最も近いAGENTS.mdが優先されます。明示的なユーザーチャットプロンプトはすべてを上書きします。</p>
</blockquote>
<blockquote data-line="108" class="code-line">
<p data-line="108" class="code-line">Q. エージェントは、AGENTS.md に記載されているテストコマンドを自動的に実行しますか？<br>
A. はい—それらをリストアップした場合です。エージェントは、タスクを完了する前に、関連するプログラム的なチェックを実行し、失敗を修正しようとします。</p>
</blockquote>
<h2 id="%E3%81%A7%E3%82%82%E7%89%B9%E5%AE%9A%E3%81%AE%E3%83%87%E3%82%A3%E3%83%AC%E3%82%AF%E3%83%88%E3%83%AA%E3%81%AFwalk-directory%E3%81%97%E3%81%A6%E3%81%BB%E3%81%97%E3%81%84" data-line="111" class="code-line">
<a class="header-anchor-link" href="#%E3%81%A7%E3%82%82%E7%89%B9%E5%AE%9A%E3%81%AE%E3%83%87%E3%82%A3%E3%83%AC%E3%82%AF%E3%83%88%E3%83%AA%E3%81%AFwalk-directory%E3%81%97%E3%81%A6%E3%81%BB%E3%81%97%E3%81%84" aria-hidden="true"></a> でも特定のディレクトリはWalk Directoryしてほしい</h2>
<p data-line="113" class="code-line">そもそもAGENTS.mdというMarkdown一つでコンテキストファイルを管理するのは無理があるので、<code>.agents</code>ディレクトリにあるファイルをすべて読み込む設計が一番楽なのでそうしてほしいんですよね。<br>
Issuesにもあります。</p>
<p data-line="116" class="code-line"><span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__2e261730e76cd" src="https://embed.zenn.studio/card#zenn-embedded__2e261730e76cd" data-content="https%3A%2F%2Fgithub.com%2Fopenai%2Fagents.md%2Fissues%2F2" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://github.com/openai/agents.md/issues/2" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://github.com/openai/agents.md/issues/2</a></p>
<p data-line="118" class="code-line">ただこうすると<code>.agents/rules</code>にはルールを置いて、<code>.agents/agents</code>にはFrontmatterで書いたカスタムエージェントを置いて、<code>.agents/spec</code>には要件定義と設計のような仕様を置くようなオレオレDirectory Structureが作られていくので収集つかなくなりそうですね（もう大体のコーディングエージェントはそうなってそう）</p>
<p data-line="120" class="code-line">また、Claude CodeのCLAUDE.mdではチャットと同様にアットマークをパスの先頭につけることで異なるコンテキストファイルを読み込む仕組みになっています。</p>
<div class="code-block-container"><pre class="language-markdown"><code class="language-markdown code-line" data-line="122"><span class="token list punctuation">-</span> 要件定義は @spec/requirements.md を確認してください。
<span class="token list punctuation">-</span> 設計は @spec/design.md を確認してください。
</code></pre></div><p data-line="127" class="code-line">AGENTS.mdには今のところこのような仕様について記載がありません。</p>
<h1 id="%E3%81%A7%E3%81%AF%E3%81%A9%E3%81%86%E3%81%99%E3%82%8C%E3%81%B0%EF%BC%9F" data-line="129" class="code-line">
<a class="header-anchor-link" href="#%E3%81%A7%E3%81%AF%E3%81%A9%E3%81%86%E3%81%99%E3%82%8C%E3%81%B0%EF%BC%9F" aria-hidden="true"></a> ではどうすれば？</h1>
<ul data-line="131" class="code-line">
<li data-line="131" class="code-line">AGENTS.mdをより良いものにしていく</li>
<li data-line="132" class="code-line">AGENTS.mdを使わない</li>
<li data-line="133" class="code-line">AGENTS.mdを自動的に読み込むコーディングエージェントを作らない
<ul data-line="134" class="code-line">
<li data-line="134" class="code-line">あるいはAGENTS.mdのウェブサイトに記載されているルールを守らずに実装する</li>
</ul>
</li>
</ul>
<p data-line="136" class="code-line">まだまだ他にも色々書きたいのですが、なんかもう疲れたのでHacker Newsあたりに任せます。</p>
<p data-line="138" class="code-line"><span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__2961b3e6c9213" src="https://embed.zenn.studio/card#zenn-embedded__2961b3e6c9213" data-content="https%3A%2F%2Fnews.ycombinator.com%2Fitem%3Fid%3D44957443" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://news.ycombinator.com/item?id=44957443" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://news.ycombinator.com/item?id=44957443</a></p>
<section class="footnotes">
<span class="footnotes-title">脚注</span>
<ol class="footnotes-list">
<li id="fn-8e8b-1" class="footnote-item">
<p data-line="140" class="code-line">Source: <a href="https://jfsowa.com/ontology/agents.htm" target="_blank" rel="nofollow noopener noreferrer">https://jfsowa.com/ontology/agents.htm</a> 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. <a href="#fnref-8e8b-1" class="footnote-backref">↩︎</a></p>
</li>
</ol>
</section>


ここだめAGENTS.md

万能ではないコンテキストファイル

なぜかプロジェクトディレクトリをWalk Directoryする

でも特定のディレクトリはWalk Directoryしてほしい

aiエージェント

codex

コンテキストエンジニアリング

Discussion