対象読者チームのコーディング規約をAIに記憶させたい開発者

達成目標copilot-instructions.md・AGENTS.md・Agent Skillsを設計・配置できる

前提条件Getting Started完了

所要時間20分

カスタム指示

GitHub Copilotの動作をプロジェクトに最適化するための指示ファイル。リポジトリ全体、パス固有、エージェント向けの3種類を使い分けて、チーム全員が一貫した高品質なAI支援を受けられるようにします。

カスタム指示の概要

GitHub Copilotはデフォルトでも優れたコード提案を行いますが、プロジェクト固有のコーディング規約やアーキテクチャに合わせるには、カスタム指示が不可欠です。Copilotには3種類の指示ファイルがあり、それぞれ異なるスコープと用途を持ちます。

copilot-instructions.md

リポジトリ全体に適用されるグローバルな指示。.github/copilot-instructions.md に配置。全てのCopilot機能（Chat、Agent Mode、Inline Completions）に自動で読み込まれます。

パス固有の指示

.github/instructions/ ディレクトリに配置。YAML frontmatterでglob指定し、特定のファイルパターンにのみ適用される細かな指示を記述します。

AGENTS.md

リポジトリ内の任意のディレクトリに配置可能。Coding Agent（クラウド）やAgent Modeが参照するエージェント専用の指示ファイルです。

📝 Note

これらの指示ファイルはリポジトリにコミットすることで、チーム全員が同じAI支援ルールを共有できます。.gitignore に追加しないよう注意してください。

機能ごとの指示ファイルサポート

機能によってサポートされる指示ファイルの種類が異なります:

指示ファイル	Copilot Chat	Coding Agent	Code Review	CLI
`copilot-instructions.md`	✅	✅	✅	✅
`.instructions.md`（パス指定）	✅	✅	✅	✅
`AGENTS.md`	—	✅	—	✅
`.github/agents/*.agent.md`	—	✅	—	—

📝 Note

AGENTS.mdはCoding AgentとCLIが参照しますが、Copilot ChatやCode Reviewでは直接参照されません。Chat向けのルールはcopilot-instructions.mdに記載してください。

copilot-instructions.md

リポジトリ全体に適用されるグローバル指示ファイルです。.github/copilot-instructions.md に配置すると、Copilotの全機能が自動的にこの指示を読み込みます。

配置場所

.github/copilot-instructions.md

フォーマット

プレーンMarkdownで記述します。特別なYAMLフロントマターやメタデータは不要で、自然言語で指示を書くだけです。

推奨する記載内容

リポジトリ概要 — プロジェクトの目的、技術スタック、ディレクトリ構造の説明
ビルド/テストコマンド — npm run build、pytest などのコマンド
コーディング規約 — 命名規則、インポート順序、エラーハンドリングのパターン
アーキテクチャ — レイヤー構成、依存関係のルール、重要な設計決定

.github/copilot-instructions.md の例

# Project Overview

This is a Next.js 15 application with TypeScript.

## Build & Test
- `npm run dev` - 開発サーバー起動
- `npm run build` - プロダクションビルド
- `npm test` - テスト実行（Vitest）

## Coding Conventions
- TypeScriptのstrictモードを使用
- コンポーネントはfunction宣言（アロー関数不可）
- エラーハンドリングにはResult型パターンを使用
- インポートはabsolute pathを使用（@/で始まる）

## Architecture
- `src/app/` - App Router pages
- `src/components/` - 共有UIコンポーネント
- `src/lib/` - ビジネスロジック
- `src/types/` - TypeScript型定義

✅ Tip

指示は簡潔かつ具体的に書きましょう。「良いコードを書いて」のような抽象的な指示よりも、「全ての関数にJSDocコメントを付ける」のような明確な指示の方が効果的です。

パス固有の指示

.github/instructions/ ディレクトリに NAME.instructions.md 形式のファイルを配置することで、特定のファイルパターンにのみ適用される指示を定義できます。

ファイル構造

.github/
  instructions/
    python.instructions.md
    react.instructions.md
    tests.instructions.md
    api.instructions.md

YAML Frontmatter

各ファイルの先頭にYAML frontmatterを記述し、applyTo フィールドでglobパターンを指定します。

python.instructions.md

---
applyTo: "**/*.py"
---
# Python開発ルール

- Type hintsを必須とする
- docstringはGoogle形式を使用
- importはisortの順序に従う（stdlib → third-party → local）
- 例外処理では具体的な例外クラスをcatchする
- f-stringを優先的に使用する

react.instructions.md

---
applyTo: "src/components/**/*.tsx"
---
# Reactコンポーネントルール

- function宣言でコンポーネントを定義する（export default function不可）
- Propsは型を明示的に定義する（inline不可）
- useEffectのdependency arrayを必ず指定する
- カスタムフックはuse接頭辞で始める

tests.instructions.md

---
applyTo: "**/*.test.{ts,tsx}"
---
# テストルール

- describeでグループ化し、itでテストケースを記述
- テスト名は日本語で記述（例: "ユーザーが正常にログインできる"）
- mockは各テストケースで初期化する
- assertionにはexpect().toBe() を優先する

📝 Note

パス固有の指示は、Copilotが該当パターンに一致するファイルを編集する際に自動で読み込まれます。copilot-instructions.md のグローバル指示と組み合わせて使用でき、パス固有の指示が優先されます。

AGENTS.md

AGENTS.md はCoding Agent（クラウドエージェント）やVS CodeのAgent Modeが参照する指示ファイルです。リポジトリ内の任意のディレクトリに配置でき、ディレクトリツリーで最も近いファイルが優先されます。

配置ルール

ルートの AGENTS.md — リポジトリ全体に適用される共通指示
サブディレクトリの AGENTS.md — そのディレクトリ以下に適用される固有指示
継承 — エージェントは作業ディレクトリから親方向に全ての AGENTS.md を読み込み、最も近いファイルの指示を優先します

repo/
  AGENTS.md              # リポジトリ全体の指示
  frontend/
    AGENTS.md            # frontend固有の指示（上書き可能）
    src/
      components/
        AGENTS.md        # コンポーネント固有の指示

ルートの AGENTS.md 例

# AGENTS.md

## ビルド & テスト
- `npm run build` でビルド
- `npm test` でテスト実行
- PRを作成する前に必ずテストを通すこと

## コーディングルール
- TypeScript strictモード
- ESLint/Prettier設定に従う
- コミットメッセージはConventional Commits形式

✅ Tip

AGENTS.md はCoding Agentが自律的にタスクを実行する際に特に重要です。ビルドコマンドやテストコマンドを記載しておくと、エージェントが自分でテストを実行し、エラーを修正できるようになります。

📝 Note

VS CodeでのAGENTS.md読み込みは実験的機能です。有効化するには chat.useAgentsMdFile: true を設定してください。Coding AgentではデフォルトでAGENTS.mdを読み込みます。

永続記憶基盤としてのAGENTS.md

AGENTS.mdはCoding Agentへの指示だけでなく、チーム全体のエージェントルールや過去の教訓を蓄積する「永続記憶」としても機能します。

Lessons Learned セクションの例

### Lessons Learned (過去の教訓)
* 2026/03/01: PrismaクエリのN+1問題が頻発 → 関連データ取得時は常に `include` を明示指定
* 2026/03/15: MSALログインフローでは `page.goto()` 後に `waitForURL()` で待機必須

✅ Tip

Claude CodeのSelf-Improvement Loop（lessons.md → CLAUDE.mdへの昇格）と同じパターンです。エージェントがミスしたらAGENTS.mdにルールを追加し、同じミスを防ぎましょう。

YAML frontmatter によるエージェント専門家化

AGENTS.mdにYAML frontmatterを追加することで、エージェントに明確な専門性と行動境界を定義できます。

専門家化されたAGENTS.md の例

---
name: prisma-expert
description: Prisma ORM専門家。N+1問題を絶対に起こさない
---
You are an expert Prisma engineer for this Next.js + TypeScript project.

## Lessons Learned（過去の教訓）
- N+1問題が多発 → 常に関連データを `include: { author: true }` で明示
- トランザクション漏れでデータ不整合 → Always `prisma.$transaction()` 使用

## Boundaries（行動境界）
- **Always**: テスト実行後にコミット
- **Ask first**: DBスキーマ変更は人間に確認
- **Never**: 機密情報（.env）をコミット

✅ Tip

GitHub公式の2,500リポジトリ分析では、明確なBoundaries（Always/Ask/Never）と実コード例を含むAGENTS.mdが「成功率3倍以上」。曖昧な役割定義だけのファイルは効果が薄いことが判明しています。

Agent Skills（.github/skills/）

頻出の手順やデバッグフローを「スキル」として保存し、Copilotがタスク文脈に応じて自動ロードする仕組みです。

.github/skills/
├── playwright-e2e/
│   └── SKILL.md
├── debug-prisma/
│   └── SKILL.md
└── api-design/
    └── SKILL.md

SKILL.md の例

---
name: playwright-e2e
description: Playwrightを使ったE2Eテスト作成・実行専門
---
## 手順
1. Playwright MCP起動
2. 対象ページをブラウザで開く
3. テストケースを生成
4. 即実行し、失敗時はログ解析→修正
5. 全テスト通過を確認

📝 Note

Agent SkillsはClaude Codeの .claude/skills/ と同じ概念です。MCPと組み合わせれば「スクショ撮影→バグ特定→修正→再テスト」まで全自動化できます。

エージェント除外

パス固有の指示ファイルでは、YAML frontmatterに excludeAgent を追加することで、特定のエージェントからその指示を除外できます。

Code Reviewエージェントから除外

---
applyTo: "**/*.generated.ts"
excludeAgent: "code-review"
---
# 自動生成ファイル
このファイルは自動生成されるため、コードレビューの対象外とする。

Coding Agentから除外

---
applyTo: "config/**/*"
excludeAgent: "coding-agent"
---
# 設定ファイル
設定ファイルはCoding Agentによる自動変更を禁止する。

利用可能な excludeAgent 値:

"code-review" — Code Reviewエージェント（PR自動レビュー）から除外
"coding-agent" — Coding Agent（クラウドエージェント）から除外

⚠️ Warning

セキュリティ上重要な設定ファイルやシークレット関連のファイルは、excludeAgent で Coding Agent の変更対象から除外することを推奨します。

Claude Code CLAUDE.md との比較

Claude CodeのCLAUDE.mdとGitHub Copilotの指示ファイルは似た目的を持ちますが、仕組みが異なります。

項目	copilot-instructions.md	CLAUDE.md
スコープ	リポジトリ全体（`.github/` 内）	リポジトリ全体（ルート配置）
フォーマット	Markdown（自然言語）	Markdown（自然言語）
自動ロード	全Copilot機能が自動読込	Claude Code起動時に自動読込
パス固有指示	`.github/instructions/*.instructions.md`	サブディレクトリに `CLAUDE.md` 配置
パターン指定	`applyTo` でglob指定	ディレクトリ階層で暗黙的に決定
エージェント向け	別ファイル（`AGENTS.md`）	`CLAUDE.md` に統合
ユーザーレベル設定	VS Code設定 or GitHub設定	`~/.claude/CLAUDE.md`

📝 Note

GitHub CopilotとClaude Codeを併用する場合は、両方の指示ファイルをリポジトリに含めることで、どちらのツールを使っても一貫した開発体験を得られます。内容は可能な限り統一しましょう。

ベストプラクティス

簡潔に書く — 長すぎる指示はコンテキストウィンドウを圧迫します。重要なルールに絞りましょう
タスク非固有にする — 「この機能を実装して」ではなく、「全ての新規機能にはテストを書く」のような一般的なルールを記述します
ビルド/テストコマンドを含める — エージェントが自律的にビルド・テストを実行できるよう、コマンドを明記しましょう
段階的に拡充する — 最初から完璧な指示を書く必要はありません。チームの利用経験に基づいて徐々に改善します
バージョン管理する — 指示ファイルはコードと同様にGitで管理し、変更履歴を追跡しましょう

✅ Tip

awesome-cursorrules や awesome-copilot リポジトリには、様々なプロジェクトタイプ向けのカスタム指示テンプレートが公開されています。自分のプロジェクトに合ったテンプレートを参考にしましょう。

✅ Tip

トークン節約のコツ: AGENTS.mdの冒頭に Trust this file first before exploring the codebase. と書くと、Copilotがまずこのファイルを優先的に参照し、不要なファイル探索を減らせます。

Claude Codeからの移行ガイド

CLAUDE.md から AGENTS.md への変換は簡単です。以下のマッピング表を参考にしてください。

変換マッピング

Claude Code	GitHub Copilot	対応
`CLAUDE.md`	`AGENTS.md` + `copilot-instructions.md`	ほぼ同一構造
`.claude/rules/`	`.github/instructions/*.instructions.md`	パス指定対応
`.claude/skills/`	`.github/agents/`（カスタムエージェントプロファイル）	`.github/agents/` は、Copilot coding agent用のカスタムエージェントプロファイルを配置するディレクトリです。各エージェントは `.agent.md` ファイルとして定義します。
`.claudeignore`	Content Exclusion（リポジトリ/Organization設定UI）	ファイルではなく設定UIで管理
`lessons.md`	`AGENTS.md` のLessons Learnedセクション	統合可能
`settings.json`（permissions）	Organization Policies + autoApprove設定	管理レベルが異なる

具体的な移行手順

CLAUDE.md の内容を AGENTS.md にコピー
MUST/NEVER ルールはそのまま使える（Copilotも強い言葉を認識）
.claude/rules/ のファイルを .github/instructions/ に移動（frontmatterの applyTo を追加）
.claudeignore の除外パターンをContent Exclusion設定（Settings → Copilot → Content exclusion）に登録
lessons.md の内容を AGENTS.md のLessons Learnedセクションに統合

📝 Note

移行作業は30分程度で完了します。両方を併用することも可能です（Claude Code＝ターミナル大規模作業、Copilot＝IDE日常作業）。

コンテンツ除外（Content Exclusion）

Copilotに読み込ませたくないファイルやディレクトリは、リポジトリ設定またはOrganization設定で除外します。

設定手順（リポジトリレベル）

GitHub.com → リポジトリ Settings → Copilot → Content exclusion にアクセス
「Add exclusion」をクリック
パスパターンを指定（例: .env, secrets/**, *.pem）

設定手順（Organization レベル）

GitHub.com → Organization Settings → Copilot → Content exclusion にアクセス
リポジトリ名とパスパターンを指定

⚠️ 重要

Content ExclusionはAgent Mode、Copilot CLI、Coding Agentでは現在サポートされていません。これらの機能で機密コードの除外を保証するには、リポジトリ構成で機密ファイルを分離し、人間による最終確認を徹底してください。

推奨される機密ファイル保護策

機密情報は別リポジトリに分離
.env は .gitignore で管理（リポジトリに含めない）
認証情報はGitHub Secretsやvaultで管理
Coding Agentが触れるリポジトリに機密ファイルを置かない

📝 Note

かつてコミュニティで .copilotignore ファイルの要望がありましたが、現時点では実装されていません。Content Exclusionは設定UIまたはREST APIで管理します。

← 前のページ

Copilot CLI

Spaces & MCP