AGENTS.md覚書

2025年8月に OpenAI が公開した形式で、Amp、Google の Jules、Cursor、Factory などと一緒にまとめられました。同じ年の12月には、Linux Foundation のもとで発足した Agentic AI Foundation（AAIF）に、第1回で触れた MCP などと並んで寄贈されています。特定の会社の持ち物ではない、共通の形式です。公式サイトによると、使っているオープンソースのプロジェクトは6万以上、読めるエージェントや IDE は30を超えます。

README との違いは、読み手です。README は人のためのもので、何のプロジェクトか、どう使うかを書きます。AGENTS.md はエージェントが作業するためのもので、どのコマンドで確かめるか、何をしてはいけないかを書きます。人向けの説明を細かい指示で散らかさずに、置き場所を分けられる、というのが公式の説明です。

• 推測できないことがある ── 「この HTML は生成物だから直接いじらない」「公開は人が確認してから」といったことは、コードをいくら読んでも分かりません
• 推測にはお金と時間がかかる ── テストの流し方を探して、あちこちのファイルを開き、試しては失敗する。書いてあれば1行で済みます
• 言う人によって指示がぶれる ── チームの誰がどのエージェントを使っても同じ約束で動くよう、口頭の注意をファイルに移します

人間の新人に渡すオンボーディング資料と同じ役目、と考えると分かりやすいでしょう。違うのは、相手が毎回かならず全文を読み、書いてあることにかなり素直に従うことです。だからこそ、短く、正確に書く必要があります。

目安は、「同じ注意を、エージェントに2回言ったかどうか」です。2回言ったことは、3回目もきっと言うことになります。その時点で AGENTS.md に1行足すのが、いちばん無駄のない育て方です。

• コマンドは、そのまま実行できる形で ── 「テストする」ではなく npm test -- --run。エージェントは書かれたコマンドを実際に流します
• 理由を一言添える ── 「生成物なので直接編集しない（元の build.py を直す）」のように。理由があると、書いていない似た場面にも正しく応用してくれます
• 禁止は、代わりの手順とセットで ── 「〜しない」だけだと、エージェントは別の抜け道を探します
• 長くしない ── Claude Code の公式ドキュメントは CLAUDE.md を200行以内を目安にしています。Codex は読み込む合計を既定で32KiBに制限。長いほど従われにくくなり、そのぶん毎回のコストもかかります
• 秘密は書かない ── パスワードや API キーはリポジトリに入れない。ファイルは全員に共有されます
• 絶対に守らせたいことは、仕組みで ── AGENTS.md はあくまで「文脈」で、強制力はありません。main に直接入れさせないならブランチ保護、書式を崩させないなら CI やフック（Claude Code の hooks など）で止めます

モノレポでは、サブフォルダにも AGENTS.md を置けます。公式サイトの説明は「いちばん近いファイルが優先」、そして「依頼の文面はすべてに優先」。OpenAI 自身のリポジトリには、AGENTS.md が88個あるそうです。

Claude Code と併用するときは、CLAUDE.md がなければ AGENTS.md がそのまま読まれます。両方置きたいなら、CLAUDE.md の先頭に1行 @AGENTS.md と書いて取り込み、その下に Claude Code だけへの指示を足すのが公式のやり方です。シンボリックリンク（ln -s AGENTS.md CLAUDE.md）でもいいのですが、Windows で clone する人がいるなら、取り込みの方が安全です。

例として、このサイト（kiji-site）に置くとしたら、という AGENTS.md を書いてみます。3言語のページを Python の1ファイルで生成して、Cloudflare Pages で公開している小さなリポジトリです。このブログを AI と一緒に作ってきたなかで、毎回説明していたことと一度やりかけた失敗だけを残しました。

逆に、書いていないことも大事です。「Python で書かれている」「blog.html は記事の一覧」といったプロジェクトの紹介は入れていません。ファイルを開けば分かることは、エージェントが自分で読みます。30行ほどのこのファイルは、次の章で見る研究の結果とも合う大きさです。

ETH の論文は、効かない理由をこう説明しています。エージェントは書かれた指示に忠実に従い、テストや探索を増やす。その結果、課題そのものが余計に難しくなる。書けば書くほど良くなるわけではないのです。

ここから言えるのは、/init などで自動生成したファイルをそのまま置かないこと。生成したなら、人が読んで、コードを見れば分かる行を削ってから置く。それが今の時点でいちばん確かな使い方です。

3本目は個人の研究者による査読前の論文です。どの数字も、それぞれの実験条件のもとでのものです。

• 読めば分かること（プロジェクトの概要、使っている言語、フォルダ構成）── これはもう今の時点で要りません。研究でも役に立たないと出ています
• 調べれば分かること（ビルドやテストのコマンド、ローカルでの動かし方）── モデルが賢く、速く、安くなるほど、自分で探す手間は気にならなくなります。書く意味は「時間とお金の節約」だけになっていきます
• どこにも書かれていない意思（なぜこうしたのか、何をしてはいけないのか、誰が決めるのか）── これはコードや履歴をどれだけ読んでも出てきません。賢さの問題ではなく、情報がそこにないからです

人に置き換えると分かりやすいでしょう。どんなに優秀なエンジニアでも、転職した初日に「本番のデータベースは金曜に触らない」「このテーブルの変更は経理の承認が要る」ことは知りません。優秀な人ほど、そういう約束を最初に聞きに来ます。

変わっていくのは、形です。エージェントが自分で気づいたことをメモに残す仕組み（Claude Code の自動メモリなど）、必要なときだけ読み込まれる手順書（スキル）、強制力のある仕組み（フックや CI）がすでにあり、AGENTS.md 1枚に全部を書く必要は減っています。それでも、人が決めたことを、人が書いて、人も AI も同じものを読む場所は残るはずです。README が要らなくならないのと、同じ理由で。

この章は、ここまでの事実をもとにした筆者の見立てです。