【第4回】GitHub Copilot Agent Mode 実践入門 — よくある失敗パターンと本番運用で押さえるべきTips

前回は AGENTS.md と .github/copilot-instructions.md を使ったカスタム指示の設定を紹介しました。シリーズ最終回の今回は、実際に使い込んでいく中で遭遇した失敗パターンと、「これやっておけば良かった」系のTipsをまとめていきます。

正直なところ、第1〜3回でセットアップは完成している。でも「ちゃんと動いてるのに、なんか思ったより使えない」というフェーズが必ずくる。今回はそこを掘り下げます。

よくある失敗パターン5つ

① タスクが大きすぎてAgent Modeが迷子になる

これが一番やりがち。「このプロジェクト全体をリファクタリングして」みたいな指示を出すと、途中でコンテキストが欠落して意図しない変更が混入する。

Agent Modeにはコンテキスト上限があり、大きすぎるタスクは途中で情報が欠落し、意図しない変更が入りやすい。段階的に進めるのが品質面でかなり違う。

悪い例：

src/ 配下を全部 TypeScript に移行して

良い例：

src/utils/ 配下の3ファイルだけ TypeScript に移行して。
まず移行計画を提示してから、OKが出たら実装に進んで

「まず計画を提示してから実装」という一文を入れるだけで暴走がかなり防げる。毎回使ってる。

② Ask / Edit / Agent を使い分けていない

GitHub Copilotには3つのモードがある。Askモードは質問窓口でワークスペース全体のコンテキストを踏まえた回答が得られ、Editモードは指定ファイルへのインライン編集、Agent Modeはファイル作成・編集・ターミナル実行・エラー自己修復まで自律的に行う。

よくある失敗として、全部Agent Modeでやろうとしてプレミアムリクエスト（Proプランで月300回）を浪費するケースがある。ちょっとした質問やコードの説明はAskモードで十分で、そっちは消費量が違う。気づかないうちに月の上限に当たって「あれ？」となるのはこれが原因だったりする。

③ セッションが長くなりすぎる

Agent Sessionが長くなるとコンテキストが溢れることがある。タスクを小さく分割するか、/clear でセッションをリセットしてから継続するのが良い。

1時間同じスレッドで作業し続けて、後半からAgentの返答が急にぼんやりしてきた経験がある。多分コンテキスト溢れだ。定期的にリセットするのが地味に重要。

④ git の変更内容を確認せずにいる

Agent Modeはgit commitまで自動実行できるが、git diffやgit logで変更内容を必ず確認してからpushすること。

これは本当に怖い。Agent Modeは便利すぎて「ありがとう、LGTM」の気持ちになってしまうけど、自律実行ゆえに想定外の変更が混じることがある。差分確認は毎回やる、という習慣を早めに作っておいたほうがいい。Cursorを普段使いしているのでgitの差分確認がUIで見やすくて助かってる。

⑤ 組織導入でポリシー設定を忘れる（チーム向け）

個人利用だとあまり関係ないが、チームに展開するケースで刺さる。

Copilot Business/Enterpriseでは、管理者がポリシーや組織設定（例：拡張機能ツールの制限など）を適切に設定しないと、環境によってはAgent Modeが使えないことがある。「GitHubでCopilot Business契約したからそのまま配布」という進め方をすると、展開後に「使えない」という問い合わせが発生する。組織設定でContent exclusions・モデル選択ポリシー・Agent mode enabledを事前に設定するのが正しい順番。

本番運用で押さえておきたいTips

AGENTS.md でエージェントのルールをプロジェクトに持たせる

プロジェクトルートに AGENTS.md を置くと、Copilotがチャット要求の実行時に自動で読み込み、プロジェクト固有のルールに従って動作する。

.github/copilot-instructions.md と AGENTS.md は自動適用されるが、AGENTS.md はエージェント関連の指示として使うのが向いている。前回の記事で copilot-instructions.md は設定したと思うので、エージェント系の機能を使い始めたら AGENTS.md も追加するとより細かく制御できる。

AGENTS.md に書いておくと効く内容の例：

## コーディング規約
- 関数は必ず型アノテーションを付ける
- テストは pytest を使う
- ログは print ではなく logging モジュールを使う

## やってはいけないこと
- 既存のテストを削除しない
- main ブランチへの直接コミットは禁止
- 外部 API キーをコードに直書きしない

MCPと組み合わせて「社内専用Copilot」に近づける

MCP（Model Context Protocol）はAnthropic発のオープン仕様で、JSON-RPC 2.0でホスト（Copilotなど）とサーバー（外部ツール群）を会話させる。VS Code Copilot Agent Modeから一番使われるのは「Tools」だ。

.github/copilot-instructions.md と組み合わせることで「自社専用Copilot」に近い動作が実現できる。MCPの設定ではまず少数の実績あるサーバーから始めて、徐々に増やしていくのが推奨されている。全部盛りで始めると何が効いているかわからなくなるので、1〜2個ずつ試すのが現実的だ。

.vscode/mcp.json の基本形：

{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

モデルは用途で使い分ける

Copilotは複数のモデルを選べ、ClaudeやGPT系、Geminiなどが選択肢に入っている。用途によってモデルを使い分けるのが効率的だ。

個人的な使い分けのイメージはこんな感じ：

• 大規模リファクタリングや複雑な設計相談 → 高品質モデル（クオリティ重視）
• 日常的なコード修正・テスト追加 → 軽め〜中量級モデル（コスパよし）
• 単純な補完や説明 → そもそもAgent Modeを使わない

プレミアムリクエストの消費はモデルによって異なるので、重いタスク以外で重いモデルを使い続けるのは勿体ない。

autoApprove系の設定は慎重に

settings.jsonで設定できる項目の中に、ターミナルコマンドやファイル変更を自動承認するオプションがある。

// .vscode/settings.json
{
  "chat.tools.terminal.autoApprove": {
    "enabled": false
  }
}

ターミナルの自動承認を有効にすると作業は速くなるが、意図しないコマンドが実行されるリスクがある。ローカルの使い捨て環境なら許容範囲かもしれないが、本番に近い環境では慎重に運用したほうがいい。危険コマンドを弾くためのdeny/allowルールを用意できるので、そこを詰めるのも有効。

Coding AgentとAgent Modeは別物と理解する

これ、最初に混乱したポイント。

Agent ModeはIDEのチャット内でリアルタイム実行する機能であり、Copilot Coding AgentはGitHub Issues経由でバックグラウンドにPRを作成する非同期型の別機能だ。

簡単に言うと：

• Agent Mode：VS Code の中でリアルタイムに対話しながら作業する
• Coding Agent：GitHub の Issue にアサインするとバックグラウンドで勝手にPRを作ってくる

Coding Agentはアップデートで挙動が変わることがあり、最近はより「テストや検証を回してからPRを出す」方向に寄ってきている。Issueを投げておけば裏で動いてくれるので、Agent Modeで別の作業をしながら並行処理できる。

シリーズを振り返って

全4回を通じて、Agent Modeのセットアップから実務での使い込み方まで書いてきた。

タスクの複雑さと自律度のバランスを見極めて使い分けるのが、Agent Mode活用の要点だ。単純な補完にAgent Modeを使う必要はなく、AGENTS.mdやAgent SkillsでチームのワークフローをAIに覚えさせていくと「個人の生産性ツール」から「チームの共有インフラ」に昇格していく感じがある。

Agent Modeを使い始めて一番変わったのは、「作業を細かく分解して渡す」習慣がついたこと。AIに任せるために人間側の整理が上手くなる、という副作用があった。