LLMエージェントのコンテキスト削減でハマった穴 — 「ファイルを分ければ減る」という錯覚と常時ロード予算

LLM エージェント（ Claude Code や Cursor 等）を運用するプロジェクトで、エージェントへの指示書（ CLAUDE.md や AGENTS.md ）にルールを追記し続けると、コンテキストウィンドウが圧迫され、エージェントが重要な規律を無視し始める「コンテキスト汚染」が発生します。

この問題に対処するため「指示書を複数のファイルに分割・整理する」アプローチが一般的ですが、ここには見落としがちな 「ファイルを分けてもコンテキストは1行も減らない」 という罠が存在します。

本記事では、実際に指示書移設を行ったもののコンテキスト削減効果が0行に終わった失敗実例をもとに、スコープの仕組みと定量的上限（ Context Budget ）を管理する自動検証ガードレールの構築手法を解説します。

1. 導入: 「ファイルを分ければ軽くなる」という錯覚

エージェント指示書の肥大化に直面した開発者の多くは、「1つの大きな指示書を複数のサブファイルに切り出せば、コンテキスト消費量を抑えられる」と考えます。

しかし、エージェントツールの仕様を理解せずにファイル分割を行うと、単にファイル数が増えただけで、エージェントがセッション開始時にインジェストするトークン量は一切変わらないという現象が起こります。

Claude Code の公式ドキュメントでは、 CLAUDE.md はセッション開始時に毎回自動的に読み込まれる永続的指示ファイルであり、ルールが多すぎると指示遵守率の低下を招くため、簡潔（目安として 150〜200 行以下）に保つことが推奨されています ¹。また、エージェント指示書のオープン規格である AGENTS.md でも、人間用の README.md と分離して明確かつ決定論的なルールを整理する重要性が示されています ²。

重要なのは「ファイル単位の行数」ではなく、「一度に自動インジェストされるスコープの合計行数」です。

2. 失敗実例: オーナープロフィールを移設したのに0行も減らなかった理由

当社社内ハブ（ AI コンサル・開発運用ハブ）の実例をご紹介します。

当時、ルート直下の CLAUDE.md が 263 行まで膨張しており、エージェントが規律を流し読みする傾向が見られました。そこで、CLAUDE.md 内に記述されていた「オーナープロフィール」（27 行）を削除し、新たに作成した CONTEXT.md へ移設しました。

CLAUDE.md 単体の行数は 263 行から 236 行に減ったため、一見するとコンテキストの削減に成功したように見えました。しかし、実効値を計測したところ、 セッション開始時にエージェントがインジェストする常時ロード行数は 338 行のまま 1 行も減っていませんでした。

なぜ削減効果が 0 行だったのでしょうか。原因は、エージェントが起動時にルート直下の CLAUDE.md だけでなく、CONTEXT.md も同一の常時ロードスコープ（自動一括読み込み対象）として処理していたためです。

【移設前】
CLAUDE.md (263行) ＝ 常時ロード合計 338行 (※他ルート共通ファイル含む)

【移設後】
CLAUDE.md (236行) ＋ CONTEXT.md (27行) ＝ 常時ロード合計 338行 (削減量 0行)

「リポジトリ全体の総行数」や「単一ファイルの行数」を定性的に減らしても、 同一の自動ロード枠の中でファイルを移動させただけでは削減効果はゼロ に終わります。

3. 対策①: 常時ロード上限（Context Budget）の策定と自動検証ガードレール

感覚的なファイル分割から脱却するために導入したのが、 「常時ロード行数上限（ Context Budget ）」の定量管理 と、それをスクリプトで計測・検証するガードレールです。

まず、自社プロジェクトの運用規律として以下の明確な行数予算（ Context Budget ）を定義しました。

CLAUDE.md 単体上限: 200 行以内
ルート常時ロード合計上限: 400 行以内（ CLAUDE.md + CONTEXT.md + index.md ）

そして、インデックス生成スクリプト（ Python ）の中に予算計測と自動検証ロジックを組み込みました。

BUDGET_FILE = 200   # CLAUDE.md 単体の上限
BUDGET_ROOT = 400   # ルート常時ロード合計の上限

def always_loaded(index_lines=None):
    """毎セッション自動的に読まれるファイル群の行数を計測"""
    out = []
    for name in ("CLAUDE.md", "CONTEXT.md"):
        p = HUB / name
        out.append((name, len(p.read_text().splitlines()) if p.exists() else 0))
    if index_lines is None:
        p = HUB / "index.md"
        index_lines = len(p.read_text().splitlines()) if p.exists() else 0
    out.append(("index.md", index_lines))
    return out

def build(docs, index_lines=None):
    al = always_loaded(index_lines)
    total = sum(n for _, n in al)
    warn = []
    if dict(al).get("CLAUDE.md", 0) > BUDGET_FILE:
        warn.append(f"CLAUDE.md {dict(al)['CLAUDE.md']}行 > {BUDGET_FILE}")
    if total > BUDGET_ROOT:
        warn.append(f"ルート合計 {total}行 > {BUDGET_ROOT}")
    
    for w in warn:
        print(f"WARN: 常時ロード予算オーバー: {w}", file=sys.stderr)
    return total, warn

このスクリプトに --check オプションを設け、予算オーバー時にはステータスコード 1 で終了するように構成し、ローカルの git フックや CI で常時ロード行数の増加を自動で抑止・警告するガードレールを敷きました。

これにより、CLAUDE.md 単体を 263 行から 151 行へ抑え、常時ロード合計を約 320 行（ 400 行枠内）へ管理することに成功しました。

4. 対策②: 常時ロード枠外への退避と段階的開示（Progressive Disclosure）

常時ロード枠を実際に削減するには、 「常時ロードスコープの外側」にファイルを退避させる 必要があります。

失敗談で取り上げた「オーナープロフィール」の記述は、ルートの CONTEXT.md ではなく、部署サブディレクトリ secretary/owner-profile.md へ再退避させました。

部署配下のサブディレクトリは「ディレクトリスコープ」であり、エージェントがその部署配下の作業を行う時のみオンデマンドでロードされます。常時ロード枠外へ退避させたことで、常時ロード合計は 338 行 → 311 行 へと確実に減少しました。

指示書の構造は、以下の 3 段階で整理・分散させる設計が有効です。

常時ロード枠（ルート: < 400 行）: 全作業で必須となる共通規律・安全制約・主要コマンドのみ。
ディレクトリスコープ枠（サブディレクトリ）: 特定機能や特定部署に閉じた専門ルール（ pm/CLAUDE.md など）。
オンデマンド枠（ Skill / Sub-agent ）: 複雑な手順や特定タスク（ SKILL.md やサブエージェント定義）は、呼び出された時のみ段階的開示（ Progressive Disclosure ）でインジェスト。

5. 対策③: 指示書リファクタリング時の規律脱落を防ぐ「機械的照合」

指示書を大規模に分割・整理する際、もう 1 つの深刻なリスクが 「リファクタリング中に重要な規律が静かに消えること」 です。

当社社内ハブで 142 行のルールを分解・移設した際、移動前のテキストと移動後の全ファイル群を機械的なスクリプトで照合（テキスト差分抽出）しました。

その結果、28 行の差分のうち 26 行は意図的な表現の統一や重複削除でしたが、 以下の 2 行が作業ミスにより静かに消失していた ことが発覚しました。

部署一覧のインデックス表 （全体構造を把握するための基盤情報）
コミット方針:「古い方針に戻さないこと」 （エージェントのリグレッションを防止する重要規律）

定性的な目視確認だけに頼ると、こうした安全制約の脱落を見過ごす危険があります。指示書を分割・移設する際は、移動前後のテキスト照合を行い、意図しないルールの脱落がないかを機械的に検証することが重要です。

6. まとめ: 定性的な分割から定量的 Context Budget 管理へ

エージェント指示書のコンテキスト管理において最も重要なのは、単に「ファイルを分ける」ことではありません。

ファイル数ではなく「常時ロードされるスコープの合計行数」を意識する。
Context Budget（常時ロード上限）を定義し、スクリプトや CI で自動チェックする。
常時ロード枠外（ディレクトリスコープや Skill ）へ段階的開示する構造を作る。

まずは自社リポジトリのエージェント起動時に読み込まれるファイルの常時ロード行数を計測することから始めてみてください。

AI エージェント運用の最適化やコンテキスト設計に関するご相談は、コンタクトフォームよりお気軽にお問い合わせください。