AGENTS.mdとは？30分で自分用のファイルを書く方法

バイブコーディングとエージェント活用に関する実践資料：Ailootのドキュメント。

AGENTS.mdを一段落で説明すると#

以下では、agents.md、OpenAI Codexのドキュメント、JetBrains Junie、Cursor Rules Docs、GitHub Copilot Coding Agentの変更履歴、Linux FoundationによるAgentic AI Foundationの発表をもとに、この形式を解説します。数値と機能はすべて2026年5月30日時点のもので、Claude CodeにおけるAGENTS.mdのサポートについてはAnthropicのドキュメントに基づき、2026年9月24日の更新を反映しています。

市場にあるツール群が何なのか、なぜ共通ファイルが必要なのか分からない場合は、まずガイド「2026年に何でコーディングする？Claude CodeからAntigravityまで、8つのAIツール」をお読みください。この記事では、AGENTS.mdの形式と、30分で自分用のファイルを書く方法に絞って解説します。

AGENTS.mdとは何か、どこから来たのか？#

以前は、AIツールごとに独自のルールファイルがありました。AnthropicにはCLAUDE.md、Cursorには.cursorrules、GitHubには.github/copilot-instructions.md、Aiderには.aider.conf.yml、JetBrainsには.junie/guidelines.mdがありました。チームで3種類のエージェントを使っていたら、同じ内容のファイルを3つ並行して管理することになり、1週間もすれば内容が食い違っていました。

最初にこの状況にうんざりしたのがOpenAIでした。2025年8月、同社はCodex CLIを公開すると同時に、オープン形式としてagents.mdを立ち上げました。サイトにはこうあります。

「AGENTS.mdはエージェント向けのREADMEだと考えてください。」

（agents.md、英語からの翻訳）

要点は、AGENTS.mdがREADMEを補うことです。READMEは人向けに「このプロジェクトは何か、ローカルでどう実行するか、どう貢献するか」を説明します。AGENTS.mdはエージェント向けで、正確なシェルコマンド、検証可能な「完了」基準、「ここには絶対に触れない」といった境界を示します。

サイトにはこうあります。

「AGENTS.mdはREADMEを補うものです。READMEに入れると煩雑になる、あるいは人間の貢献者には不要でもエージェントには必要な、ビルド手順、テスト、規約などの追加情報、ときには詳細な情報を記載します。」

（agents.md、英語からの翻訳）

2025年9月までに、GitHub Copilot Coding Agentがこの形式をサポートしました（変更履歴、2025年8月28日）。12月までにはCursor、Junie、Gemini CLI、Aiderなど、さらに10を超えるツールが加わりました。2025年12月9日、Linux FoundationはAgentic AI Foundation（AAIF）を設立しました。創設プロジェクトはOpenAIのAGENTS.md、AnthropicのMCP、Blockのgooseです。創設メンバーはAWS、Anthropic、Block、Bloomberg、Cloudflare、Google、Microsoft、OpenAIでした。2026年2月24日までに、146の組織が財団に参加し、Red Hat、ServiceNow、Akamai、Lenovo、JPMorgan Chase、Huawei、UiPath、Hitachiなどが含まれていました。

その時点で、AGENTS.mdは「またOpenAIが作ったもの」ではなく、事実上の標準になりました。

AGENTS.mdを読むAIエージェント、読まないAIエージェント#

2026年5月30日時点のサポート一覧。Claude Codeの行は2026年9月24日に更新しています。

大手の中で最後に加わったのはAnthropicでした。2025年8月、公式のanthropics/claude-codeリポジトリに、AGENTS.mdのサポートを求めるissue #6235が立てられました。

issueは1年近くオープンのままで、2026年8月17日にクローズされました。AGENTS.mdに対応したバージョン2.1.277は、9月18日にリリースされました。Anthropicの仕様では、CLAUDE.mdが優先され、作業フォルダーまたは親フォルダーにCLAUDE.mdがない場合にAGENTS.mdが読み取られます。ドキュメントによると、次のように動作します。

注意点として、個人用のCLAUDE.local.mdも対象になり、これがあるとClaude CodeはAGENTS.mdを読み取らなくなります。この動作は/configの「Project instructions」で変更でき、たとえばClaude Codeに両方のファイルを同時に読み取らせることもできます。2.1.277より古いバージョンではAGENTS.mdは自動で読み込まれませんが、CLAUDE.mdに@AGENTS.mdという行を入れる方法は引き続き使えます。

AGENTS.mdはCLAUDE.mdや.cursorrulesとどう違うのか？#

2026年5月30日時点の4形式の比較：

AGENTS.mdには共通のプロジェクト指示を置けますが、各クライアントの読み込み経路や個人設定は別に設定する必要があります。Claude CodeにはCLAUDE.local.mdがあり、Cursorにはユーザー用のローカル.mdcファイルがあります。AGENTS.md単体では個人設定を扱えないため、他のファイルと組み合わせるか、gitignore対象のセクションに個人ルールを書くことをチームで合意する必要があります。

もう1つ重要なのがモノレポです。CodexとCursorでは「最も近いAGENTS.mdが優先される」というルールが使われています。

「モノレポでは、各パッケージに個別のAGENTS.mdを置いてください。エージェントはディレクトリツリー内で最も近いファイルを自動的に読み取り、最も近いファイルが優先されます。」

（agents.md、英語からの翻訳）

agents.mdによると、OpenAIの主要なモノレポには、サブパッケージごとに88個のAGENTS.mdがあります。モノレポで作業する場合は、ルートに全体ルールを置き、サブフォルダーには個別のルールを配置します。

AGENTS.mdには何を書くべきか？#

agents.mdのサイトでは「Markdownなら何でもよい」という柔軟な形式を提示しています。しかし、実際に使われている良質なファイルの80%には、同じ8つのセクションがあります。基本ルールは、各項目を正確なコマンドか具体例にすること。「きれいなコードを書く」のような抽象的な考え方は、エージェントに無視されます。

1. プロジェクトの概要 — 2～3行で、プロジェクトの内容、対象ユーザー、主な目的を書く。マーケティング文句は不要。例：「有料ワークショップへの参加を案内するTelegramボット。スタック：Next.js 14、Prisma、PostgreSQL。purchasesに新しいレコードが追加されると起動する。」
2. セットアップコマンド — ローカルで実行する正確なシェルコマンドを書く。npm install、npm run dev、npm run build。「通常はこうしています」ではいけない。
3. コードスタイル／規約 — 「きれいに書く」ではなく、具体的なルールと例を書く。例：「TypeScriptのstrictモード、シングルクォート、default exportなし、コンポーネント名はPascalCase、フック名はuseで始める。」
4. 開発環境のヒント — 重要なものの場所を書く。.envに必要な変数、シークレットの保存先、使用中のポート、ローカルDBの使い方。
5. テスト手順 — 特定のテストの実行方法と、何をもって「成功」とするかを書く。例：npm test -- --testPathPattern=user-auth。すべてのテストが成功すること。
6. PR／コミットのガイドライン — コミットメッセージの形式、PR前のチェックリスト（テスト、リンター、ドキュメント）、承認者を書く。
7. セキュリティ上の注意 — 絶対にしてはいけないことを書く。「.envをコミットしない。シークレットはVaultだけに保存する。ユーザーの個人情報をログに出さない。」
8. 境界／絶対にしないこと — 禁止事項に代替手段を添える。「mainにgit push --forceしない。ロールバックが必要なら、機能ブランチでgit revertまたはgit resetを使う。」

各セクションでは「考え方よりコマンド」という原則を使います。エージェントは「マイグレーションに注意する」を無視します。「alembic upgrade headの前にalembic checkを実行する。エラーが出たら、マイグレーションを適用せず、私に確認する」なら従います。

すぐに使えるAGENTS.mdテンプレート（コピーして調整）#

# AGENTS.md

## Project overview

<project-name> - <one phrase describing its purpose>.
Stack: <Next.js / Python / Go / ...>.
Main entities: <users, orders, posts ...>.
Details for people are in README.md.

## Setup commands

```bash
# first install
npm install
cp .env.example .env  # then fill in manually; see list below

# run
npm run dev           # dev server on :3000
npm run build         # production build
npm run start         # run production build
```

## Dev environment

- Node 20+ (via nvm: `nvm use 20`)
- PostgreSQL 16 locally on :5432 (`docker-compose up postgres`)
- Redis is optional, needed only for queues (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Never read the entire `.env` file. If you need one variable: `grep "^VAR=" .env`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons (unless ESLint requires them)
- Imports: external first, then internal via `@/`, then relative
- Components in PascalCase; hooks start with `use`
- No `any` without an explicit comment explaining “why it can’t be typed”

Example of a good module:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Testing

```bash
npm test                                # all tests
npm test -- --testPathPattern=auth      # auth only
npm test -- --watch                     # watch mode
```

All tests must pass (be green) before committing. If a test is red, don’t commit; ask me what to do.

## Pull request guidelines

- Commit format: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Before PR: `npm run build && npm test && npm run lint`
- PR description = what changes, why, and how to test
- Don’t approve your own PR—always wait for human review

## Security

- Secrets only in `.env` and Vault, never in code
- Don’t log personal data (email, phone, name)
- When working with the production DB, use read-only queries only unless explicitly authorized
- Don’t hardcode external service API keys (Stripe, OpenAI) in tests

## Never do this

- Don’t `git push --force` to main. If you need to roll back, use `git revert` or open a new PR
- Don’t run DB migrations without `alembic check` (or the equivalent in your ORM)
- Don’t use `npm install -g` or `sudo` for project dependencies
- Don’t add dependencies without approval (especially heavy ones: webpack plugins, ORM)

テンプレートは平均して80～120行です。150行を超える場合は、整理が必要なサインです。内容をdocs/に移す、リンクする、または1行に圧縮することを検討してください。実際には、100～150行のファイルが最も効果的で、それを超えると品質向上が頭打ちになります。

AGENTS.mdを本当に役立つものにする5つのルール#

1. 考え方よりコマンド。 エージェントは「マイグレーションに注意する」を理解しません。alembic upgrade headの前にalembic checkを実行する、という指示には従います。エージェントが扱うのは気分ではなく、コマンドと条件です。重要なルールはすべて「Xを実行し、そうでなければY」と表現します。

2. 代替手段を伴う禁止事項。 単に「強制プッシュしない」と書いても、エージェントは2～3回プロンプトを受け取るうちに無視するようになります。「Xをしない。代わりにYをする」という組み合わせが有効です。例：「mainにgit push --forceしない。ロールバックが必要なら、git revertを使うか、新しいPRを開く。」

3. 唯一の信頼できる情報源を設ける。 ルートのAGENTS.mdをプロジェクト全体の信頼できる情報源にします。モノレポの場合は、サブフォルダーにネストしたAGENTS.mdを置き、「最も近いものを優先する」ルールに従います。互いに矛盾するファイルを並行して置いてはいけません。

4. 検証可能な「完了」基準。 「テストに合格すること」は役に立ちません。正確な基準は、「npm testの終了コードが0で、標準出力にFAILが出ないこと」です。「コードをきれいにする」も役に立ちません。正確な基準は、「警告なしでnpm run lintが成功すること」です。「完了」の意味をエージェントが理解するには、条件を明示する必要があります。

5. 150行未満のファイル。 150行を超えると、指標が悪化し始めます。エージェントが読解により多くのコンテキストを費やし、重要なルールを見落とすためです。収まらない場合は、詳細をdocs/architecture.mdに移してAGENTS.mdからリンクし、ファイルにはコマンドと境界だけを残します。

AGENTS.mdを役立たずにする10の間違い#

1. コマンドのないあいまいなルール。 エージェントは「マイグレーションに注意する」を無視します。具体的なコマンドと条件がある場合だけ機能します。「alembic upgrade headの前にalembic checkを実行する。エラーがあればマイグレーションを適用せず、私に確認する。」

2. 「クリーンコード」。 役に立たない表現です。具体的なパターンに置き換えます。「フックを使った関数コンポーネントを使う。例：function LoginForm() { const [email, setEmail] = useState(''); ... }」

3. 構成のない文章。 AGENTS.mdが見出しのない文章で300行あると、エージェントは無関係な箇所を読むのに80Kのコンテキストトークンを費やし、重要な点を見落とします。H2／H3見出し、短いセクション、箇条書きを使いましょう。

4. 150行を超えるファイル。 このしきい値を超えると品質指標が低下します。メインファイルと、docs/内の詳細へのリンクに分けます。

5. 代替手段のない30件以上の禁止事項。 「Xをするな、Yをするな」と並べるだけで「代わりにZをする」と説明しないファイルでは、エージェントは手探りになります。

6. README.mdとの重複。 READMEにすでに「インストールと実行方法」を書いているなら、AGENTS.mdにコピーしないでください。代わりにREADMEを参照し、人間の貢献者には不要でもエージェントには必要なことをAGENTS.mdに記載します。

7. シークレットのハードコード。 AGENTS.mdはGitで公開される可能性があります。実際のAPIキー、トークン、パスワードを書いてはいけません。シークレットの保存先だけを記載します。「Vaultを参照：secret/staging/db。」

8. 優先順位のない矛盾。 「迅速に進める」ことと「テストカバレッジを90%に保つ」ことだけが書かれていると、エージェントはどちらを選ぶべきか分かりません。優先順位を明示します。「まずテストカバレッジ80%以上を守り、その後で速度を優先する。両者が衝突した場合はテストを優先する。」

9. 古いドキュメント。 実態はすでにWebSocketなのに、アーキテクチャの説明にはRESTとポーリングと書かれている場合です。エージェントは古い説明に従って、アーキテクチャを壊します。ルール：アーキテクチャが変わったら、同じPRでAGENTS.mdも更新します。

10. 単純な作業に対する過剰なアーキテクチャ説明。 設定ファイルの2行を変える依頼に、エージェントが14個のマイクロサービスの全体像を読む必要はありません。詳細なアーキテクチャ情報はdocs/architecture.mdに移し、AGENTS.mdには「アーキテクチャに関わる作業ではdocs/architecture.mdを読むこと」とだけ記載します。

2,500を超えるAGENTS.mdリポジトリに関するGitHub Blogの調査は、主な結論を次のように述べています。

「ほとんどのエージェント用ファイルは一般論に偏っているため失敗します。『あなたは親切なコーディングアシスタントです』という指示は機能しません。」

（GitHub Blog、英語からの翻訳）

1つのリポジトリでAGENTS.mdとCLAUDE.mdを共存させる方法#

実務上の主な問題は、内容を重複させずに両方のファイルをどう共存させるかです。3つのケースがあります。

ケース1：Claude Codeのみ。 CLAUDE.mdを使い、Claude Codeのすべての機能を利用します。ユーザー向けの指示には~/.claude/CLAUDE.md、プロジェクトにはCLAUDE.md、個人設定にはCLAUDE.local.md、他のファイルの読み込みには@import、専門スキルには.claude/skills/を使います。AGENTS.mdは不要です。

ケース2：複数のコーディングクライアント。 共通ルールをAGENTS.mdにまとめ、各クライアントを個別に接続・検証します。Gemini CLIではコンテキストのファイル名を設定でき、Aiderではread設定でファイルを読み込めます。これは明示的な読み込みであり、同じ自動検出ではありません。

安全なテスト用リポジトリで新しいセッションを始め、「テストの返答にinstructions-loadedという印を含める」などの無害で固有の指示を加えます。返答に加えて、クライアントが公式に用意する読み込み済みファイルの表示やログも確認してください。実際に使うクライアントとバージョンごとに繰り返します。モデルが「読みました」と答えるだけでは独立した証拠になりません。1つで成功しても、ほかのツールすべての対応を証明したことにはなりません。

ケース3：混在チーム（Claude Codeとその他のツール）。 2026年で最も一般的な構成です。解決策は、AGENTS.mdを主ファイルにすることです。Claude Code専用のルールがなければ、CLAUDE.mdは作らないでください。バージョン2.1.277以降、プロジェクトにCLAUDE.mdがなければ、Claude CodeはAGENTS.mdを読み取ります。そのようなルールがあれば、CLAUDE.mdをシンボリックリンクにするか、@AGENTS.mdをインポートする短いラッパーにします。

どちらのファイルも、変更前に内容を確認してバックアップします。両方ある場合は、矛盾しない共通指示をAGENTS.mdに統合し、Claude固有の指示と@AGENTS.mdのインポートをCLAUDE.mdに残します。既存のシンボリックリンクは置き換えずに保持してください。

通常ファイルのCLAUDE.mdで、AGENTS.mdがない場合だけ、次のmacOS/Linux用ガードを使えます。対象やシンボリックリンクがすでにあれば上書きしません。

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
  printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2
fi

名前変更が成功すると、CLAUDE.mdはAGENTS.mdへのシンボリックリンクになります。

Windowsでは、シンボリックリンクの作成に開発者モード（または管理者権限）が必要で、チーム全体で使うには不便なことがあります。代わりに、AGENTS.mdを読み込む短いCLAUDE.mdを作成できます。

# CLAUDE.md

@AGENTS.md

## Claude Code specific

- Use .claude/skills/ for specialized prompts
- When working with Skills, consult .claude/skills/INDEX.md
- Use Plan Mode before major changes (Shift+Tab)

Claude Codeでは、この構文で1行を使ってAGENTS.mdを読み込み、その下にClaude Code固有の追加事項を記載できます。後でAGENTS.mdを削除したい場合は、インポート行を削除するだけです。Claude Codeのドキュメントによると、AGENTS.mdを自動で読み取る場合でも同じファイルを二重に読み込むことはありません。

2026年のマルチツールチームにおける標準的な構成：

repo-root/
├── AGENTS.md                              # 信頼できる情報源、≤150行
├── CLAUDE.md                              # Claude専用ルールがある場合のみ：シンボリックリンク → AGENTS.md、または@AGENTS.md + 追加ルール
├── .cursor/rules/                         # Cursor専用の個別ルール
├── .github/copilot-instructions.md        # 使う場合は「AGENTS.mdを参照」
└── docs/architecture.md                   # AGENTS.mdから参照する詳細なアーキテクチャ情報

CLAUDE.mdの詳細は、ガイド「CLAUDE.mdを正しく設定する方法」をお読みください。エージェントに大きな指示ファイルが必要な理由については、「コンテキストエンジニアリングとは何か」をお読みください。

2026年に何が変わったのか？AAIFがAGENTS.mdをLinux Foundationに移管した理由#

2026年5月のAIコーディングにおける主な政治的動きは、新しいモデルのリリースではなく、形式の統合でした。以前はベンダーごとに独自のルールファイルがあり、ベンダーには便利でも、複数ツールを使うチームにとっては面倒でした。

2025年12月9日付の発表で、Linux Foundationは3つの形式を傘下に置くAgentic AI Foundationの設立を発表しました。

• AGENTS.md（OpenAI）— エージェント向け指示ファイルの形式
• Model Context Protocol（MCP）（Anthropic）— 外部ツールをエージェントに接続するためのプロトコル
• goose（Block）— オープンソースのエージェントフレームワーク

Linux Foundationのプレスリリースより：

「これらのプロジェクトをAAIFの傘下にまとめることで、オープンなガバナンスだけがもたらす透明性と安定性を備えた発展が可能になります。」

（Linux Foundationの発表、2025年12月9日、英語からの翻訳）

2026年2月24日までに、146の組織がAAIFに参加していました（2か月で97の新規メンバー）。新たなGoldメンバーにはRed Hat、ServiceNow、Akamai、Lenovo、JPMorgan Chase、Huawei、Hitachi、UiPath、American Express、Autodeskが含まれます。AnthropicはMCPを推進するPlatinumメンバーです。OpenAIはAGENTS.mdを推進するPlatinumメンバーです。Blockはgooseを擁するPlatinumメンバーです。

これにより、AGENTS.mdの位置づけは「OpenAIの形式」から業界標準へと変わります。2026年春のClaude Codeはまだ対応していませんでしたが、9月にはバージョン2.1.277でAGENTS.mdを自動で読み取れるようになりました。CLAUDE.mdはなくなっておらず、プロジェクト内にあればデフォルトで引き続き優先されます。

まず共通のプロジェクトルールをAGENTS.mdに置き、実際に使うクライアントが必要とするインポート、ラッパー、明示的なread設定を組み合わせます。Claude Codeでは、インストール済みバージョンと指示ファイルの優先順位を確認してから、CLAUDE.mdのインポートやシンボリックリンクが必要か判断してください。各クライアントで読み込みを検証します。ここでは対応率の数値は実証していません。

次にすること#

AGENTS.mdは「エージェントと合意し、予測どおりに動かす方法」における最初の構成要素です。次は、プロジェクトの知識フォルダーという2つ目の構成要素です。そこにはビジネスの背景情報、対象者、製品、価格を記載します。3つ目の構成要素はコンテキストエンジニアリングで、各ステップでエージェントがどのファイルを見るか、セッション間で状態をどう保持するか、異なるモデルをどう切り替えるかなど、すべてを結び付けます。

実践資料：Ailootのドキュメント。

その他の資料とツール：Ailoot。