コンテキストインジェクション技法 — AIに最適な情報を最適なタイミングで

AIエージェントの精度は、与える情報の質とタイミングで決まる。コンテキストウィンドウは有限なリソースであり、「何を」「いつ」注入するかが設計の肝になる。

4つの注入方法と使い分け

方法	タイミング	容量目安	用途
CLAUDE.md	毎セッション自動	1000行以内推奨	プロジェクトルール・禁止事項
Skills	オンデマンド（/skill名）	各500行以内	専門知識・手順書
SessionStart Hook	起動時・コンパクション後	動的に変化	最新状態の注入
@ファイル参照	ユーザー手動指定	ファイルサイズ依存	特定ファイルの精読

CLAUDE.mdによる常時注入

プロジェクトルートのCLAUDE.mdは毎セッション冒頭に自動読み込みされる。

# CLAUDE.md
## プロジェクト概要
- TypeScript + Next.js 15
- テストフレームワーク: Vitest
- デプロイ先: Vercel

## コーディングルール
- 型定義は必ずinterfaceで書く（typeは禁止）
- console.logはcommitに含めない
- エラーハンドリングは必ずResult型で返す

注意: CLAUDE.mdが肥大化するとコンテキストを圧迫する。1000行を超えたらSkillsに分離する。

Skillsによるオンデマンド注入

.claude/skills/にMarkdownファイルを配置すると、/skill名で必要な時だけ読み込める。

# deployment.md
## デプロイ前チェックリスト
1. npm run build がエラーなく完了すること
2. npm run test が全通過すること
3. 環境変数が.env.exampleと一致すること
4. CHANGELOG.mdが更新されていること

SessionStart Hookによる動的注入

起動時とコンパクション後に最新の状態情報を自動注入する。

{
  "hooks": {
    "SessionStart": [
      {
        "command": "python scripts/inject_context.py",
        "timeout": 10000
      }
    ]
  }
}

inject_context.pyの実装例:

import subprocess, datetime

branch = subprocess.check_output(
    ["git", "branch", "--show-current"]
).decode().strip()

diff_stat = subprocess.check_output(
    ["git", "diff", "--stat"]
).decode().strip()

now = datetime.datetime.now().isoformat()

print(f"[SESSION_CONTEXT]")
print(f"TIME: {now}")
print(f"BRANCH: {branch}")
print(f"UNCOMMITTED: {diff_stat or 'なし'}")

Hookのstdout出力がそのままコンテキストに注入される。

@ファイル参照による精密注入

会話中に@ファイルパスで特定ファイルを直接コンテキストに追加する。

@src/lib/auth.ts このファイルの認証ロジックにバグがあるので修正して

大きなファイルはコンテキストを圧迫するため、必要な部分だけを参照する。

タイミング比較と選択基準

セッション開始
  ├─ CLAUDE.md 自動読込（常に）
  ├─ SessionStart Hook 実行（常に）
作業中
  ├─ /skill名 でSkills読込（必要時）
  ├─ @file でファイル参照（必要時）
コンパクション発生
  ├─ CLAUDE.md 再読込（自動）
  └─ SessionStart Hook 再実行（自動）

コンパクション（コンテキストの圧縮）が発生すると、会話履歴は要約されるがCLAUDE.mdとSessionStart Hookは再注入される。つまりこの2つは「絶対に失われない情報」の置き場所になる。

コンテキスト管理のベストプラクティス

静的ルールはCLAUDE.md、動的状態はSessionStart Hookに分離する
専門知識はSkillsに切り出し、必要な時だけ呼ぶ
1セッションで使うコンテキスト量を意識する: 全部入れると肝心の作業領域が圧迫される
コンパクション耐性を考慮する: 失われてはいけない情報はCLAUDE.mdかHookに置く

コンテキストインジェクションは「情報を詰め込む技術」ではなく「最小限の情報で最大の精度を得る技術」である。