AGENTS.mdとは何ですか？

AGENTS.mdは、AIコーディングエージェントに機械可読なコンテキストを提供するベンダーニュートラルなマークダウンファイルです。ビルドコマンド、テスト手順、コーディング規約、プロジェクトアーキテクチャ、セキュリティ境界—AIエージェントがコードベースで効果的に作業するために必要なすべての情報を含みます。60,000以上のオープンソースプロジェクトが採用しています。

どのAIコーディングエージェントがAGENTS.mdをサポートしていますか？

AGENTS.mdはGitHub Copilot、OpenAI Codex、Cursor、Windsurf、Claude Code、Aider、Roo Code、Google Jules、Factory.ai Droids、Zedでサポートされています。CLAUDE.mdなどのエージェント固有ファイルと並行して機能し、マルチエージェントチームにとって最も安全な単一投資となります。

AGENTS.mdはCLAUDE.mdとどう違いますか？

CLAUDE.mdはClaude Code専用で、自動メモリやMCPサーバー統合などの機能を含みます。AGENTS.mdはベンダーニュートラルで、主要なすべてのAIコーディングエージェントで機能します。ほとんどのチームは両方を使用します—汎用規約にAGENTS.md、Claude固有の設定にCLAUDE.mdを使います。

モノレポでAGENTS.mdはどこに配置すべきですか？

ルートにグローバルルールを持つAGENTS.mdを配置し、チームまたはモジュール固有の規約用にサブディレクトリのAGENTS.mdファイルを追加します。最も近いファイルが優先されます。OpenAIはリポジトリ全体で約88のネストされたAGENTS.mdファイルを維持しています。

AGENTS.mdファイルはどのくらいの長さにすべきですか？

最小限から始めてください—コマンド、技術スタック、コードスタイル、境界をカバーする15-20分の投資。エージェントの間違いに基づいて反復します。包括的なファイルはエージェントの成功率を40-60%から85-90%に引き上げますが、長すぎるファイルはコンテキストトークンを無駄にします。

AGENTS.mdはREADME.mdを置き換えますか？

いいえ。README.mdは人間向け—プロジェクト概要、セットアップ手順、貢献ガイドライン。AGENTS.mdは機械消費用に最適化—正確なコマンド、具体的なコード例、明示的な境界。異なる対象読者にサービスを提供し、相互に補完し合います。

AGENTS.mdをどのように始めればよいですか？

リポジトリルートにAGENTS.mdというファイルを作成します。ビルド/テスト/リントコマンド、バージョン付きの技術スタック、1つのコードスタイル例、エージェントが決してやってはいけないことのリストを含む境界セクションを追加します。このガイドのテンプレートを出発点として使用し、エージェントが間違えた内容に基づいて洗練させてください。

AGENTS.mdガイド：AIコーディングエージェントのためのユニバーサル設定ファイル

昨日、エンタープライズチーム向けCLAUDE.mdガイドを公開しました。数時間のうちに3人から同じ質問がありました：「Claude Codeに全面採用していないチームについてはどうすれば？」

もっともなポイントです。一部のチームがGitHub Copilotを使い、他のチームがCursor、バックグラウンドタスクにCodex、複雑なリファクタリングにClaude Codeを使う組織—そしてそれはますます一般的です—どこでも機能するものが必要です。

それがAGENTS.mdです。

AGENTS.mdとは何か（そして何でないか）

AGENTS.mdは、AIコーディングエージェントにコードベースでどう作業すべきかを伝えるベンダーニュートラルなマークダウンファイルです。リポジトリのルート（またはスコープ付きルール用のサブディレクトリ）に配置され、初日に新しい開発者に伝えるのと同じ種類の情報を含みます：ビルドコマンド、テストプロトコル、コーディング規約、プロジェクトアーキテクチャ、明示的な境界です。

README.mdとの主な違い：人間向けではなく機械向けに構造化されていること。READMEが「ReactとTypeScriptを使用しています」と書くかもしれないのに対し、AGENTS.mdはこう書きます：

## Tech Stack
- React 18.3, TypeScript 5.4, Vite 5.2, Tailwind CSS 3.4

正確なバージョン。説明なし。エージェントはあなたの起源の物語を必要としません。

このフォーマットは実用的な問題から生まれました。AGENTS.mdの前、すべてのエージェントは独自の設定ファイルを持っていました—AiderはCONVENTIONS.mdを使用し、Roo Codeは.roomodesファイルを使用し、Clineは.clinerulesディレクトリを使用し、Claude CodeはCLAUDE.mdを使用していました。複数のエージェントを実行するチームは冗長で分岐した設定を維持していました。AGENTS.mdはこれを60,000以上のオープンソースプロジェクトが採用した単一の信頼できる情報源に統合します。

エンタープライズチームが注目すべき理由

数字が物語を語ります。GitHubは2,500以上のリポジトリを分析し、適切なガイダンスでエージェントの成功率が劇的に向上することを発見しました：

AGENTS.mdなし — 40-60%のタスク成功率
最小限のAGENTS.md — 60-70%の成功率
包括的なAGENTS.md — 85-90%の成功率

朝に5つのエージェントタスクをキューに入れるエンタープライズチーム（WorkOSチームがCodexで開拓したパターン）にとって、これは1日2回の失敗とゼロの差です。組織全体に掛け算すればROIは明らかです。

しかし、本当のエンタープライズ価値は単なる成功率ではありません。ツール間の標準化です。フロントエンドチームがCursorを使用し、プラットフォームチームがClaude Codeを使用し、DevOpsチームがCodexを試す場合、単一のAGENTS.mdがすべて同じ規約に従うことを保証します。一度書けば、すべてのエージェントが読みます。

主要エージェントがAGENTS.mdを使用する方法

すべてのエージェントがAGENTS.mdを同じように消費するわけではありません。違いを理解することは、どこでもうまく機能するファイルを書くのに役立ちます。

GitHub Copilot

CopilotはワークスペースルートとサブディレクトリからAGENTS.mdを自動発見します。GitHubのチームはCopilotがフォーマットをどう解釈するかを改善するために、その2,500以上のリポジトリを特別に分析しました。Copilotは.agent.mdファイル—特定のツールとロールを持つカスタムエージェントペルソナを定義するためのYAMLフロントマッター付きの別フォーマット—もサポートしています。

Cursor

CursorはAGENTS.mdを自動発見し、指示システムに取り込みます。設定不要—ファイルをリポジトリに置けばCursorが拾い上げます。シンプルで効果的です。

Windsurf

Windsurfが最も洗練された統合を持っています。AGENTS.mdを自動スコーピングを備えたRulesエンジンの一部として扱います：ルートファイルは常時オンのグローバルルールになり、サブディレクトリファイルは場所に基づいてglobパターンを自動適用します。Windsurfはワークスペース全体のすべてのAGENTS.mdファイルをスキャンします。

Claude Code

Claude CodeはネイティブのCLAUDE.mdフォーマットと並行してAGENTS.mdをサポートします。2つは相互に補完し合います—汎用規約にAGENTS.md、自動メモリ、MCPサーバー宣言、フック設定、Claude固有の最適化にCLAUDE.mdを使います。Claude Code Projectの解剖で取り上げた3層アーキテクチャです。

OpenAI Codex

Codexは起動時にAGENTS.mdを自動発見・ロードし、タスク実行中に頻繁にコマンドを参照します。ここでWorkOSのケーススタディが輝きます—チームは毎朝4-5のメンテナンスタスク（TypeScript修正、Webhook更新、認証移行）をCodexにキューに入れ、適切にスコープされた作業で85-90%の成功率を報告しています。

Aider

Aiderは既に--conventions-fileを介して規約ファイルをサポートしていました。AGENTS.mdが標準のデフォルトの場所となり、既存のCONVENTIONS.mdファイルも後方互換性のために機能し続けます。

その他

Roo Code、Google Jules、Factory.ai Droids、Zedはすべてさまざまな洗練度でAGENTS.mdをサポートしています。Factory.aiはディレクトリ全体の包括的な発見で主要なブリーフィングメカニズムとして使用しています。トレンドは明確です：AGENTS.mdはテーブルステークスになりつつあります。

すべてのAGENTS.mdに必要な6つの要素

GitHubの2,500以上のリポジトリの分析は、最も大きな違いを生む6つのコア領域を特定しました：

1. 実行可能なコマンド

これらを最初に配置してください。エージェントは常にそれらに手を伸ばします。

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test all: `pnpm test`
- Test single: `pnpm test -- --grep "test name"`
- Build: `pnpm build`
- Lint: `pnpm lint --fix`

2. テスト手順

テストの実行方法だけでなく、書き方も。どのフレームワーク、どのパターン、どこにあるか。

## Testing
- Framework: Vitest with React Testing Library
- Location: `__tests__/` directories adjacent to source
- Pattern: one test file per component, named `ComponentName.test.tsx`
- Run single file: `pnpm test src/components/__tests__/Button.test.tsx`

3. プロジェクトアーキテクチャ

簡潔な注釈付きのファイル構造。エージェントはこれを使用して不慣れなコードベースをナビゲートします。

## Architecture
- `src/api/` — .NET 8 Web API (Clean Architecture)
- `src/web/` — React 18 + TypeScript frontend
- `src/shared/` — Shared types and utilities
- `infra/` — Terraform modules and Bicep templates
- `scripts/` — CI/CD and automation scripts

4. コードスタイル（例付き）

抽象的なルールは伝わりません。具体的な例が伝わります。

## Code Style
- Use functional components with hooks (no class components)
- Prefer named exports over default exports
- Example:
  ```tsx
  export function UserCard({ name, role }: UserCardProps) {
    const [expanded, setExpanded] = useState(false);
    return (
      <Card onClick={() => setExpanded(!expanded)}>
        <h3>{name}</h3>
        {expanded && <p>{role}</p>}
      </Card>
    );
  }
  ```

5. Gitワークフロー

コミット標準、ブランチ規約、PR要件。

## Git Conventions
- Commit format: `type(scope): description` (conventional commits)
- Branch naming: `feature/JIRA-123-brief-description`
- PRs require passing tests and lint checks

6. 明示的な境界

3層の制約構造はエンタープライズチームにとって重要です：

## Boundaries
**Always do:**
- Include unit tests for new functions
- Run lint before committing
- Use environment variables for configuration

**Ask first:**
- Database schema changes
- Adding new dependencies
- Modifying CI/CD pipelines
- Changes to authentication or authorization logic

**Never do:**
- Commit secrets, API keys, or connection strings
- Modify files in `vendor/` or `node_modules/`
- Edit generated migration files
- Push directly to main branch
- Modify `.env.production`

モノレポパターン

ここがエンタープライズチームにとってAGENTS.mdが面白くなる場所です。フォーマットは階層的ネストをサポート—サブディレクトリファイルは親ファイルを継承しオーバーライドし、最も近いファイルが優先されます。

/AGENTS.md                          ← グローバル：セキュリティルール、コミット規約
/frontend/AGENTS.md                 ← Reactパターン、CSS規約、コンポーネントルール
/frontend/components/AGENTS.md      ← コンポーネントライブラリ固有
/backend/AGENTS.md                  ← APIパターン、データベースルール、サービス規約
/infra/AGENTS.md                    ← Terraform/Bicepルール、命名規約

OpenAIはリポジトリ全体で約88のネストされたAGENTS.mdファイルを維持しています。それは過副ではなく—正確なのです。各チームがサブディレクトリのエージェントガイダンスを所有し、グローバルルールがルートからカスケードダウンします。

エンタープライズチームにとって、これはチームオーナーシップに自然にマッピングします。プラットフォームチームがルートレベルのルールを所有します。フロントエンド、バックエンド、インフラチームがそれぞれのサブディレクトリファイルを所有します。変更はコードと同様にプルリクエストを経由します。

AGENTS.md、CLAUDE.md、SKILL.md — それらがどう組み合わさるか

Claude Codeを使用していて（CLAUDE.mdガイドを読んだなら、おそらく使用しているでしょう）、これらのファイルがどう関係するのか疑問に思うかもしれません。メンタルモデルは以下の通りです：

AGENTS.md — 「このコードベースでどう作業するか」。ベンダーニュートラル。すべてのエージェントが読む。コマンド、アーキテクチャ、規約、境界を含む。
CLAUDE.md — 「Claudeが具体的にここでどう作業すべきか」。Claude Code専用。自動メモリ、MCPサーバー宣言、フック設定、Claude固有の最適化を追加。
SKILL.md — 「このカテゴリのタスクをどう実行するか」。再利用可能な専門知識パッケージ—コードベース固有ではなくタスク固有。Claude CodeとGemini CLIのskill作成ツールでskill作成ワークフローを取り上げました。

スタックとして考えてください：

システムプロンプト — モデルベースライン（これは制御できません）
AGENTS.md — コードベースコンテキスト（汎用）
SKILL.md — タスク専門知識（オンデマンド）
CLAUDE.md / .agent.md — エージェント固有設定（ツールごと）
MCPサーバー — 外部システムアクセス（ライブデータ）

マルチエージェントチームの場合、最も多くの努力をAGENTS.mdに投じます。これが最も広いリーチを持ちます。次にエージェント固有の最適化のためにCLAUDE.mdまたは.agent.mdファイルを重ねます。

エンタープライズスターターテンプレート

エンタープライズチーム向けのコピーペースト対応テンプレートです。詳細をカスタマイズし、構造を維持してください：

# AGENTS.md

## Project Overview
[One sentence: what this system does and who it serves]

## Tech Stack
- [Language] [version], [Framework] [version], [Build tool] [version]
- Database: [system] [version]
- Infrastructure: [platform] (Terraform/Bicep/CDK)
- CI/CD: [platform]

## Commands
- Install: `[command]`
- Dev: `[command]`
- Build: `[command]`
- Test all: `[command]`
- Test single: `[command] [path]`
- Lint: `[command]`
- Format: `[command]`

## Architecture
- `src/` — Application source code
  - `src/api/` — [description]
  - `src/web/` — [description]
  - `src/shared/` — [description]
- `infra/` — Infrastructure as code
- `tests/` — Integration and E2E tests
- `scripts/` — Automation and CI/CD
- `docs/` — Architecture decisions and runbooks

## Code Style
- [2-3 concrete rules with examples]
- Example:
  ```[language]
  // Preferred pattern
  [code example]
  ```

## Testing
- Framework: [name]
- Location: [pattern]
- Naming: [convention]
- Coverage: [minimum threshold if any]

## Git Conventions
- Commits: [format]
- Branches: [naming pattern]
- PRs: [requirements]

## Boundaries
**Always do:**
- [list critical always-do items]

**Ask first:**
- [list items requiring human approval]

**Never do:**
- [list absolute prohibitions]

15分で始める

初日から完璧なAGENTS.mdは必要ありません。最小限から始めて反復してください。

ステップ1（5分）: リポジトリルートにAGENTS.mdを作成します。ビルド、テスト、リントコマンドを追加します。これらが最も即効性のある影響を持ちます。

ステップ2（5分）: 正確なバージョン付きの技術スタックと、ディレクトリ構造をリストした簡潔なアーキテクチャセクションを追加します。

ステップ3（5分）: 境界セクションを追加します。「never do」から始めてください—エージェントが実行した場合実際のダメージを引き起こすもの。人間の判断が必要なものに「ask first」アイテムを追加します。

ステップ4（継続的）: エージェントが間違えるたびにルールを追加します。これがすべての成功しているチームが従う有機的成長パターンです。AGENTS.mdは学んだ教訓の生きた記録になります。

プロのヒント: 既存のリポジトリをスキャン—パッケージファイル、CI/CDワークフロー、貢献ガイドライン、git履歴—し、開始用AGENTS.mdを自動生成するようAIエージェントに依頼するコミュニティ管理プロンプトがあります。既存プロジェクトの最速のブートストラップです。

マルチエージェントの現実

今これが重要な理由です。AI CLI大戦により、チームは承認しているかどうかにかかわらず、おそらく既に複数のエージェントを使用しています。開発者は手元のタスクに最適なツールを選びます—対話型編集にCursor、複雑なリファクタリングにClaude Code、バックグラウンドタスクキューにCodex。

AGENTS.mdなしでは、各開発者が各エージェントを独立して設定します。規約が漂います。品質がばらつきます。同じ間違いがコードベースの異なる部分で異なるエージェントによって犯されます。

AGENTS.mdがあれば、標準を一度定義します。すべてのエージェント、すべての開発者、すべてのセッションが同じベースラインから始まります。それがエンタープライズの価値提案です：1つのエージェントを選ぶことではなく、すべてを一貫して機能させることです。

リソース

公式AGENTS.md仕様と例
GitHub Blog: 素晴らしいagents.mdの書き方 — 2,500以上のリポジトリからの教訓
Windsurf AGENTS.mdドキュメント
agentsmd.netテンプレート — 技術スタック別の14の本番対応テンプレート

マルチエージェント戦略を正しく整える

AGENTS.mdが基盤ですが、より広範なAIコーディング戦略の1ピースです。CLAUDE.mdファイルとどう組み合わさるか？MCPサーバーインフラストラクチャは？ガバナンス要件は？チームの実際のワークフローは？

Big Hat Groupはエンタープライズチームが首尾一貫したAIエージェント戦略を構築するのを支援します—設定ファイルだけでなく、フルスタック：エージェント設定、skill開発、セキュリティ境界、コンプライアンスチームを安心させるガバナンスフレームワーク。Copilot、Claude Code、Codexを同時に実行する組織全体にこれらのパターンをデプロイしてきました。

チームが複数のAIコーディングエージェントを扱っており、統一されたアプローチが必要な場合は、ご連絡ください。

Kevin Kaminskiは17回 Microsoft MVP であり、Big Hat GroupのPrincipalです。エンタープライズチームのAIエージェント、Windows 365、モダン管理ソリューションのデプロイを支援しています。