🔥 GitHub Copilot なにもしてないのにこわれた 2 〜system prompt を約 90% 減らした話〜

こんにちは、自作の カスタムエージェント を呼んだ瞬間に Copilot が「何を進めますか？」マシーンに退化して、また冷や汗をかいたアーキテクトのやまぱん！です 😇
補足コメントや質問、いいね、拡散、ぜひお願いします 🥺！
間違っていたら 優しく 教えてください！

TL;DR

• VS Code のカスタムエージェント (.agent.md) を起動した瞬間だけ、Copilot が指示を聞かなくなる現象に遭遇しました
• 原因は .agent.md や .instructions.md 内の Markdown リンクを VS Code が再帰的に辿って、リンク先の本文ぜんぶをシステムプロンプトに突っ込んでくることでした
• 結果、カスタムエージェント起動時だけ system prompt が 99 KB → 950 KB（約 9 倍 / 約 23 万トークン） に膨張し、長文プロンプトで中間の指示が埋もれる lost-in-the-middle が起きていました
• 直したのは 設定 1 行。chat.includeReferencedInstructions: false で system prompt は元の 99 KB に戻り、ファイルは一切書き換えずに直りました
• 2026/05 の Azure Travelers 金沢 LT「GitHub Copilot なにもしてないのにこわれた」では applyTo 明示で止まりましたが、今回は もう片方の対策（Markdown リンク自動展開を設定で止める）が効きました。経路が違う対策なので両方やっておくと安定します 🙇

先に結論

.vscode/settings.json か User Settings に chat.includeReferencedInstructions: false を 1 行入れるだけ で、.github/agents/・.github/instructions/・.github/skills/ の Markdown リンクを書き換えることなく、カスタムエージェント起動時の system prompt が約 90% 縮みました。

VS Code 公式ドキュメントによれば、この設定は 「Markdown link で参照された instruction files を chat requests に自動追加するか」 を制御します。私の環境ではこれが実質有効になっていて、リンクを片っ端から食べていました。設定例と実測値は後述します。

前回 LT（Azure Travelers 金沢）の続きです 🎬

この話、2026 年 5 月に Azure Travelers 金沢 で LT した「GitHub Copilot なにもしてないのにこわれた」の続編です。

• スライド: copilot-context-explosion-LT (Docswell)

Japan Azure Travelers は「いろんな地方に行って、その土地のコミュニティと一緒に Azure イベントをやろう」という有志コミュニティです。これまで神戸・山形・福岡・沖縄・愛媛・東京・仙台・金沢を旅してきて、次回は 2026/08/01（土）の広島の旅。Azure 好きな人、地方コミュニティに興味ある人はぜひ覗いてみてください。

• connpass: https://jat.connpass.com/
• YouTube: https://www.youtube.com/@JapanAzureTraveler
• Discord: https://discord.gg/qJzGk76WmK

LT のときに整理した容疑者と対策はこうでした。

LT 時点で挙げた容疑者	LT での対策
第 1 容疑者：Markdown リンク自動展開（参考：vscode#279045）	AGENTS.md / copilot-instructions.md を退避して切り分け
第 2 容疑者：LLM 駆動の read_file	applyTo 未指定でも description + パスの list が LLM に渡って勝手に読みに行く。applyTo を明示

LT 当時は 第 2 容疑者の方が直接効いたので、applyTo をちゃんと書く運用にして一段落させていました。

ところが今回、また別ワークスペースで同じ症状が出たんですが、applyTo はもうそれなりに書いてある状態でした。それでもカスタムエージェントを呼ぶと system prompt が爆発する。

そこで今度は 第 1 容疑者（Markdown リンク自動展開）の方を本気で追い直した のがこの記事です。結論を先に言うと、こちらは 設定 1 行で完全に止められて、約 90% の削減効果がありました。

つまり LT の対策と今回の対策は どちらか一方ではなく、両方やっておくと事故りにくい 関係です。

• applyTo を明示する → LLM が「description だけ見て」勝手に read_file するのを抑える
• chat.includeReferencedInstructions: false → Markdown リンク経由の再帰添付を止める

抑える経路が違うんですよね。

何が起きたか

舞台は、私が 半年くらいかけてそれなりに作り上げてきたワークスペースです。.github/agents/ に自作エージェントが 22 個、.github/instructions/ が 41 本、.github/skills/ の SKILL が 75 ファイル。合計約 1.58 MB のカスタマイズ資産がある状態でした。長く育てた愛着のあるやつ、と言えば伝わるでしょうか。

そこで起きた症状はかなりピンポイントでした。

• カスタムエージェント（自作の .agent.md）を呼んだときだけ、ちゃんと書いた指示が無視される
• 返ってくるのは「何をしましょうか？」「以下のうちどれを進めますか？」型の汎用メニュー
• 通常チャット（エージェント未指定）は 同じワークスペース・同じ時刻でも問題なく動く
• 体感としては「ちょっと前までは普通に動いてたのに」

ここで嫌な感じがしたんですよね。GitHub の障害ステータスは Operational。LT の経験から「これ、また自分で盛ったやつだ」とすぐ思いました。資産を育てた結果、自分の足を踏んだ気配がします。

最初に立てた仮説（で、外した）

まず疑ったのは「LT で効いた対策が外れてるんじゃないか」でした。.instructions.md 群の frontmatter に applyTo がちゃんと書いてあるかをひと通り確認 → 書けていました。

じゃあ別の原因だなと、次に疑ったのは Agent Skills の量。このワークスペースの .github/skills/ は約 446 KB / 75 ファイル。SKILL 群が常時露出していて重そうに見えます。「これだろ」と思って、chat.agentSkillsLocations で skills の読み込み場所を絞ったり、SKILL ファイルそのものを一時退避したりして、常時露出の量を実際に減らしてみました。

…結果、改善せず 😇

これは小さなショックだったんですが、反証としてはかなり強い情報でした。「skills の量も今回の主因ではない」という事実が確定したからです。

真犯人を探す：debug-logs を見る

ここで、VS Code Copilot Chat の debug-logs を覗くことにしました。

VS Code は session ごとに、こんなファイルを残しています。

workspaceStorage/<id>/GitHub.copilot-chat/debug-logs/<session>/
  ├─ main.jsonl            # LLM リクエスト単位のメトリクス（inputTokens など）
  ├─ system_prompt_0.json  # 構築されたシステムプロンプト全文（添付込み）
  └─ ...

system_prompt_0.json を、通常チャットと カスタムエージェント起動時で比較するのが今回の主役です。

計測結果

同じワークスペース・同じ時間帯で比べたら、こうなりました。

セッション種別	system_prompt サイズ	初手 inputTokens	添付数
通常チャット	99.5 – 113.3 KB	約 40,000	13
カスタムエージェント起動	742 – 955 KB	約 231,000	72

カスタムエージェント起動時だけ、system prompt が 約 8～9 倍 に膨らんでいました。そのとき送ったユーザーメッセージ自体は 約 5,000 トークン しかなかったので、膨張させていたのはユーザー入力ではなく、Copilot 側が起動時に勝手に積み込んでいた何か でした。

添付の正体は「Markdown リンクの到達閉包」

到達閉包 (reachability closure) とは「ある起点からリンクを辿り続けて到達できる全ファイルの集合」のことです。

system_prompt_0.json の <attachment filePath="..."> ブロックを全部抜き出して、通常チャットの 13 添付と差分を取りました。

カスタムエージェント側だけ増えていた 59 添付の内訳がこれです。

種別	件数	由来
.instructions.md 本文	27	リンク辿り
Skills の SKILL.md / references	22	リンク辿り
.agent.md 本文	8	リンク辿り
.prompt.md / その他	2	リンク辿り

ここで一番おもしろかったのは、.agent.md が「全 22 個中 8 個」だけ入っていたことです。

VS Code が「カスタムエージェント全部を自動列挙する」仕様なら、22 個全部が入っていてもおかしくないんですよね。でも実際は 8 個。これは roster（名簿）添付ではなく、リンクで到達できる .agent.md だけが添付されている ことを意味します。

つまり、機構はこれです。

起動エージェントの本文 → そこに書かれた Markdown リンク → リンク先 → そこに書かれた Markdown リンク → ... と 再帰的に辿って、辿れたファイルの本文を全部システムプロンプトに添付する。

念のため、エージェント定義から Markdown リンクだけを辿って静的に到達閉包を計算したら、83 ファイル / 846 KB / 約 217k トークン になりました。実測の 231k とほぼ一致。正体はほぼ確定です。

なぜ「指示が無視される」のか

system prompt 23 万トークンの中に、ユーザー指示 5 千トークンが埋もれます。さらに autonomy 系の「受け身メニューを返すな」みたいな制御ルールも、大量の添付本文の海に薄まります。

結果、モデルがどこにフォーカスすべきか判断できなくなり、いちばん安全側のテンプレート応答＝「何を進めますか？」に倒れます。

指示が無視されたのではなく、モデルが指示を抱えきれなかった状態ですね。長文 LLM でおなじみの lost-in-the-middle（長いプロンプトで中間の情報がスルーされやすくなる現象）です。

skills 削減が効かなかった理由

最初の仮説「skills が重い」が当たらなかった理由も、ここで腑に落ちました。

skills の中身を削っても、たとえば AGENTS.md にこういう 1 行が残っていると：

See [Agent Skills](.github/skills/README.md)

このリンク 1 本だけで、skills/README.md を起点に 23 ファイル・102 KB が再帰的に積まれます。

つまり、ファイル量を削っても、Markdown リンクが生きていればそこから芋づるでした。問題は容量ではなく、参照グラフだったわけです。

解決：設定 1 行で 90% 減

ここで満を持して、chat.includeReferencedInstructions: false を入れます。私の現現在の settings.json には、この 2 行だけ入れています。

// .vscode/settings.json か User Settings
{
  // applyTo 一致の instruction は通常どおり読む（既定 true）
  "chat.includeApplyingInstructions": true,
  // ★ 今回の本命：Markdown リンク参照の再帰追加を止める
  "chat.includeReferencedInstructions": false,
}

それぞれの役割はこうです。

設定	役割	今回での効き方
chat.includeApplyingInstructions	applyTo 一致 instruction の自動追加	通常チャットの土台 13 添付（40k）
chat.includeReferencedInstructions	Markdown link 参照の再帰追加	カスタムエージェント起動時の +59 / +217k

設定変更前後の比較がこれです。

指標	カスタムエージェント（変更前）	カスタムエージェント（変更後）	通常チャット（参考）
system_prompt サイズ	950.5 KB	99.5 KB	113.3 KB
添付数	72	13	13
削減率	—	約 90% 減	—

カスタムエージェントの system prompt が、通常チャットと 同じレベルまで落ちました。応答も普通に戻り、指示通りに動くようになりました。

数字だけじゃなく、体感としても GitHub Copilot Chat の応答がはっきり速くなりました。最初のトークンが返ってくるまでがサクッと早くなって、「あ、今までこれ毎リクエスト 23 万トークン読ませてたんだな…」と、過積載っぷりが体感でもわかるレベルでした 🐤

しかも嬉しい副次効果として、添付数が 完全に通常チャットと同じ 13 まで戻ったので、「instruction の再帰を止めると、そこから芋づるで引かれていた .agent.md も SKILL も連動して止まる」ことがわかりました。設定 1 つで連鎖全体が止まるんです。

そして地味に大事なのが、この設定は ソース上の Markdown リンクをそのまま残せる こと。人間のナビゲーション（クリックして移動）は維持されるし、README から SKILL.md へのリンクも生きるし、エージェントが必要なら read_file で都度読みに行けます。止まるのは 「起動時の自動先読み」だけ という、ちょうどいい効き方でした。

「ちょっと前までは動いてた」の説明

体感の「最近壊れた」も、ちゃんと説明できます。

機構自体は前から存在していました。VS Code 1.99（2025 年 3 月版）で .copilot-instructions.md の nested link resolution（リンク先をネストして解決する仕組み）が入り、その後 1.106（2025 年 11 月版） で custom agent (.agent.md) が正式に登場して同じ仕組みが乗ったあたりが起点です。

ただ、当時は添付対象がそこまで重くなかったので、再帰しても context window に収まっていました。

それが、半年かけてエージェント・instruction・SKILL を増やし、合計約 1.58 MB のカスタマイズ資産を持つ頃には… 閉包合計が 23 万トークン、エージェント起動時だけ閾値を超えた 結果でした。「最近変わった」のではなく、「自分の盛り方が閾値を超えた」だけだったんですよね 😇

実務での診断順、アップデート版

LT 時の経験も踏まえて、今の私の診断順はこうです。対策はどれか 1 つではなく、上から順に効く分だけ重ねていくイメージです。

1. applyTo 未指定を埋める（LT で効いた方）：LLM が勝手に read_file するのを抑える
2. 設定で再帰添付を止める（今回効いた方）：chat.includeReferencedInstructions を false にして Markdown リンク経由の自動展開を止める
3. debug-logs で測る：system_prompt_0.json のサイズと添付数を、通常チャットとエージェントで比較する
4. applyTo 駆動の常時添付を確認：通常チャットの土台 40k がどこから来ているかは chat.includeApplyingInstructions 側の話。重ければ applyTo: "**" の instruction 本数と長さを見る
5. ファイル軽量化は最後：内容を消すより、構造（applyTo の指定・リンクの貼り方）を見直す方が効くことが多い

LT のときは 1 番だけで治ったんですが、今回は 1 番が済んでいてもダメで、2 番が決め手でした。経路が違う対策なので両方やっておくと安定する、というのが今回の学びです。

設計の含意

chat.includeReferencedInstructions: false を入れる前提に立つと、こういう書き方が安全になります。

• 必須の判断ルールは、applyTo で scoped された instruction 本体に残す
• 「詳細は別ファイル参照」とリンクだけ書いて本文を空にする構成は避ける（false 下では読まれないので）
• リンクは 補助的な深掘り先 として扱う
• 入口ファイル（copilot-instructions.md / AGENTS.md）は薄く保つ

ちなみに、チームポリシーで設定変更が難しいときは、Markdown link をコードスパンに変えると VS Code がリンクと解釈しにくくなるのも有効です。

<!-- これは VS Code が「リンク」と解釈して再帰しがち -->

See [AGENTS.md](../../AGENTS.md)

<!-- これならただのテキスト扱いになりやすい -->

Human reference only: `AGENTS.md`

ただし、私の実測では 設定 1 行で十分でした。リンクをいじる必要はありませんでした。

参考：もう一段絞りたいときの関連設定

ここから先は 必須ではない参考情報 です。チームで配るリポジトリだったり、ホーム配下にもいろいろ置いてある人、ネストワークスペースを使う人など、もう一段コンテキストを絞りたい場合に使える周辺設定をまとめておきます。

設定	役割	使いどころ
chat.useCustomizationsInParentRepositories	親リポジトリの customizations も探索するか	既定 false。ネスト構成では明示しておくと事故りにくい
chat.instructionsFilesLocations	.instructions.md を探す場所	余計な場所を false にしておくと未使用資産を踏まない
chat.promptFilesLocations	.prompt.md を探す場所	同上
chat.agentFilesLocations	.agent.md を探す場所	同上。ホーム配下の試作 agent を持ち込みたくない時に有効
chat.useAgentSkills	Agent Skills を有効化するか	Skills を使っていないなら false で迷わず軽量化
chat.agentSkillsLocations	Skills を探す場所	グローバル skills を抑止すると常時露出をかなり減らせる

たとえば「グローバル skills は読みたくない、このリポジトリの skills だけ使いたい」みたいな絞り込みはこんな感じでできます。

{
  "chat.agentSkillsLocations": {
    ".github/skills": true,
    "~/.copilot/skills": false,
    "~/.claude/skills": false,
  },
  "chat.useCustomizationsInParentRepositories": false,
}

ポイントは、「設定で止められるなら、ファイルを消す前に設定で止める」 ことです。instruction や skill の中身を一生懸命減らしても、読み込み経路を絞っていなければまた静かに膨らみます。先に蛇口を絞っておく方が長持ちします。

おまけ：この調査、Copilot Chat が手伝ってくれました 🐤

ちなみにこの記事の調査、自分で system_prompt_0.json を grep して回ったわけではなく、Copilot Chat にやってもらいました。皮肉ですよね、調査対象の Copilot 自身が調査を手伝ってくれる構図。

使ったのはこの 2 つです。

• Developer: Show Chat Debug View：コマンドパレットから開ける Chat Debug View。panel/editAgent ノードを開くと、その request で実際に送られた system prompt（添付ファイル含む）の中身を全部見られます。今回の添付内訳分析（27 instructions / 22 skills / 8 agents / 2 prompts）はここから抜きました
• /troubleshoot + #session：チャットで /troubleshoot と打って #session でセッションを参照すると、Copilot 自身が「なぜカスタム instructions が無視された？」みたいな質問に対して、自分の動作ログを解析して答えてくれます。
  使うには github.copilot.chat.agentDebugLog.enabled と ...fileLogging.enabled を有効化しておく必要があります

「Copilot が壊れた」って騒いでるときに Copilot に「お前なんで壊れてるの？」って聞いて答えてもらったわけで、なんとも 2026 年っぽい体験でした。

公式の手順はこちら: VS Code Wiki - Copilot Issues / Custom Instructions Logs

まとめ

2026/05 LT「GitHub Copilot なにもしてないのにこわれた」で扱った Copilot のコンテキスト爆発問題、その続編として 「もう片方の対策」 が見つかった、というのが今回の話でした。

• LT の対策：applyTo を明示 → LLM 駆動の read_file を抑える
• 今回の対策：chat.includeReferencedInstructions: false → Markdown リンク経由の再帰添付を止める
• どちらも 抑える経路が違うので、両方やっておくと事故りにくい
• 今回は LT 当時と違って、設定 1 行で system prompt が約 90% 減（950 KB → 99.5 KB）まで定量的に確認できた

LLM エージェントのコンテキスト設計って、量より構造なんだなあ、と今回でだいぶ腹落ちしました。

今回の教訓（Copilot を盛りすぎる人向け）

カスタマイズ資産を育てている人が、今後同じ目に遭わないための 3 つです。

1. .instructions.md の frontmatter はちゃんと書く 🔑
   applyTo で適用範囲を明示する。description も短く正確に書く。これだけで「LLM が description だけ見て勝手に read_file する」ルートを抑えられます。
2. .agent.md も同じく frontmatter を整える
   description / tools / 必要なら user-invocable / disable-model-invocation を明示。読者から見て「いつ起動されるべき agent か」が定義で分かる状態にしておく。
3. VS Code を使うなら Markdown リンクの自動展開もチェック
   chat.includeReferencedInstructions: false を入れる。ベストエフォートで読み込ませると、リンクを辿って全部読みに行きます。資産を育てている人ほど、ある日突然 system prompt が爆発します。

3 つに共通するのは、「Copilot が読みに行く経路を、自分で明示的に絞る」ことです。盛れば盛るほどこれが効きます。

---

似たような症状（カスタムエージェントだけ指示が通らない、何を聞いてもメニュー応答になる）に心当たりがある方は、まず applyTo を埋めて、それでも重ければ今回の 1 行を試してみてください。どちらでもダメだったら別の問題なので、また一緒に調査させてください 🙏

参考

• 2026/05 LT「GitHub Copilot なにもしてないのにこわれた」（Docswell）

• VS Code Copilot Settings リファレンス（chat.includeReferencedInstructions / chat.includeApplyingInstructions）

• VS Code custom instructions

• VS Code Custom Agents

• VS Code 1.99 リリースノート（nested link resolution が入った版）

• vscode#279045 — Markdown リンク自動展開の挙動（参考）