【2026年6月最新】agents.mdとは？CLAUDE.mdとの違い・書き方・導入手順を実例付きで徹底解説

01 WHAT IS AGENTS MD agents.mdとは何か ── AI専用の「プロジェクト指示書」 AIエージェントのための共通プロジェクト指示書

agents.mdを一言で表すと、「AIに渡すプロジェクトの取扱説明書」です。人間がREADME.mdを読んでプロジェクトの概要を把握するように、AIエージェントはagents.mdを読んでコーディング規約・テスト手順・禁止事項を把握します。

従来、AIエージェントへの指示はチャット上でその都度伝えるか、各ツール専用の設定ファイル（.cursorrules、CLAUDE.mdなど）に書くしかありませんでした。agents.mdは「ツールに依存しない共通フォーマット」としてこれを解決しようとしています。

agents.mdが解決する問題は、大きく次の3つです。

02 WHY NOW なぜ今agents.mdが必要なのか？3つの背景 AIコーディングエージェント時代の課題

agents.mdが注目される背景には、2025〜2026年のAI開発環境の急速な変化があります。

背景①：AIコーディングエージェントの爆発的増加

2025年後半から、Cursor、GitHub Copilot Agent、Claude Code、Devin、Aider、Windsurf、Clineなど、自律的にコードを書くAIツールが一気に普及しました。1つのプロジェクトで複数のAIエージェントを使い分けるケースも珍しくありません。

背景②：「指示の属人化」による品質のバラつき

チームでAIエージェントを使う場合、各メンバーがチャットで個別に指示を出すと、コーディング規約の解釈やテスト方針にブレが生じます。ある人は「TypeScript strictモード」を前提にAIを動かし、別の人はanyを許容する ── こうした不統一がバグの温床になります。

背景③：ベンダー固有フォーマットの乱立

現状、各ツールは独自の設定ファイルを持っています。

ツール	設定ファイル	特徴
Cursor	.cursorrules	Cursor専用。他ツールは読めない
Claude Code	CLAUDE.md	実行環境と一体化。3階層で継承
GitHub Copilot	.github/copilot-instructions.md	GitHub専用ディレクトリ配置
Windsurf	.windsurfrules	Windsurf専用
agents.md	AGENTS.md	ベンダー非依存の共通標準を目指す

03 STRUCTURE agents.mdの基本構造と書き方【実例コード付き】 最小構成テンプレートから拡張まで

agents.mdの書き方にはまだ厳密な「公式仕様」はありませんが、Agentic AI Foundationが推奨する基本構造があります。

最小構成テンプレート ── まず5セクションから

# AGENTS.md

## Project overview
- TypeScript + Next.js 14 モノレポ
- Frontend: Next.js (App Router) / Backend: Hono
- DB: PostgreSQL + Drizzle ORM

## Setup commands
```bash
pnpm install
pnpm dev        # 開発サーバー起動
pnpm test       # テスト実行
pnpm lint       # Lint実行
```

## Code style
- Formatter: Prettier (設定は .prettierrc)
- Linter: ESLint + @typescript-eslint
- TypeScript strict モード必須
- 変数名はcamelCase、コンポーネントはPascalCase

## Testing
- テストフレームワーク: Vitest
- テストファイル: `*.test.ts` を同階層に配置
- PR前に `pnpm test` が全パスすること

## PR guidelines
- タイトル形式: `feat:` / `fix:` / `chore:` プレフィクス
- 1 PR = 1機能（巨大PRは分割）
- セルフレビュー済みであること

実践的な拡張セクション

プロジェクトが大きくなると、以下のセクションを追加するのが効果的です。

## Architecture
- /apps/web — Next.jsフロントエンド
- /apps/api — Honoバックエンド
- /packages/ui — 共通UIコンポーネント
- /packages/db — Drizzle スキーマ+マイグレーション

## Forbidden patterns
- `any` 型の使用禁止（unknownを使う）
- console.log は本番コードに残さない
- 直接のDOM操作禁止（React経由のみ）

## Environment variables
- `.env.example` を参照（秘密情報は含まない）
- DB_URL, NEXT_PUBLIC_API_URL が必須

## Deployment
- main ブランチ = 本番自動デプロイ
- develop ブランチ = ステージング
- feature/* → develop へのPRでレビュー

モノレポでの配置戦略

モノレポ構成では、ルートのAGENTS.mdに全体方針を書き、各サブディレクトリに固有ルールを追加配置します。AIエージェントは「一番近いAGENTS.mdから優先的に読む」のが一般的な挙動です。

ルートには「全チーム共通のルール」、サブディレクトリには「そのパッケージ固有の追加ルール」を書きます。重複を避けつつ、コンテキストに応じた指示を出せるのがメリットです。

04 ROLE DIFF README.md・CONTRIBUTING.md・agents.mdの役割の違い 3つのドキュメントファイルの棲み分け

agents.mdの位置づけを理解するには、既存のドキュメントファイルとの違いを明確にすることが大切です。

ファイル	対象読者	目的	書き方の特徴
README.md	人間（ユーザー・新規メンバー）	プロジェクトの概要説明	説明的な文章、スクショ付き
CONTRIBUTING.md	人間（コントリビューター）	貢献のルール・手順	PRテンプレ、ブランチ命名規則
AGENTS.md	AIエージェント	AIへのプロジェクト指示書	実行可能コマンド、断定形

よくある疑問として「README.mdにAI向け情報も全部書けばいいのでは？」というものがあります。結論から言うと、規模が小さいプロジェクトではそれでも問題ありません。しかし、チーム開発やモノレポでは以下の問題が出てきます。

05 COMPARISON agents.md vs CLAUDE.md vs .cursorrules 徹底比較 共通標準 vs 専用最適化のトレードオフ

ここからが本記事の核心です。agents.mdは「共通標準」を謳っていますが、実際にはClaude Code（CLAUDE.md）やCursor（.cursorrules）の専用フォーマットの方が高機能なケースがあります。

比較項目	agents.md	CLAUDE.md	.cursorrules
ベンダー依存	なし（共通標準）	Claude Code専用	Cursor専用
階層構造	ディレクトリ単位で配置可	3階層（ユーザー→プロジェクト→サブ）	プロジェクトルートのみ
実行環境との統合	読み取り専用（指示のみ）	Claude Codeが直接実行	Cursorが参照して生成
シェルコマンド実行	ツール依存	CLIから直接実行可能	ターミナル連携
MCP連携	標準的にサポート	ネイティブ統合	プラグイン経由
フックシステム	なし	PreToolUse/PostToolUseフック	なし
学習曲線	低い（Markdown記述のみ）	中程度	低い

もちろん、チームで複数のAIツールを使っている場合はagents.mdに共通ルールを書き、各ツール固有の設定は専用ファイルに書く ── という「二層構成」も合理的です。ただし多くの場合、メインツールの専用設定に集中する方が費用対効果は高いのが現実です。

「実行環境との統合」が決定的な差を生む

agents.mdは基本的に「静的なテキストファイル」です。AIエージェントがそれを読んで指示に従うかどうかは、各ツールの実装次第です。一方、CLAUDE.mdはClaude Codeの実行エンジンとネイティブに統合されているため、以下のような動的な制御が可能です。

この「指示を書くだけでなく、指示の遵守を強制できる」点が、agents.mdとCLAUDE.mdの最大の違いです。agents.mdはあくまで「お願い」ですが、CLAUDE.mdのフックシステムは「強制」として機能します。

06 GENAI REAL DATA CLAUDE.mdが実務で最強な理由【GENAI社の実例】 実行環境と一体化した指示書の威力

ここでは、弊社（株式会社GENAI）がClaude Codeを全社導入して得た実運用データを公開します。CLAUDE.mdを活用した結果、以下の工数削減を実現しました。

業務	導入前	導入後	削減率
営業	週20時間	週2時間	90%
広告運用	週10時間	週1時間	90%
ブログ記事	1本8時間	1本1時間	87.5%
経理	月40時間	月5時間	87.5%
秘書業務	日2時間	日15分	87.5%

CLAUDE.mdの3階層構成の実例

Claude CodeのCLAUDE.mdは3つのレベルで設定を継承できます。これがagents.mdにはない大きな強みです。

# ① ユーザーレベル（~/.claude/CLAUDE.md）
# → 全プロジェクト共通。個人の作業スタイルを定義
- 日本語で応答する
- 結論ベースで短く答える
- 確認は最大1つ

# ② プロジェクトレベル（/project/CLAUDE.md）
# → リポジトリ固有のルール
- TypeScript strict必須
- テスト未通過のコミット禁止
- FTPデプロイは必ずバックアップ後

# ③ サブディレクトリ（/project/apps/api/CLAUDE.md）
# → パッケージ固有の追加指示
- API追加時はOpenAPI specも同時更新
- レスポンスは必ずZodでバリデーション

この3階層構成により、「全社共通ルール」「プロジェクト固有ルール」「モジュール固有ルール」を自然に分離・継承できます。agents.mdでも同様の配置は可能ですが、Claude Codeのように実行環境と連動して動的に適用される仕組みは備えていません。

CLAUDE.mdで実現した自動化の具体例

弊社ではCLAUDE.mdに書いたルールによって、以下のような業務が自動化されています。

業務	CLAUDE.mdに書いたルール	自動化された内容
ブログ記事投稿	WP REST APIの認証情報参照先、サムネイル生成ルール	記事執筆→サムネ生成→WP投稿→SEO設定まで一気通貫
LP制作	FTPデプロイ先、画像最適化基準、CTA統一テンプレ	HTML生成→画像生成→FTPアップロード→動作確認
経理仕訳	freee API認証、勘定科目マッピング	銀行明細取込→仕訳作成→freee登録
営業リサーチ	求人スキップ条件、企業調査手順	問い合わせ受信→企業リサーチ→Slack報告

これらの自動化はすべて、CLAUDE.mdに「何をどう処理するか」を記述することで実現しています。agents.mdではここまでの自動化は難しく、別途ワークフロー定義やスクリプトが必要になります。CLAUDE.mdはそれ自体が「業務マニュアル兼実行環境」として機能するのです。

07 SETUP GUIDE agents.mdの導入手順 ── 5ステップチェックリスト 最小構成から始める段階的アプローチ

agents.mdを導入する手順を5ステップで解説します。すでにCLAUDE.mdや.cursorrules を使っている場合は、既存の設定をベースにagents.mdへ統合するのが効率的です。

ステップ1：プロジェクトの「AIに守らせたいルール」を洗い出す

まずはチーム内で「AIエージェントに最低限守ってほしいこと」を書き出します。代表的な項目は以下です。

ステップ2：最小構成でAGENTS.mdを作成する

いきなり完璧を目指さず、先述の5セクション（Project overview / Setup commands / Code style / Testing / PR guidelines）から始めましょう。

ステップ3：コードレビューフローに組み込む

AGENTS.mdの変更は通常のコードと同様にPRレビューを通しましょう。AIへの指示は「コードの品質を左右するインフラ」です。無断変更が入ると、生成されるコードの品質が全体で変動するリスクがあります。

ステップ4：AIエージェントで動作確認する

作成したAGENTS.mdを実際にAIエージェントに読ませて、意図通りに動くか検証します。特に以下をチェックしてください。

ステップ5：定期的にアップデートする

プロジェクトの変化に合わせて四半期ごとにAGENTS.mdを見直しましょう。古い情報が残っていると、AIが誤った前提で動いてしまいます。

よくある失敗パターンと対策

agents.mdやCLAUDE.mdの導入でよくある失敗を3つ紹介します。事前に知っておけば回避できます。

失敗1：最初から完璧を目指して肥大化する

「あれもこれも書いておかなきゃ」と、最初から100行以上の巨大なagents.mdを作ってしまうケースです。AIエージェントはコンテキストウィンドウに限りがあるため、指示が多すぎると重要なルールが埋もれてしまいます。まずは20行以内の最小構成から始め、実際にAIが間違えた箇所だけを追記していくのがベストです。

失敗2：抽象的な指示を書いてしまう

「コードは読みやすく書いてください」のような抽象的な指示は、AIにとってほとんど意味がありません。「変数名はcamelCase」「関数の行数は30行以内」「Prettier の設定に従う」のように、具体的かつ検証可能な形で書きましょう。

失敗3：書いたまま放置する

プロジェクトは日々変化しますが、agents.mdは放っておくと陳腐化します。使わなくなったライブラリの記述や、変更されたブランチ戦略が残っていると、AIが古い情報に従って誤ったコードを生成します。四半期に一度のレビューサイクルを設けることを強く推奨します。

08 SECURITY セキュリティとガバナンス ── 安全に運用するための注意点 秘密情報・権限管理・CI連携

AIエージェントへの指示書を安全に運用するためのポイントを整理します。

秘密情報の取り扱い

環境変数や認証情報は .env ファイルで管理し、agents.mdには「.envを参照せよ」とだけ書きます。.env 自体は必ず .gitignore に含めましょう。

権限境界の明示

AIエージェントが操作してよい範囲を明示的に書きましょう。たとえば以下のような記述です。

## Permissions
- /src/ 以下のみ編集可
- /config/ は読み取り専用
- /scripts/deploy.sh は実行禁止
- データベースのDROP/TRUNCATE操作は禁止

CI/CDとの連携

AGENTS.mdの変更はCIパイプラインに含めることを推奨します。Lintチェック（agents.md自体のフォーマット検証）や、秘密情報のスキャン（git-secretsなど）を組み込むと安全性が高まります。

具体的なCI設定例として、GitHub Actionsでagents.mdの秘密情報混入チェックを行う方法を紹介します。

# .github/workflows/agents-md-check.yml
name: Check AGENTS.md
on:
  pull_request:
    paths: ['**/AGENTS.md', '**/CLAUDE.md']
jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Scan for secrets
        run: |
          # API キー・トークンのパターンを検出
          if grep -rEi '(api_key|secret|token|password)' AGENTS.md CLAUDE.md 2>/dev/null; then
            echo "ERROR: 秘密情報の疑いがあります"
            exit 1
          fi

このように、agents.mdやCLAUDE.mdの変更をPRレビュー+CIの二重チェックにかけることで、チーム全体の安全を担保できます。「AIへの指示書」はコードと同じレベルでガバナンスを効かせるべきです。

09 CONCLUSION まとめ ── agents.mdで「AIと協働する開発」を始めよう 用途に応じた最適な選択を

この記事のポイントを整理します。

弊社ではClaude Code + CLAUDE.mdの組み合わせで、営業・広告・ブログ・経理・秘書の5領域で87〜90%の工数削減を実現しています。AIエージェントの力を最大限引き出すために、まずは「AIへの指示書」を整備してみてください。

10 FAQ よくある質問

Q. agents.mdは必須ですか？

A. 必須ではありません。agents.mdがなくてもAIエージェントは動作します。ただし、指示書があるとコードの品質と一貫性が大幅に向上するため、チーム開発では強く推奨されます。

Q. agents.mdとCLAUDE.mdは両方置いても大丈夫ですか？

A. はい、共存可能です。Claude Codeは基本的にCLAUDE.mdを参照しますが、agents.mdも認識できます。ただし内容が矛盾しないよう注意してください。実務上は、メインツールの専用設定に集中するのが効率的です。

Q. agents.mdの最低限の内容は？

A. Project overview（2〜5行）とSetup commands（ビルド・テスト・Lint）の2セクションがあれば最小構成として成立します。ここから徐々にルールを追加していくのが推奨アプローチです。

Q. OSSリポジトリにもagents.mdを置くべきですか？

A. コントリビューターがAIエージェントを使う可能性がある場合は推奨されます。特にコーディング規約やPRルールを記載しておくと、AI経由のコントリビューションの品質が安定します。

Q. agents.mdの将来性はどう見ていますか？

A. Linux Foundation傘下のAAIFが標準化を推進しているため、数年以内に「とりあえず置いておく」レベルの標準になる可能性はあります。ただし現時点では、各ツール専用の設定ファイルの方が機能的に優れているため、「将来に備えてagents.mdも作っておく」程度のスタンスで十分です。

Q. agents.mdの適切な長さはどれくらいですか？

A. 20〜50行が最初の目安です。それ以上になる場合は、モノレポの各サブディレクトリにファイルを分割することを検討してください。AIエージェントのコンテキストウィンドウは有限なので、指示が長すぎると重要なルールが埋もれてしまいます。弊社のCLAUDE.mdは現在数百行ありますが、これは2年間の運用で「実際に起きた問題の対策」を積み重ねた結果です。

AIAI鬼管理

AI鬼管理へのお問い合わせ

この記事を読んで気になった方へ。
AI鬼管理の専門スタッフが、御社に最適な
業務自動化プランを無料でご提案します。

お客様情報

会社名・屋号*必須

会社名を入力してください

業種*必須 選択してください IT・ソフトウェア 製造業 建設・不動産 小売・EC 飲食・宿泊 医療・介護 教育・研修 士業・コンサル 人材・BPO その他

業種を選択してください

お名前*必須

お名前を入力してください

メールアドレス*必須

正しいメールアドレスを入力してください

電話番号任意

---

現在の課題について

現在感じている課題*必須

人手不足で業務が回らない 社長・経営者が現場を離れられない 定型業務に時間を取られている AIを導入したいが何から始めればいいかわからない 外注・人件費コストが高い 業務フローが属人化している 社員のITリテラシーにばらつきがある

1つ以上選択してください

効率化・自動化したい業務*必須

営業・顧客対応（CRM・メール等） 経理・請求書・入金管理 採用・人事・労務管理 マーケティング・SNS・広告運用 カスタマーサポート・問い合わせ対応 資料作成・レポート・議事録 データ入力・集計・分析 社内の情報共有・ナレッジ管理

1つ以上選択してください

上記業務に現在かけている月額コスト*必須 選択してください まだかけていない（これから検討） 〜10万円 10〜30万円 30〜50万円 50〜100万円 100万円以上 その他（自由入力）

月額コストを選択してください

その他、ご相談内容任意

---

面談日時の選択

ご希望の日時*必須

約1時間のオンライン面談（Google Meet）です

空き枠を取得中...

面談日時を選択してください

この内容で面談を予約する

予約確定後、Google Calendarの招待メールをお届けします。
しつこい営業は一切ございません。