copilot-instructions.md と AGENTS.md、どっちに何を書く？【公式推奨と使い分け】

SHARE

目次

はじめに

ども！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 StackBackend/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 StyleGood/Bad のコード例、命名規則
GitワークフローGit Workflowコミット慣行、ブランチ戦略
境界線BoundariesAlways / Ask First / Never

ベストプラクティス: コマンドを先頭に配置、説明より具体例を重視

公式推奨の重複に注目

両方の公式推奨を見比べると、重複する項目があることがわかります。

項目copilot-instructions.mdAGENTS.md
プロジェクト構造○○
テスト○（Tech Stack内）○
コードスタイル○（Coding Guidelines）○

公式は「What vs How」の分離を明示的に推奨していません。

これはおそらく以下の理由によるものです：

  • 単独利用を想定: どちらか一方だけ使う場合でも完結するように
  • クロスツール互換: AGENTS.md は他のAIツールでも使うため、Copilot固有の情報に依存しない

次のセクションで紹介する「What vs How 分離」は、両方を併用する場合に重複・矛盾を避けるための筆者独自の設計指針として提案するものです。

役割分担の原則: What vs How【筆者独自の提案】

⚠️ 注意: 以下は公式推奨ではなく、両ファイル併用時の重複・矛盾を避けるための筆者独自の設計指針です。

両方使うなら、役割分担が必要です。僕が考えた分離の基準は「What vs How」です。

観点copilot-instructions.mdAGENTS.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.mdWhat（何をするか）方針・規約・制約
AGENTS.mdHow（どうやるか）手順・コマンド・境界線
*.instructions.mdWhat の詳細ファイル別ルール
  • 複数ファイルはマージされて読み込まれる
  • 公式推奨には重複があるが、両方使うなら役割分担が必要
  • What と How で分離するのが筆者のおすすめ
  • ただし、特殊な事情がなければどっちかに寄せるのが一番楽

参考リンク

公式ドキュメント

関連記事

ここまで読んでいただき、ありがとうございました！

正直、両方メンテするのはしんどいので、可能なら片方に寄せてください。でも「Claude Code も使ってるから AGENTS.md は残したい」みたいな状況になったら、この記事を思い出してもらえると嬉しいです。

ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？

役に立った 役に立たなかった

0人がこの投稿は役に立ったと言っています。
エンジニア募集中!

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

前の記事

copilot-instructions.md を分割したい？…

次の記事

【2026年版】Agent Skills 入門：SKILL.m…