はじめに
ども！GitHub Copilot の設定に対して徐々に理解が進んでいる龍ちゃんです。
これまでの記事で、AGENTS.md と Custom Agents の違いと、copilot-instructions.md の分割設計について解説してきました。
で、ここまで読んでくれた方は気づいたかもしれません。AGENTS.md と copilot-instructions.md、書く内容かぶってない？ と。
機能的には両者が近い機能を持っているように感じています。発火条件も近いですしね。
んでよ！どっちのファイルも同じタイミングで読み込まれるなって話になってしまいまして迷子になりました。そりゃ、「AGENTS.md」は参照されるだけで、GitHub Copilot がメインでメンテナンスしているものではないですからね。
というわけで、今回はそれぞれの設定ファイルの公開されている「設定すべき情報」から共生させる方法について考えた内容に関して触れていこうと思います。それぞれのファイルの設定すべき内容にも触れるので、AGENTS・instructions どちらかしか使ってねえ！って方でもそれぞれのファイルで設定すべき内容について触れるから安心してね。
ぶっちゃけ前提
プロジェクト上、とんでもなく特殊な事情がない限りどっちかに寄せたい！だってメンテナンスとか、どっちのファイルに何書くとか考えるのめんどくさいもん！
なんでこれはチーム向けの記事だと思って読み物で。特殊な状況になった皆さんにお疲れさまと、もしもっといい方法があるってわかったら連絡くださいってお気持ちを置いときます。
検証環境
- 検証日: 2026年1月30日
- 環境: VS Code + Dev Container
- GitHub Copilot: 2026年1月時点の機能
複数ファイルの読み込み動作
まず、Copilot Coding Agent がどのファイルを読み込むのかを整理します。
ポイント:
- 競合ではなくマージされる
- 矛盾する指示があった場合の優先順位は公式未定義
- → 矛盾を避ける設計が必要
全部読み込んでマージされるってことは、同じことを両方に書いたら重複するし、矛盾したら何が優先されるかわからないってことです。
公式が推奨する記載内容
両ファイルにどのような内容を書くべきか、公式が推奨している内容を整理します。
copilot-instructions.md の公式推奨（5セクション）
出典: 5 tips for writing better custom instructions for Copilot – GitHub Blog
| セクション | 英語名 | 書くべき内容 |
|---|---|---|
| プロジェクト概要 | Project Overview | アプリの目的、対象ユーザー、主要機能 |
| テックスタック | Tech Stack | Backend/Frontend/Testing のフレームワーク、API |
| コーディングガイドライン | Coding Guidelines | 言語ルール（セミコロン、型ヒント等）、セキュリティ慣行 |
| プロジェクト構造 | Project Structure | フォルダ構成と各ディレクトリの用途 |
| リソース | Resources | 開発スクリプト、MCPサーバー、自動化ツール |
制約: 2ページ以内
AGENTS.md の公式推奨（6セクション）
出典: How to write a great agents.md – GitHub Blog
| セクション | 英語名 | 書くべき内容 |
|---|---|---|
| コマンド | Commands | ビルド、テスト、リントの実行コマンド（フラグ含む） |
| テスト | Testing | テストフレームワーク、実行方法 |
| プロジェクト構造 | Project Structure | ディレクトリ構成の説明 |
| コードスタイル | Code Style | Good/Bad のコード例、命名規則 |
| Gitワークフロー | Git Workflow | コミット慣行、ブランチ戦略 |
| 境界線 | Boundaries | Always / Ask First / Never |
ベストプラクティス: コマンドを先頭に配置、説明より具体例を重視
公式推奨の重複に注目
両方の公式推奨を見比べると、重複する項目があることがわかります。
| 項目 | copilot-instructions.md | AGENTS.md |
|---|---|---|
| プロジェクト構造 | ○ | ○ |
| テスト | ○（Tech Stack内） | ○ |
| コードスタイル | ○（Coding Guidelines） | ○ |
公式は「What vs How」の分離を明示的に推奨していません。
これはおそらく以下の理由によるものです：
- 単独利用を想定: どちらか一方だけ使う場合でも完結するように
- クロスツール互換: AGENTS.md は他のAIツールでも使うため、Copilot固有の情報に依存しない
次のセクションで紹介する「What vs How 分離」は、両方を併用する場合に重複・矛盾を避けるための筆者独自の設計指針として提案するものです。
役割分担の原則: What vs How【筆者独自の提案】
⚠️ 注意: 以下は公式推奨ではなく、両ファイル併用時の重複・矛盾を避けるための筆者独自の設計指針です。
両方使うなら、役割分担が必要です。僕が考えた分離の基準は「What vs How」です。
| 観点 | copilot-instructions.md | AGENTS.md |
|---|---|---|
| 責務 | What（何をするか） | How（どうやるか） |
| 内容 | 方針・規約・制約 | 手順・コマンド・境界線 |
| 更新頻度 | 低（安定したルール） | 中〜高（手順は変わりやすい） |
| 適用範囲 | Copilot 全機能 | Coding Agent 中心 |
なぜこの分離が有効か
copilot-instructions.md は .github/ ディレクトリにあって、機能変更とは別にコミットされることが多いです。レビュー時も「設定変更」として独立して見られます。
一方、AGENTS.md は各ディレクトリに配置できるので、そのディレクトリのファイル変更と一緒にレビューされやすい。つまり「手順」の変更は実装と一緒に更新されるイメージです。
- What（方針） は変わりにくい → copilot-instructions.md
- How（手順） は変わりやすい → AGENTS.md
- 変更頻度でファイルを分けると管理しやすい
何をどこに書くか【具体例】
copilot-instructions.md に書く内容（What）
## コードスタイル
- TypeScript strict mode を使用
- 関数は camelCase、コンポーネントは PascalCase
- any 型の使用禁止
## アーキテクチャ
- Clean Architecture に従う
- ビジネスロジックは domain/ に配置
- 外部依存は infrastructure/ に隔離
## 使用ライブラリ
- 状態管理: Zustand（Redux は使わない）
- フォーム: React Hook Form + Zod
- テスト: Vitest + Testing Library
特徴: 「どうあるべきか」を記述
AGENTS.md に書く内容（How）
## コマンド
npm ci # 依存インストール
npm run dev # 開発サーバー起動
npm test # テスト実行
npm run lint:fix # リント自動修正
## 境界線
### Always Do
- テストを書いてから実装（TDD）
- 変更したファイルに対応するテストを更新
### Ask First
- 新しいnpmパッケージの追加
- 既存のAPI契約（型定義）の変更
### Never Do
- .env ファイルをコミットしない
- console.log を本番コードに残さない
特徴: 「どうやるか」を記述
同じことを両方に書かない
悪い例（重複）
# copilot-instructions.md
TypeScriptのstrictモードを使用してください。
テストはVitestで書いてください。
`npm test` でテストを実行します。 ← 手順がここにある
# AGENTS.md
TypeScriptのstrictモードを使用してください。 ← 重複
テストはVitestで書いてください。 ← 重複
npm test # テスト実行
問題点: 同じ内容が2箇所に。片方だけ更新すると矛盾が発生。
良い例（分担）
# copilot-instructions.md
TypeScriptのstrictモードを使用してください。
テストはVitestで書いてください。
← コマンドは書かない
# AGENTS.md
## コマンド
npm test # テスト実行
npm run test:watch # ウォッチモード
← 方針は書かない
メリット: 責務が明確、更新箇所が1箇所、矛盾が発生しない
どっちに書くか迷ったら
新しい指示を追加するとき、どっちに書くか迷ったら2つの質問で判断してください。
Q1. Chat や Code Review でも使いたい？
- No → AGENTS.md に書く（Coding Agent 専用でOK）
- Yes → Q2 へ
Q2. 「方針」か「手順」か？
- 方針（〜すべき、〜を使う、〜は禁止） → copilot-instructions.md
- 手順（コマンド、境界線、具体的な操作） → AGENTS.md
シンプルに言うと：
| こんな内容なら | 配置先 |
|---|---|
| 「TypeScript strict mode を使う」 | copilot-instructions.md |
npm test で実行 | AGENTS.md |
| 「Redux は使わない」 | copilot-instructions.md |
| 「.env をコミットしない」（Never Do） | AGENTS.md |
*.instructions.md との組み合わせ
前回記事で紹介した *.instructions.md も含めると、3層構造になります。
copilot-instructions.md # 全体の方針（What）
├── *.instructions.md # ファイル別の詳細ルール（What の詳細）
└── AGENTS.md # 手順・コマンド・境界線（How）
| 内容 | 配置先 |
|---|---|
| 「TypeScript strict mode を使用」 | copilot-instructions.md |
| 「React コンポーネントは forwardRef 必須」 | frontend-ui.instructions.md |
「npm run lint:fix でリント修正」 | AGENTS.md |
まとめ
| ファイル | 役割 | キーワード |
|---|---|---|
| copilot-instructions.md | What（何をするか） | 方針・規約・制約 |
| AGENTS.md | How（どうやるか） | 手順・コマンド・境界線 |
| *.instructions.md | What の詳細 | ファイル別ルール |
- 複数ファイルはマージされて読み込まれる
- 公式推奨には重複があるが、両方使うなら役割分担が必要
- What と How で分離するのが筆者のおすすめ
- ただし、特殊な事情がなければどっちかに寄せるのが一番楽
参考リンク
公式ドキュメント
- Adding custom instructions for GitHub Copilot – GitHub Docs
- 5 tips for writing better custom instructions for Copilot – GitHub Blog
- How to write a great agents.md – GitHub Blog
関連記事
ここまで読んでいただき、ありがとうございました！
正直、両方メンテするのはしんどいので、可能なら片方に寄せてください。でも「Claude Code も使ってるから AGENTS.md は残したい」みたいな状況になったら、この記事を思い出してもらえると嬉しいです。
