GitHub Copilotの設定 - AGENTS.md

提供: MochiuWiki : SUSE, EC, PCB

📢 Webサイト閉鎖と移転のお知らせ
このWebサイトは2026年9月に閉鎖いたします。
新しい記事は移転先で追加しております。（旧サイトでは記事を追加しておりません）

概要

AGENTS.md は、AIコーディングエージェント向けのオープンフォーマットであり、エージェント用のREADMEとして機能する。

Linux Foundation傘下のAgentic AI Foundationが管理する標準フォーマットであり、60以上のAIコーディングツールが対応している。

対応ツールの例を以下に示す。

  • GitHub Copilot
  • Cursor
  • Devin
  • Google Jules
  • OpenAI Codex
  • Anthropic Claude
  • その他55以上のツール


AGENTS.md は、以下に示す特徴を持つ。

  • ベンダー中立のオープンフォーマット
  • 標準的なMarkdown形式
  • 複数のディレクトリにネスト配置可能
  • AIエージェントの動作をプロジェクト固有にカスタマイズ
  • 60以上のAIツール間で互換性を持つ


AGENTS.md を使用することにより、以下に示すメリットが得られる。

  • プロジェクト固有のコンテキストを提供
    ビルドコマンド、テストコマンド、プロジェクト構造等をエージェントに伝える。
  • 複数のAIツール間で指示を共有
    GitHub Copilot、Cursor、Devin等で同じ指示を使用できる。
  • ディレクトリごとの詳細な制御
    ネスト配置により、ディレクトリごとに異なる指示を定義できる。
  • エージェントの動作範囲の明確化
    常時実行可能、事前確認、禁止の3段階で動作を制御できる。



ファイルの配置

AGENTS.md は、リポジトリルートまたはサブディレクトリに配置できる。

配置場所

AGENTS.md を配置可能な場所を以下に示す。

  • リポジトリルート
    プロジェクト全体の基本指示を定義する。
    例: /AGENTS.md
  • サブディレクトリ
    ディレクトリ固有の詳細指示を定義する。
    例: /frontend/AGENTS.md、/backend/AGENTS.md


ディレクトリ構成の例を以下に示す。

project/
├── .github/
│   ├── copilot-instructions.md              # リポジトリ全体の基本指示
│   │                                        # (コーディング規約、プロジェクト概要等)
│   │
│   ├── instructions/                        # パス固有の指示ファイル
│   │   ├── frontend.instructions.md         # applyTo: "src/frontend/**/*.ts,**/*.tsx"
│   │   ├── backend.instructions.md          # applyTo: "src/backend/**/*.ts"
│   │   ├── api.instructions.md              # applyTo: "src/api/**/*.ts"
│   │   ├── python.instructions.md           # applyTo: "**/*.py"
│   │   ├── testing.instructions.md          # applyTo: "**/tests/**/*,**/*.test.*"
│   │   └── security.instructions.md         # applyTo: "**/*.ts,**/*.py"
│   │                                        # excludeAgent: "coding-agent"
│   │
│   └── agents/                              # カスタムエージェント定義
│       ├── docs-agent.md                    # ドキュメント執筆専門
│       ├── test-agent.md                    # テスト専門
│       ├── security-agent.md                # セキュリティレビュー専門
│       └── refactor-agent.md                # リファクタリング専門
│
├── AGENTS.md                                # プロジェクト全体のエージェント指示
│                                            # (ビルドコマンド、テスト手順、境界設定等)
│
├── src/
│   ├── frontend/
│   │   ├── AGENTS.md                        # フロントエンド固有のエージェント指示
│   │   └── components/
│   │
│   ├── backend/
│   │   ├── AGENTS.md                        # バックエンド固有のエージェント指示
│   │   └── services/
│   │
│   └── api/
│       ├── AGENTS.md                        # API固有のエージェント指示
│       └── routes/
│
├── docs/
│   └── AGENTS.md                            # ドキュメント用のエージェント指示
│
└── README.md


ネスト対応

AGENTS.md は、複数のディレクトリにネスト配置可能である。

  • 優先順位
    ディレクトリツリーで最も近い AGENTS.md が優先される。
  • 継承
    親ディレクトリの AGENTS.md と併用される。


優先順位の例を以下に示す。

例えば、ソースファイルである /src/frontend/components/Button.tsx を編集する場合、以下に示す優先順位で AGENTS.md が適用される。

  1. /src/frontend/components/AGENTS.md (最優先)
  2. /src/frontend/AGENTS.md
  3. /src/AGENTS.md
  4. /AGENTS.md (最低優先度)


ファイル形式

AGENTS.md は、標準的なMarkdown形式で記述する。

  • フォーマット
    Markdown形式
  • フロントマター
    YAMLフロントマター推奨 (必須ではない)
  • 記述言語
    自然言語 (英語推奨)
  • 必須フィールド
    特定の必須フィールドなし


基本的な構造を以下に示す。

 ---
 name: agent_name
 description: エージェントの説明
 ---
 
 # プロジェクトの概要
 
 プロジェクトの説明と技術スタック
 
 ## Commands
 
 ビルド、テスト、リントのコマンド
 
 ## Project Structure
 
 ディレクトリ構造と各フォルダの役割
 
 ## Boundaries
 
 エージェントの動作範囲の定義



他の指示ファイルとの関係

GitHub Copilotは、複数の指示ファイルをサポートしている。

GitHub Copilot対応の指示ファイル

GitHub Copilotが対応する指示ファイルを以下に示す。

  • .github/copilot-instructions.md
    リポジトリ全体向けの基本指示
    配置場所: .github/ ディレクトリ
    適用範囲: リポジトリ全体
  • .github/instructions/*.instructions.md
    パス固有の指示 (globパターンで指定)
    配置場所: .github/instructions/ ディレクトリ
    適用範囲: YAMLフロントマターの applyTo プロパティで指定されたパターン
  • AGENTS.md
    エージェント専用の詳細ガイダンス
    配置場所: リポジトリルートまたはサブディレクトリ
    適用範囲: 配置されたディレクトリとその子ディレクトリ
  • CLAUDE.md、GEMINI.md
    代替フォーマット (エージェント固有)
    配置場所: 任意のディレクトリ
    適用範囲: 配置されたディレクトリとその子ディレクトリ


指示ファイルの比較

下表に、GitHub Copilot対応の指示ファイルの比較を示す。

GitHub Copilot対応の指示ファイルの比較
特徴 copilot-instructions.md *.instructions.md AGENTS.md
配置場所 .github/ .github/instructions/ 任意のディレクトリ
適用範囲 リポジトリ全体 globパターンで指定 配置されたディレクトリとその子ディレクトリ
ファイル数 1ファイル 複数ファイル可能 ディレクトリごとに1ファイル
パターン指定 不要 YAMLフロントマター必須 不要
ネスト対応 非対応 非対応 対応 (最も近いファイル優先)
他ツール互換性 GitHub Copilot専用 GitHub Copilot専用 60以上のツールで対応
用途 全体的な原則 言語別・パス別ルール エージェント専用の詳細ガイダンス


推奨される使い分けを以下に示す。

  • copilot-instructions.md
    プロジェクトの概要、技術スタック、全体的なコーディング規約
  • *.instructions.md
    TypeScript固有のルール、フロントエンド専用の規約、APIルートの要件
  • AGENTS.md
    ビルドコマンド、テストコマンド、プロジェクト構造、エージェントの動作範囲、境界設定



6つのコア領域

AGENTS.md は、6つのコア領域を定義することを推奨する。

2,500のリポジトリ分析により、これらの領域が最も頻繁に参照されることが確認されている。

Commands (コマンド)

ビルド、テスト、リントのコマンドをフラグ付きで記載する。

エージェントが頻繁に参照するため、ファイルの早期セクションに配置することを推奨する。

記述例を以下に示す。

 ## Commands
 
 - `npm test` - 全テスト実行
 - `pytest -v` - 詳細モードでPythonテストを実行
 - `npm run lint --fix` - リント実行と自動修正
 - `npm run build` - プロダクションビルド
 - `npm run dev` - 開発サーバー起動


Testing (テスト)

テストフレームワークの仕様と実行方法を記載する。

エージェントが何を修正でき、何ができないかを定義する。

記述例を以下に示す。

 ## Testing
 
 - テストフレームワーク: Jest (JavaScript), pytest (Python)
 - テストファイルの配置: `tests/` ディレクトリ
 - テストファイルの命名規則: `*.test.ts` または `test_*.py`
 - カバレッジ要件: 80%以上
 
 ### エージェントの制限
 
 - ソースコードは変更しない
 - 失敗するテストは削除しない
 - テストファイルの作成と修正のみ実行可能


Project Structure (プロジェクト構造)

ディレクトリツリーと各フォルダの役割を明確に定義する。

エージェントが何を読み取り、何に書き込めるかを指定する。

記述例を以下に示す。

 ## Project Structure
 
 - `src/` - ソースコード (読み取り専用)
 - `docs/` - ドキュメント (書き込み可能)
 - `tests/` - テストコード (書き込み可能)
 - `config/` - 設定ファイル (読み取り専用)
 - `scripts/` - ビルドスクリプト (読み取り専用)
 
 ### ディレクトリの役割
 
 - `src/frontend/` - React + TypeScriptのフロントエンドコード
 - `src/backend/` - Node.js + Expressのバックエンドコード
 - `src/api/` - RESTful APIエンドポイント


Code Style (コードスタイル)

実際のソースコード例を記載する。

3段落の説明よりも、実際のコード例を優先する。

記述例を以下に示す。

 ## Code Style
 
 ### 命名規則
 
 良い例:
 ```typescript
 function getUserById(id: string): User {
    const user = await userRepository.findById(id);
    return user;
 }
 ```
 
 悪い例:
 ```typescript
 function GetUser(i: string): User {
    const u = await repo.find(i);
    return u;
 }
 ```
 
 ### エラーハンドリング
 
 良い例:
 ```typescript
 async function fetchData() {
    try {
       const response = await api.getData();
       return response.data;
    }
    catch (error) {
       logger.error('Failed to fetch data', error);
       throw new DataFetchError('Data fetch failed');
    }
 }
 ```
 
 悪い例:
 ```typescript
 async function fetchData() {
    const response = await api.getData();
    return response.data;
 }
 ```


Git Workflow (Gitワークフロー)

コミット前のテスト実行要件とブランチ戦略を指定する。

記述例を以下に示す。

 ## Git Workflow
 
 - コミット前に必ずテストを実行する
 - ブランチ戦略: Git Flow
 - ブランチ命名規則: `feature/`, `bugfix/`, `hotfix/`
 - コミットメッセージ: Conventional Commits形式
 
 ### コミット前のチェックリスト
 
 1. `npm test` を実行し、全テストが成功することを確認
 2. `npm run lint` を実行し、リントエラーがないことを確認
 3. `npm run build` を実行し、ビルドが成功することを確認


Boundaries (境界設定)

エージェントの動作範囲を3段階で明確に定義する。

  • 常に実行すること
    事前確認なしで常時実行可能な操作
  • 確認が必要な操作
    実行前にユーザーの確認が必要な操作
  • 絶対禁止事項
    いかなる場合も実行してはならない操作


記述例を以下に示す。

 ## Boundaries
 
 ### 常に実行すること
 
 - テストファイルの作成と修正
 - ドキュメントの作成と更新
 - リントエラーの自動修正
 - コードフォーマットの適用
 
 ### 確認が必要な操作
 
 - ソースコードの変更
 - データベーススキーマの変更
 - 依存関係の追加・削除
 - 設定ファイルの変更
 
 ### 絶対禁止事項
 
 - 失敗するテストの削除
 - 本番環境へのデプロイ
 - 認証情報のハードコード
 - セキュリティ設定の変更



記述例

AGENTS.md の実際の記述例を以下に示す。

ドキュメント専門エージェント

技術ドキュメント執筆専門のエージェント向けの記述例を以下に示す。

  • ファイル名: /docs/AGENTS.md
     ---
 name: docs_agent
 description: 技術ドキュメント執筆専門家
 ---
 
 ## あなたの役割
 
 - Markdown と TypeScript に精通
 - 開発者向けに明確かつ実践的に執筆
 - `src/` から読み取り、`docs/` に書き込み
 
 ## 利用可能なツール
 
 - `npm run docs:build` - ドキュメントビルドとリンク検証
 - `npx markdownlint docs/` - マークダウン検証
 
 ## コードスタイル例
 
 良い例: 記述的な名前、エラーハンドリング完備
 ```typescript
 async function generateApiDocumentation(apiPath: string): Promise<void> {
    try {
       const apiSpec = await readApiSpec(apiPath);
       await writeDocumentation(apiSpec);
    }
    catch (error) {
       logger.error('Documentation generation failed', error);
       throw error;
    }
 }
 ```
 
 悪い例: 曖昧な名前、エラー処理なし
 ```typescript
 async function genDoc(p: string): Promise<void> {
    const spec = await read(p);
    await write(spec);
 }
 ```
 
 ## Boundaries
 
 ### 常に実行すること
 
 - ドキュメントファイルの作成と更新
 - リンク検証の実行
 - コード例の追加
 
 ### 確認が必要な操作
 
 - ドキュメント構造の大幅な変更
 - 目次の再構成

 ### 絶対禁止事項
 
 - ソースコードの変更
 - 設定ファイルの変更


テスト専門エージェント

QAソフトウェアエンジニア向けの記述例を以下に示す。

  • ファイル名: /tests/AGENTS.md
     ---
 name: test_agent
 description: QAソフトウェアエンジニア
 ---
 
 ## あなたの役割
 
 - テストコードを書き、テストを実行し、結果を分析
 - `/tests/` ディレクトリにのみ書き込み
 - ソースコードは変更しない
 - 失敗するテストは削除しない
 
 ## コマンド
 
 - `npm test` - 全テスト実行
 - `npm test -- --watch` - ウォッチモード
 - `npm run test:coverage` - カバレッジレポート
 - `npm run test:unit` - ユニットテストのみ実行
 - `npm run test:integration` - 統合テストのみ実行
 
 ## テストフレームワーク
 
 - フレームワーク: Jest
 - アサーションライブラリ: Jest組み込み
 - モックライブラリ: Jest組み込み
 
 ## テストの構造
 
 良い例:
 ```typescript
 describe('UserService', () => {
    describe('getUserById', () => {
       it('should return user when user exists', async () => {
          const mockUser = { id: '1', name: 'John' };
          userRepository.findById.mockResolvedValue(mockUser);
 
          const result = await userService.getUserById('1');
 
          expect(result).toEqual(mockUser);
       });
 
       it('should throw error when user does not exist', async () => {
          userRepository.findById.mockResolvedValue(null);
 
          await expect(userService.getUserById('1'))
             .rejects.toThrow('User not found');
       });
    });
 });
 ```
 
 悪い例:
 ```typescript
 test('user test', async () => {
    const u = await userService.getUserById('1');
    expect(u).toBeTruthy();
 });
 ```
 
 ## Boundaries
 
 ### 常に実行すること
 
 - テストファイルの作成
 - テストの実行
 - カバレッジレポートの確認
 
 ### 確認が必要な操作
 
 - テストフレームワークの設定変更
 - モックの追加
 
 ### 絶対禁止事項
 
 - ソースコードの変更
 - テストの削除
 - カバレッジ要件の緩和


セキュリティ専門エージェント

セキュリティレビュー専門のエージェント向けの記述例を以下に示す。

  • ファイル名: /AGENTS.md
     ---
 name: security_agent
 description: セキュリティレビュー専門家
 ---
 
 ## あなたの役割
 
 - セキュリティの脆弱性を検出し、修正提案を行う
 - OWASP Top 10に準拠した検証を実施
 - コードレビュー時にセキュリティ観点でチェック
 
 ## チェック項目
 
 ### 認証・認可
 
 - パスワードはハッシュ化して保存 (bcrypt、Argon2等)
 - JWT、OAuth2等の標準認証方式を使用
 - アクセストークンの有効期限を設定
 - セッション管理の適切な実装
 
 ### データ保護
 
 - 機密情報はログに記録しない
 - 外部通信はHTTPS必須
 - 暗号化キーは環境変数で管理
 
 ### インジェクション対策
 
 良い例: プリペアドステートメント
 ```typescript
 async function getUserByEmail(email: string): Promise<User> {
    const query = 'SELECT * FROM users WHERE email = $1';
    const result = await db.query(query, [email]);
    return result.rows[0];
 }
 ```
 
 悪い例: SQLインジェクションの脆弱性
 ```typescript
 async function getUserByEmail(email: string): Promise<User> {
    const query = `SELECT * FROM users WHERE email = '${email}'`;
    const result = await db.query(query);
    return result.rows[0];
 }
 ```
 
 ### XSS対策
 
 良い例: 入力のサニタイズ
 ```typescript
 function displayUserInput(input: string): string {
    return escapeHtml(input);
 }
 ```
 
 悪い例: 未検証の入力をそのまま表示
 ```typescript
 function displayUserInput(input: string): string {
    return input;
 }
 ```
 
 ## Boundaries
 
 ### ✅ 常に実行すること
 
 - セキュリティ脆弱性の検出
 - 修正提案の作成
 - セキュリティログの記録
 
 ### 確認が必要な操作
 
 - セキュリティ設定の変更
 - 認証フローの変更
 
 ### 絶対禁止事項
 
 - セキュリティ設定の緩和
 - 認証情報のハードコード
 - 脆弱性のある依存関係の追加



ベストプラクティス

2,500のリポジトリ分析から得られた AGENTS.md の記述のベストプラクティスを以下に示す。

明確なペルソナ定義

エージェントの役割を具体的に定義する。

  • 良い例
    • テストエンジニア
    • セキュリティレビュー専門家
    • ドキュメント執筆者
  • 悪い例
    • 便利なアシスタント
    • コーディングヘルパー


ペルソナを明確にすることにより、エージェントの専門性を高め、適切な動作を促進できる。

実装例優先

抽象的な説明よりも、実装例を優先する。

3段落の説明文よりも、1つの実装例の方が効果的である。

  • 良い例
    TypeScriptのコード例を示す。
  • 悪い例
    TypeScriptのベストプラクティスに従うこと という抽象的な指示


段階的な制限

エージェントの動作範囲を3層構造で明確に定義する。

  • 常時実行可能
    事前確認なしで実行できる操作
  • 事前確認
    実行前にユーザーの確認が必要な操作
  • 禁止
    いかなる場合も実行してはならない操作


この3層構造により、エージェントの動作範囲が明確になり、予期しない動作を防止できる。

バージョン指定

技術スタックのバージョンを明確に指定する。

バージョンを指定することにより、エージェントが適切なAPIと構文を使用できる。

  • 良い例
    React 18 with TypeScript, Vite
  • 悪い例
    React


反復的改善

初期は最小限から始め、エージェントの誤りに応じて詳細化する。

  1. 最小限の AGENTS.md を作成する。
  2. エージェントの動作を観察する。
  3. 誤った動作があれば、指示を追加する。
  4. 繰り返し改善する。


この反復的なアプローチにより、過度に詳細な指示を避け、実際に必要な指示のみを追加できる。

コマンドを早期配置

npm test、npm run build 等のコマンドをファイル前半に配置する。

エージェントが頻繁に参照するため、ファイルの早期セクションに配置することにより、エージェントの応答速度が向上する。

推奨されるセクション順序を以下に示す。

  1. Commands (コマンド)
  2. Testing (テスト)
  3. Project Structure (プロジェクト構造)
  4. Code Style (コードスタイル)
  5. Git Workflow (Gitワークフロー)
  6. Boundaries (境界設定)



避けるべきパターン

AGENTS.md の記述で避けるべきパターンを以下に示す。

曖昧な役割定義

曖昧な役割定義は避ける。

良い例を以下に示す。

  • You are a test engineer specializing in Jest and pytest
  • You are a security reviewer focusing on OWASP Top 10
  • You are a documentation writer for developer guides


悪い例を以下に示す。

  • You are a helpful coding assistant
  • You are a friendly AI
  • You are a programming helper


実行可能なコマンドの省略

ビルド、テスト、リントのコマンドを省略してはならない。

良い例を以下に示す。

  • npm test - 全テスト実行
  • pytest -v - 詳細モードでPythonテストを実行
  • npm run lint --fix - リント実行と自動修正


悪い例を以下に示す。

  • セクションにコマンドの記載がない
  • Run the tests という抽象的な指示のみ


コード例なしの文章のみ説明

抽象的な説明のみで、コード例がない記述は避ける。

良い例を以下に示す。

 ## Code Style
 
 良い例:
 ```typescript
 async function getUserById(id: string): Promise<User> {
    try {
       const user = await userRepository.findById(id);
       return user;
    }
    catch (error) {
       logger.error('Failed to get user', error);
       throw new UserNotFoundError(`User ${id} not found`);
    }
 }
 ```
 
 悪い例:
 ```typescript
 async function GetUser(i: string): Promise<User> {
    const u = await repo.find(i);
    return u;
 }
 ```


悪い例を以下に示す。

 ## Code Style
 
 TypeScriptのベストプラクティスに従うこと。
 関数名はcamelCaseを使用すること。
 エラーハンドリングを実装すること。


禁止事項を明記しない設定

エージェントの禁止事項を明記しないことは避ける。

良い例を以下に示す。

 ## Boundaries
 
 ### 常に実行すること
 
 - テストファイルの作成と修正
 
 ### 確認が必要な操作
 
 - ソースコードの変更
 
 ### 絶対禁止事項
 
 - 失敗するテストの削除
 - 本番環境へのデプロイ


悪い例を以下に示す。

  • Boundariesセクションが無い。
  • 常に実行すること のみを記載し、絶対禁止事項 を記載しない。



Claude Codeとの比較

下表に、AGENTS.md と CLAUDE.md の比較を示す。

AGENTS.md と CLAUDE.md の比較
項目 AGENTS.md CLAUDE.md
ファイル名 AGENTS.md CLAUDE.md
配置場所 任意のディレクトリ
(リポジトリルートまたはサブディレクトリ)		 任意のディレクトリ
(リポジトリルートまたはサブディレクトリ)
ネスト対応 対応
(最も近いファイル優先)		 対応
(親と自動マージ)
フォーマット 標準Markdown
(YAMLフロントマター推奨)		 標準Markdown
6コア領域 推奨構造として定義
(Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries)		 特に定義なし
複数エージェント対応 対応
(.github/agents/*.mdで定義可能)		 非対応
標準化団体 Linux Foundation
(Agentic AI Foundation)		 なし
他ツール互換性 60以上のツール
(Cursor、Devin、Google Jules、OpenAI Codex等)		 Claude Code専用
優先順位 最も近いAGENTS.mdが優先 親のCLAUDE.mdと自動マージ
YAMLフロントマター 推奨 (name, description等) 特に定義なし
継承メカニズム 親ディレクトリの指示と併用 親ディレクトリのCLAUDE.mdと自動マージ


推奨される使い分けを以下に示す。

  • AGENTS.md
    複数のAIツールを使用するプロジェクト、標準化されたフォーマットを重視するプロジェクト
  • CLAUDE.md
    Claude Code専用のプロジェクト、Claude Codeの独自機能を活用するプロジェクト


両方のファイルを併用することも可能である。

併用時の動作を以下に示す。

  • GitHub Copilot
    AGENTS.md を優先的に使用
  • Claude Code
    CLAUDE.md を優先的に使用、AGENTS.md も参照可能
  • Cursor
    AGENTS.md を優先的に使用
  • Devin
    AGENTS.md を優先的に使用



関連項目



「http://mochiuwiki.e2.valueserver.jp/index.php?title=GitHub_Copilotの設定_-_AGENTS.md&oldid=14197」から取得