AGENTS.mdとは？AIコーディングエージェントに渡す「プロジェクトの取扱説明書」を解説

はじめに

AIコーディングエージェントに実装を任せると、技術的には正しくても「このリポジトリのやり方」から外れることがあります。そこで使われるのが AGENTS.md です。
OpenAI の Codex ガイドは AGENTS.md を「Codex に追加の指示と文脈を与える」ためのファイルとして説明しており、AGENTS.md プロジェクトも「コーディングエージェントを導くためのシンプルでオープンな形式」と位置づけています（ OpenAI Codex Guide 、 AGENTS.md ）。
この記事では、開発者・テックリード向けに、AGENTS.md とは何か、なぜ必要か、何を書くとよいか、他の文脈ファイルとどう使い分けるかを、一次情報ベースでまとめます。

AGENTS.mdとは何か

AGENTS.md は、AI コーディングエージェント向けにプロジェクト固有の指示を書く Markdown ファイルです。README.md が人間向けの概要やセットアップ案内を担うのに対し、AGENTS.md はビルド手順、テスト方法、コード規約、変更してはいけない領域などをエージェントに渡すための場所として使われます。

README.mdとの違い

README.md と AGENTS.md は、似ているようで役割が違います。AGENTS.md の公式サイトは、README.md は人間向けであり、AGENTS.md は build steps、tests、conventions のような「エージェントには必要だが README に書くと重くなりやすい情報」を置く場所だと説明しています。

「AGENTS.md は AI チームメイト向けの README」と説明されることがありますが、これは比喩としてはかなり近い表現です。ただし実体としては、README の置き換えではなく、README を補完するエージェント向け文脈ファイルです。

形式は普通の Markdown

AGENTS.md は公式 FAQ では「標準的な Markdown であり、必須フィールドはない」と説明されており、YAML フロントマターや JSON スキーマは必須ではありません。

Are there required fields?
No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.

AGENTS.md FAQ

AGENTS.mdはどう広がったのか

AGENTS.md は 2025 年 8 月に OpenAI が公開しました。OpenAI は 2025 年 12 月 9 日、Linux Foundation 傘下の Agentic AI Foundation（AAIF）を共同設立し、AGENTS.md を寄贈すると発表しています。同じ発表の中で、AGENTS.md は 60,000 を超えるオープンソースプロジェクトやエージェント関連フレームワークに採用されていると説明されています（ OpenAI 、 AAIF ）。
また Linux Foundation は 2026 年 2 月 24 日の発表で、AAIF が 146 メンバーを擁するコミュニティになったと公表しました。少なくとも 2026 年 2 月時点では、AGENTS.md は単なる 1 社独自の慣習ではなく、AAIF 配下で管理されるオープン標準の 1 つとして扱われています（Linux Foundation）。

どのツールで使われているのか

一次情報で確認しやすい範囲でも、すでに複数の主要ツールが AGENTS.md を扱っています。

ここで重要なのは、「すべてのツールが完全に同じ仕様で読む」と早合点しないことです。AGENTS.md はオープン標準として広がっていますが、読み込み順序や周辺機能はツールごとの公式ドキュメントも確認したほうが安全です。

なぜAGENTS.mdが必要なのか

AGENTS.md が必要になる理由は、プロジェクト固有のルールの多くがコードを読むだけでは分からないからです。AGENTS.md の公式サイトも、README には人間向け情報が載り、エージェントが必要とする build steps、tests、conventions は別の置き場があったほうがよいと説明しています。
この点は GitHub の調査でも裏づけられています。GitHub Blog は 2,500 以上のリポジトリを分析し、効果的な AGENTS.md には「正確なセットアップコマンド」「検証手順」「リポジトリ構造」「開発環境」「プロジェクト固有パターン」「ガードレール」が共通していたと報告しています（GitHub Blog）。
要するに、良い AGENTS.md は抽象論を書く場所ではありません。「何のコマンドを打つべきか」「どのチェックを通すべきか」「どこは触ってよくてどこは危険か」を、エージェントが実行しやすい形で渡す場所です。

AGENTS.mdの仕様と配置ルール

どこに置くのか

OpenAI のガイドでは、Codex はリポジトリルートから現在の作業ディレクトリまで AGENTS.md を探し、近い場所の指示ほど優先度が高いと説明されています。AGENTS.md の FAQ も「編集対象に最も近い AGENTS.md が勝つ」と案内しています。

What if instructions conflict?
The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.

AGENTS.md FAQ

project/
├── AGENTS.md
├── frontend/
│   ├── AGENTS.md
│   └── src/
└── backend/
    └── AGENTS.md

この構成なら、ルートには共通ルール、frontend/AGENTS.md にはフロントエンド固有ルール、backend/AGENTS.md にはバックエンド固有ルールを書けます。モノレポや大規模リポジトリで特に有効です。

ツールごとに読み方は少し異なる

GitHub Copilot の docs では、リポジトリ内の複数の AGENTS.md を扱え、近いファイルがより強く効くと説明されています（GitHub Docs）。Gemini CLI も文脈ファイルを階層的に読み込み、AGENTS.md をファイル名候補に設定できます（Gemini CLI）。
つまり「ルート 1 枚だけ」という前提ではなく、親子ディレクトリで文脈を分ける設計はすでに複数ツールで現実的です。ただし、細かな優先順位や既定値はツール実装で差があり得るため、導入時は使うツールの公式 docs を確認してください。

長くしすぎない

AGENTS.md プロジェクトのリファレンス実装では、連結後の AGENTS.md に既定で 32 KiB のサイズ制限があり、設定で 65,520 bytes まで拡張できます（codex/GitHub）。
この数値をすべてのツールにそのまま当てはめるべきではありませんが、「短く具体的に保つべき」という方向性はかなり重要です。長い総論より、すぐ実行できるコマンドや、失敗しやすい注意点を優先したほうが役に立ちます。

AGENTS.mdに書くとよい6つの要素

GitHub Blog の 2,500 リポジトリ分析を、そのまま日本語に寄せて整理すると、次の 6 項目が中核になります（GitHub Blog）。

1. セットアップと実行コマンド

インストール、ビルド、開発サーバー起動、型チェック、リントなど、エージェントがまず使うコマンドを書きます。GitHub は「ツール名だけではなく、実際に打つコマンドをフラグ込みで書く」ことを勧めています。

## Setup commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Build: `pnpm build`
- Type check: `pnpm tsc --noEmit`

2. 検証手順と品質ゲート

テスト、リント、CI で最低限通すべきチェックを書きます。単体テストと統合テストが分かれているなら、その区別も書きます。

## Validation
- Unit tests: `pnpm test`
- Lint: `pnpm lint`
- Before finishing, run the checks relevant to the files you changed

3. リポジトリ構造

主要ディレクトリの役割を書きます。ファイル一覧を丸ごと貼る必要はありません。どの層に何があるか、どう切り分けるかが分かれば十分です。

## Repository structure
- `src/` - application code
- `tests/` - automated tests
- `docs/` - design notes and ADRs

4. 開発環境

使っているランタイム、パッケージマネージャ、ローカル起動に必要な前提をまとめます。ローカルで DB や外部サービスが要るなら、その前提もここに書きます。

## Development environment
- Node.js 22
- Package manager: pnpm
- Local env vars are documented in `.env.example`

5. プロジェクト固有のパターン

「このプロジェクトでは何が普通か」を書く項目です。命名規則、アーキテクチャ上の約束、既存の実装パターンなどがここに入ります。GitHub Blog も、抽象的な美文より「このコードベースでよく使うパターン」を見せるほうが有効だとしています。

## Project patterns
- Reuse helpers in `src/lib/` before adding a new utility
- Prefer existing API clients over raw fetch calls
- Keep feature logic inside `src/features/<name>/`

6. ガードレール

エージェントにどこまで自律的に進めてよいかを伝える項目です。GitHub Blog では、Always、Ask、Never のように分けて明示する例が紹介されています。

## Guardrails

### Always
- Use existing patterns before introducing new abstractions
- Add or update tests for changed behavior

### Ask first
- Adding dependencies
- Editing CI workflows
- Changing database schema

### Never
- Commit secrets
- Modify generated files by hand
- Force-push to the main branch

なお、コミットメッセージ形式や PR ルールのような運用ルールは、この「ガードレール」に含めて書くと整理しやすいです。

実践：最小限のAGENTS.mdテンプレート

最初から完璧な AGENTS.md を書く必要はありません。GitHub Blog の調査でも、まずは実行コマンドと検証手順を明確にすることが重要だと読み取れます。
以下は、6 項目を一通り押さえた最小限のテンプレート例です。

# Project Guidelines

## Setup commands
- Install: `<install command>`
- Dev: `<dev command>`
- Build: `<build command>`

## Validation
- Tests: `<test command>`
- Lint: `<lint command>`
- Run relevant checks before finishing

## Repository structure
- `src/` - application code
- `tests/` - automated tests
- `docs/` - project documentation

## Development environment
- Runtime: `<language/runtime version>`
- Package manager: `<package manager>`

## Project patterns
- Reuse existing utilities before adding new ones
- Follow the established module structure

## Guardrails

### Always
- Keep changes scoped to the requested task
- Update tests when behavior changes

### Ask first
- Adding dependencies
- Editing CI/CD configuration
- Changing schema or migrations

### Never
- Commit secrets
- Modify generated files manually
- Push directly to the protected branch

最初の 1 枚では、Setup commands と Validation だけでも十分に効果があります。エージェントが毎回そこで迷わなくなるからです。

AGENTS.mdを書くときのコツ

「長い総論を書くこと」ではなく「エージェントが次に取る行動を具体化すること」です。

具体的に書く

「きれいなコードを書いてください」ではなく、「pnpm lint を通す」「src/lib/ の既存ユーティリティを優先する」のように行動に落ちる形で書きます。GitHub Blog も、曖昧な原則より具体的なパターンやコマンドを示すほうがよいと勧めています。

説明より実例を優先する

コードスタイルやテスト方針は、長文で説明するより、実際のコマンドやディレクトリ名で示したほうが伝わります。AGENTS.md の公式サイトも、サンプルでは見出しと箇条書きで短く明示する構成を採っています。

リンターや CI と役割を分ける

AGENTS.md は「ルールを伝える」ための文書です。自動整形や静的解析で機械的に担保できることは、それらの設定ファイルに任せたほうが一貫します。AGENTS.md には「どのコマンドを実行すればそのルールを検証できるか」を書くほうが実務では有効です。

生きた文書として更新する

AGENTS.md の FAQ は、AGENTS.md を living documentation として扱うよう勧めています。同じ種類の失敗が繰り返されたら、その対策を AGENTS.md に追加する運用が自然です。

他の文脈ファイルとの関係

AGENTS.md が広がっている一方で、ツールごとに別名の文脈ファイルや別用途の設定ファイルもあります。ここは混同しやすいので、一次情報ベースで整理しておきます。

この表の根拠はそれぞれ次のとおりです。

複数ツールを併用する場合は、同じルールをあちこちに重複記載しないことが大切です。共通部分は AGENTS.md に寄せ、ツール固有の設定だけを CLAUDE.md や GEMINI.md、Copilot の各ファイルに分ける運用が管理しやすいでしょう。

まとめ

いかがでしたでしょうか。
まずはリポジトリルートに、ビルドコマンドとテストコマンドだけを書いた AGENTS.md を置くところから始めてみてください。そこからエージェントの失敗パターンに応じて追記していくほうが、最初から巨大な指示書を作るより現実的です。
エージェント関連の用語やツールの全体像については、以下の記事も参考にしてください。

生成AI活用支援サービスのご紹介

Tech Funでは、お客様のフェーズに合わせ、生成AI活用に向けた支援を3つのパックでご提供しています。

1. 無料診断パック：業務・プロセスの現状を無料で診断し、生成AI活用の可能性をレポートします。
2. 検証（PoC）パック：診断で有効性が確認された業務を対象に、プロトタイプ構築を支援します。
3. コンサルティングサービス：生成AI導入戦略の策定から運用体制構築までを包括的に支援します。

生成AIに限らず、Web・業務システム開発やインフラ設計など、技術領域を問わずご相談を承っています。「何から始めれば良いか分からない」という段階でも構いませんので、ぜひお気軽にお問い合わせください。

執筆・編集

Tech Fun Magazine R&Dチーム

Tech Funの生成AI研究に携わるエンジニアが、最新のAIモデル動向やプロンプト設計、実業務への応用手法など、生成AIに特化した知見を執筆・編集しています。
モデル評価や業務シナリオに応じたAI活用設計など、日々のR&D活動で得られる実践的なノウハウをわかりやすく紹介します。