【第1回】GitHub Copilot Agent Mode 実践入門 — AGENTS.mdとVS Code設定で始めるAgent Modeの基本

GitHub Copilot Agent Mode、ちゃんと使えてますか？

自分はしばらく「補完とチャットがちょっと賢くなったやつ」くらいの認識で使っていたんですが、ある日 AGENTS.md の存在を知ってから急に景色が変わりました。「あ、これ別のツールだ」ってなった感じです。

この記事はシリーズ「GitHub Copilot Agent Mode 実践入門」の第1回です。全4回を通して、VS Codeの基本設定からAGENTS.mdの書き方、MCP連携、実務での使い方まで順を追って紹介していきます。今回はまず「Agent Modeとは何か」を整理しつつ、AGENTS.mdとsettings.jsonの初期設定まで一通り動かすところを目指します。

• 第1回：AGENTS.mdとVS Code設定で始めるAgent Modeの基本（← 今ここ）
• 第2回：AGENTS.mdを育てる — プロジェクト固有ルールの書き方と運用
• 第3回：ターミナル操作・自動承認設定とリスク管理
• 第4回：MCP連携とカスタムエージェントで広げるAgent Mode

GitHub Copilot Agent Modeって何が違うの？

従来のCopilot Chatは基本的に「聞いたことに答える」ツールでした。コードを提案してくれるけど、実際にファイルを編集したりテストを走らせたりするのは人間がやる、というスタンス。

Agent Modeはそこが根本的に違います。

コードベースを解析し、関連ファイルを読み込み、ファイル編集を提案し、ターミナルコマンドやテストを実行する——これを自律的にループしてくれるのがAgent Modeです。コンパイルエラーが出ればそれを読んで自己修正するし、テストが落ちれば原因を調べてコードを直そうとします。

要は「コード補完ツール」から「自律的に動くペアプログラマー」への格上げ、というイメージが近いです。もちろんまだ完全に任せられるわけじゃないですが、それはシリーズの後半で話します。

ちなみにAgent Modeはチャットやマルチファイル編集とは根本的に異なり、アイデアをコードに変換するために必要なすべてのサブタスクを自律的に完了させることができます。この「サブタスクを自律的に」の部分がポイントで、自分で計画を立てて実行してくれるわけです。

前提条件と有効化の確認

まず使える状態になっているかを確認します。

Agent Modeはほとんどの利用形態でアクセスできるようになっています。無料プランでも有料プランでも利用できますが、無料プランの場合は利用量に制限があります。

VS Codeでの確認手順：

1. GitHub CopilotとGitHub Copilot Chat拡張がインストールされていること
2. GitHubアカウントでサインイン済みであること
3. チャットパネルを開き、モード選択ドロップダウンで「Agent」が選べること

「Agent」という選択肢が出てこない場合は、まずVS Codeと拡張機能を最新版にアップデートしてください。それでも出ない場合は組織のポリシーで制限されている可能性があります（Business/Enterpriseプランの場合は管理者に確認を）。

VS Code settings.jsonの基本設定

Agent Modeを有効にしたら、まず.vscode/settings.jsonに最低限の設定を入れておきます。

{
  "github.copilot.chat.agent.enabled": true,
  "github.copilot.chat.agent.maxIterations": 15,
  "github.copilot.chat.agent.autoApproveTerminal": false,
  "github.copilot.chat.agent.autoApproveFileChanges": false
}

各項目について補足します。

• agent.enabled: Agent Modeを有効にするフラグです。最近のバージョンではデフォルトで有効になっているケースもあるようなので、明示的に書いておくほうが安心です。
• maxIterations: 1セッションで実行できるイテレーション（リクエスト）の上限です。デフォルト値は環境やバージョンで異なる可能性があるため、まずはこのくらいを目安にして、必要なら調整するのがよさそうです。増やすと消費量も増えるので注意。
• autoApproveTerminal: ターミナルコマンドを自動実行するかどうか。最初はfalseで運用してください。trueにすると確認なしにコマンドが走ります。
• autoApproveFileChanges: ファイル変更の自動承認。同様に最初はfalse推奨。

Agent Modeはチャットモードと比べてトークン消費がかなり増えることがあるようです。使いすぎると利用枠に引っかかる可能性があるので、最初は小さいタスクで感覚を掴むのがよさそうです。

ターミナルコマンドをある程度自動化したい場合は、allowlistを使う方法もあります：

{
  "chat.tools.terminal.autoApprove": {
    "/^git\\s+(status|diff|log)\\b/": true,
    "/^npm\\s+(test|run\\s+lint)\\b/": true,
    "rm": false,
    "sudo": false
  }
}

安全なコマンドだけ正規表現で許可して、rmやsudoは明示的にfalseにするパターンです。VS Codeでも rm や del といった危険コマンドはブロックされ、常に手動承認になるようになっています。

AGENTS.mdとは何か、なぜ必要か

Agent Modeを使い始めると、すぐぶつかる問題があります。「既存のコーディング規約を無視してコードを書かれた」「何度も同じ指摘を繰り返している」というやつです。

これはCopilotの能力の問題ではなく、リポジトリに「AI向けの取扱説明書」が存在しないことが原因です。人間向けにはREADME.mdを書いてきましたが、AIエージェントが普通に開発に参加するようになった今、AI向けのプロジェクトの常識ファイルが必要になっています。それがAGENTS.mdです。

AGENTS.mdは「Agent instructions」として扱われる指示ファイルで、AGENTS.md（ほか CLAUDE.md や GEMINI.md）のような名前で指定できます。リポジトリルートまたはサブディレクトリに配置でき、プロジェクト固有のビルド手順、テスト方法、コーディング規約などを詳細に指定できます。

GitHub側のカスタム指示ファイルとしては .github/copilot-instructions.md や .github/instructions/**/*-instructions.md、AGENTS.md などが利用できます。従来の .github/copilot-instructions.md はリポジトリのカスタム指示として広く使われていますが、AGENTS.md は「Agent instructions」扱いで、機能ごとのサポート状況に差があるようです。

AGENTS.mdの基本的な書き方

実際に書いてみます。Pythonのウェブアプリプロジェクトを例にします。

# Project Overview
FastAPIを使ったREST APIサーバー。DynamoDBをバックエンドに持つ。

# Tech Stack
- Python 3.12
- FastAPI
- AWS DynamoDB（boto3経由）
- テスト: pytest
- Linter: ruff

# Build & Test
```bash
# 依存関係インストール
uv sync

# テスト実行
pytest tests/ -v

# Lintチェック
ruff check .
```

# Coding Rules
- 型ヒントは必ず書く（mypy strict相当）
- 関数のdocstringはGoogle形式
- DynamoDBアクセスはrepositoryレイヤーに集約する
- ビジネスロジックはserviceレイヤー

# Directory Structure
- src/api/       ... FastAPIルーター
- src/service/  ... ビジネスロジック
- src/repository/ ... DynamoDB操作
- tests/         ... pytestテスト

# Important Notes
- boto3のクライアントは毎回生成せず、シングルトンで使う
- 環境変数はos.environではなくpydantic-settingsで管理

ポイントは「ビルドとテストの実行コマンドを明確に書く」ことです。優れたAGENTS.mdは実際のコード例で良いアウトプットを示し、抽象的な説明を避けます。また「必ずやること・先に確認すること・絶対にやってはいけないこと」という3段階のルールを設けることで、破壊的なミスを防げます。

「ここまで書かないといけないの？」と思うかもしれませんが、最初は少なくてもOKです。最初からすべて用意する必要はなく、まずは基本的な指示から始めて、必要に応じて拡張していくのがおすすめです。使っていくうちに「またこれを指摘された」という経験が積み重なるので、そのたびに追記するスタイルが現実的だと思います。

VS CodeでAGENTS.mdを読み込ませる設定

AGENTS.mdを置いただけで自動的に読まれるケースもあるようですが、どの機能がどの指示ファイルを参照するかはサポート状況に差があるので、確実に効かせたい場合は設定で明示するのが安心です。

{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "file": "AGENTS.md"
    }
  ]
}

この設定により、VS CodeでCopilot Chatを使用する際にもAGENTS.mdの内容が参照されるようになります。Agent Modeだけでなく通常のチャットセッションにも効く可能性があるので、試す価値はあります。

ディレクトリ構成をまとめるとこうなります：

your-project/
├── AGENTS.md                        # Agent向け指示ファイル
├── .vscode/
│   └── settings.json                # Agent Mode設定
├── .github/
│   └── copilot-instructions.md      # リポジトリのカスタム指示ファイル（別途）
└── src/
    └── ...

AGENTS.md と .github/copilot-instructions.md は共存できます。前者がAgent寄り、後者がリポジトリのカスタム指示寄り、という棲み分けで運用している人も多い印象です。正直このあたりの使い分けはまだ自分もふわっとしてる部分があるので、第2回で整理する予定です。

実際にAgent Modeを動かしてみる

設定が終わったら、チャットパネルのモード選択を「Agent」に切り替えて試してみましょう。

最初のお試し用としておすすめのプロンプト：

このリポジトリのREADMEを読んで、
プロジェクトの概要・ビルド手順・テスト手順を
AGENTS.mdとして生成してください

「AGENTS.mdをAGENTS.mdに書かせる」という少し再帰的なやり方ですが、CopilotにAGENTS.mdを生成させることもできます。既存のREADMEやコードをもとに骨格を作ってもらって、そこに自分の規約を追記するのが効率的です。

実行すると、AgentがREADMEを読んでファイルを作成しようとします。ファイル変更の提案が来たら内容を確認してから承認する、このフローを最初のうちは丁寧にやっておくと、「どの範囲まで自律的に動くのか」の感覚が掴めます。

あと一点、個人的に大事だと思ったのが実行前に計画を確認するクセをつけること。Agent Modeは優秀だけど、こちらの意図と微妙にずれた方向に進むことがある。先に計画を見てから実行に移すだけで、手戻りがだいぶ減る、という話。最初の1〜2回は「どんな計画を立てるか見せて」と伝えてから実行させると安全です。

---