📜すべてのエージェントを統べる、たった一つのファイル · AGENTS.md をマスターする

それが必要になる、まさにその瞬間

必要性が現れるのは、プロジェクトがルールを持ち、複数の人工の頭脳がそこを通り抜ける日だ。構築には Claude Code を使い、レビューには別のツールを使い、たまに何か単発の作業で Cursor や Copilot を開く、というケースかもしれない。あるいは明日、クレジット節約のためにエージェントを乗り換えるケース。そのすべてで、コードの中には存在しない知識がある。環境をどう起動するのか、どのコマンドでテストを走らせるのか、どのフォルダが神聖で触ってはいけないのか、保存のメッセージをどう書いてほしいのか。その知識は今、あなたの頭の中にしかない —— そして新しいエージェントはどれもゼロから始まり、そのことを何も知らない。

それが生まれる痛み · 蒸発してしまうコンテキスト

痛みは静かで、分割払いで支払われる。今日のAIとのセッションは、あなたのプロジェクトがどう動くのかを完璧に理解している。あなたが何時間もかけて説明したからだ。だがその知識はどこにも保存されない。会話を閉じた瞬間、蒸発する。明日、新しいセッションを開く —— あるいは支出を抑えるためにモデルを乗り換える —— と、またスタート地点に逆戻りだ。「テストはこのコマンドで走らせるって覚えておいて」、「決済のフォルダは触らないで」、「コミットはこのフォーマットで」と繰り返す。

なぜ起こるのか? どのエージェントも目隠しの状態で始動するからだ。見えるのはコードだけで、あなたのルールも習慣も見えない。そして各ツールはそれぞれの流儀で指示を保存していたので —— Claude はあるファイルに、Cursor は別のファイルに、Copilot はまた別のファイルに —— 同じ知識を三度も四度も書いて維持しなければならなかった。勝手に非同期化していくカオスだ。あるファイルでルールを変えても、他のファイルで変え忘れる。

AGENTS.md とは?(平たく言うと)

AGENTS.md はエージェントのための README だ。昔ながらの README が人間にプロジェクトの中身を伝えるように、AGENTS.md はあらゆるコードAIに、その中でどう振る舞うべきかを伝える。プロジェクトのルートに置くプレーンテキスト(Markdown)のファイルで、それだけ。変な設定なし、コードなし、儀式なし。

これを強力にするのはフォーマットではない —— それが今や25以上の異なるツールが読み込むオープン標準になったことだ。OpenAI Codex、Cursor、GitHub Copilot、Gemini CLI、Google Jules、Aider、Zed、Windsurf、Devin、JetBrains Junie、Warp、goose など。すでに6万以上のオープンソースプロジェクトが使っている。ルールを一度書けば、今日使うAIでも、明日使うAIでも機能する。一つのツールに縛られる暮らしから抜け出せる。

本当の解剖学 · 中に何が入るのか

ここが一番の朗報だ。厳格なフォーマットを覚える必要はない。AGENTS.md はごく普通の Markdown だ —— # で見出し、ハイフンでリスト、そしてテキスト。あの、コロンと波括弧だらけの技術的なヘッダー(プログラマーが YAML frontmatter と呼ぶもの)は付かない。そんなものは一切必須ではない。好きな名前のセクションで書き、エージェントは書かれたものを読む。以上。

とはいえ、良い AGENTS.md ならほぼ必ず含める五つのブロックがある —— それこそがセッション間で蒸発する知識そのものだからだ。仕事場マニュアルの五つの引き出しだと考えてほしい。

その習慣 · 一度書いて、生き続けさせる

この recurso は毎日実践する類のものではない —— 一度きちんとやって、たまに手を入れる類のものだ。ここでの継続性は頻度にはない。忘れてはいけない、具体的な二つの瞬間にある。

ほとんど誰も説明しない機微 · AGENTS.md vs CLAUDE.md vs .cursorrules

ここで人は混乱するので、はっきりさせよう。標準が存在する前は、各ツールが独自のルールファイルを発明していた。Claude Code は CLAUDE.md を読み、Cursor は .cursorrules を読み、といった具合だ。明白な問題:三つのツールを使うなら、同じ知識を持つ三つのファイルを維持し、勝手に非同期化していく。AGENTS.md はまさにその無秩序を終わらせるために生まれた:すべてが読む、たった一つの真実の源だ。

# CLAUDE.md

# プロジェクトのルールは AGENTS.md にある(唯一の源)。
# Claude Code はこのインポート行でそれらを読み込む:

@AGENTS.md

# この下は、他のエージェントには当てはまらない
# Claude Code 固有のことだけ(もし何かあれば)。

どちらをいつ使うか? 簡単だ:どのエージェントにも従ってほしいものはすべて AGENTS.md(ルールの95%)。ツール固有のファイル(CLAUDE.md、.cursorrules)は、そのツール専用のものだけに —— そのツールだけが理解するコマンド、そのツールにだけ効く設定。迷ったら AGENTS.md 行きだ。頭の中のルール:デフォルトで全員に向けて書く。例外として一つだけに向けて書く。

Point & counterpoint · specがすでに何を作るか言っているなら?

構築の前に仕様を書くという発想(何を構築してほしいか、その何)から来ているなら、AGENTS.md はそのペアのもう半分だ —— そして互いを踏まない、補完し合う。spec は何を構築するかを統べる:機能、目的、成果。AGENTS.md は、それを構築する間にどのエージェントもどう振る舞うかを統べる:どのコマンドで、どのルールで、何を触らないか。一方は建物の図面、もう一方は工事現場の安全規則。両方が要る。

マスタープロンプト · あなたの完璧な AGENTS.md を生成する

これが近道だ。ファイルを手で書く必要も、各セクションを考える必要もない。あなたのプロジェクトの中でこのプロンプトをコードエージェントに渡せば、実際のコードの組み立て方を見ながら、代わりに書き上げてくれる。あなたはレビューして調整するだけ。そのままコピーし、角括弧を知っていることで埋めて、働かせよう。

プロジェクトのルートに AGENTS.md ファイルを作りたい:AIコードツールが読み込むオープン標準(agents.md)の「エージェントのための README」だ。プレーンな Markdown で、YAML ヘッダーは付けない。私はプログラマーではないと想定して、平易な言葉で導いてほしい。

まず、私のプロジェクトを実際に EXPLORA(フォルダ構造、package.json またはそれに相当するもの、そしてどう構成されているかを調べて)して、何も捏造しないこと。それから、次のセクションを持つ AGENTS.md を、きれいな Markdown で書いてほしい:

1. プロジェクトの概要 — 何であり、どの技術を使っているか、2〜3文で(コードから推論する)。
2. 環境を整える — プロジェクトをゼロからインストールして起動する実際のコマンド。
3. どうテストするのか — テストとエラー/型チェックの正確なコマンド。どのエージェントも、作業を良しとする前に検証できるように。
4. スタイルのルール — コードの言語と、検出した規約(引用符、命名、フォーマット)。
5. コミットとPR — これが私のコミットメッセージのフォーマットだ:[記述する、あるいは持っていないなら言って、良いものを提案して]。
6. 境界線 · 触ってはいけないもの — 次の神聖なフォルダ/ファイルを、明示的な許可なしには INTOCABLES と印を付ける:[ここにデリケートなものを列挙:決済、シークレット、設定、マイグレーション… 持っているもの]。エージェントはそれらを変更する前に PARAR して尋ねるべきだと明確にする。

書くためのルール:
- 私のコードを見て検証できることだけを断言する。何か分からないなら、捏造せず [POR CONFIRMAR] というマーカーを置く。
- 簡潔で実行可能に、小説にはしない。エージェントは作業前に全部を読む。
- メインのツールがすでに独自のルールファイルを持っているなら(例えば CLAUDE.md)、内容を重複させない:そのファイルが一行で AGENTS.md をインポートするようにし、AGENTS.md を唯一の真実の源として残す。

終わったら、完全なファイルを見せて、各セクションに何を保存したかを一文で説明して、私がレビューできるように。

最も簡単な道 · チャット vs. 手作業

このシリーズ全体と同じく、これをやるやり方は二つあり、どちらも望まなければターミナルを触らせない。

手作業の道を行くなら、これがコピーして埋めるだけの最小テンプレートだ。好みに変えていい:必須のフォーマットはないことを思い出して。

# AGENTS.md

## プロジェクトの概要
[何であり、何で作られているか。2〜3文。]

## 環境を整える
[ゼロからインストールして起動するコマンド。]

## どうテストするのか
- テスト: [正確なコマンド]
- エラー/型のチェック: [正確なコマンド]
> 変更を完了とする前に、これを走らせて緑のままにしておくこと。

## スタイルのルール
[コードの言語、命名/フォーマットの規約。]

## コミットとプルリクエスト
[あなたのコミットメッセージのフォーマット。良い例を一つ。]

## 境界線 · 許可なく触るな
- [神聖なフォルダまたはファイル1 — なぜデリケートか]
- [神聖なフォルダまたはファイル2]
> これらのどれかに直面したら:変更する前に PARA して尋ねる。

黄金のルーティン · 持ち帰る要約