コンテキストエンジニアリング入門
はじめに
記事①ではプロンプト単体の設計技術、記事②ではエージェント(LLM + ツール + ループ)の構築方法を扱いました。
しかし、同じCLAUDE.mdと同じ指示を使っても、エージェントの出力品質がばらつくことがあります。ある日は正確な手順書が出力されるのに、別の日は重要な手順が抜けている。原因はモデルの性能ではなく、「モデルに何を見せているか」 ― つまりコンテキストの設計にあります。
コンテキストエンジニアリングとは、LLMがタスクを解決できるよう、適切なコンテキストを設計・管理する技術です。プロンプトエンジニアリング(記事①)が「1回の指示をどう書くか」の技術であるのに対し、コンテキストエンジニアリングは「エージェントが動いている間ずっと、何を見せ続けるか」を設計する上位概念です。
この記事では、以下の4つを扱います。
- コンテキストエンジニアリングの定義とプロンプトエンジニアリングとの違い
- コンテキストウィンドウの仕組みと制約
- CLAUDE.md設計のベストプラクティス
- 情報設計パターン5選とRAG(検索拡張生成)
記事①の用語(6構成要素、Zero-shot / Few-shot / Chain-of-Thought等)および記事②の用語(エージェントの3要素、Claude Codeの基本操作、CLAUDE.mdの概念)は再説明しません。未読の方は先に①②を読むことを推奨します。
前提条件
この記事は、以下の前提知識を持つ方を対象としています。
- 記事①の内容(プロンプトの6構成要素、3つの基本テクニック)を理解している
- 記事②の内容(エージェントの3要素、Claude Codeの基本操作、CLAUDE.mdの概念)を理解している
- Claude Codeがインストール済みであること(記事②参照)
コンテキストエンジニアリングとは何か
LLMがタスクを解決できるよう、すべてのコンテキストを提供する技術
(”the art of providing all the context for the task to be plausibly solvable by the LLM”)
プロンプトエンジニアリングとの違い
記事①で扱ったプロンプトエンジニアリングとの違いを整理します。
| 観点 | プロンプトエンジニアリング(記事①) | コンテキストエンジニアリング(本記事) |
|---|---|---|
| 対象範囲 | モデルへの「指示文」の最適化 | モデルが受け取る「トークン全体」の最適化 |
| 時間軸 | 単一のやり取り(1回のリクエスト) | 複数ターン・長期間のエージェント操作 |
| 焦点 | 「何を言うか」 | 「モデルが何を知っているか」 |
| 関係性 | コンテキストエンジニアリングの一部 | プロンプトエンジニアリングを包含する上位概念 |
プロンプトエンジニアリングはコンテキストエンジニアリングのサブセット(部分集合)です。記事①で学んだ「指示の書き方」は引き続き重要ですが、エージェントを運用する際には、指示文以外の情報 ― 会話履歴、メモリ、ツール定義、外部データ ― も含めた全体設計が必要になります。
| プロンプトエンジニアリング(記事①) | コンテキストエンジニアリング(本記事) | |
|---|---|---|
| 対象範囲 | モデルへの「指示文」 | モデルが受け取る「トークン全体」 |
| 含まれる要素 | 役割 / タスク / 制約 / コンテキスト / 出力形式 / 例 | 左記に加え、会話履歴 / 長期メモリ / ツール定義 / RAG / 出力構造 |
| 関係性 | コンテキストエンジニアリングの一部(サブセット) | プロンプトエンジニアリングを包含する上位概念 |
Philipp Schmidは「エージェントの失敗は、もはやモデルの失敗ではなく、コンテキストの失敗である」と指摘しています(原文の趣旨に基づく要約)。モデルの性能を上げるだけでなく、モデルに見せる情報を適切に設計することが、エージェントの品質向上に直結します。
コンテキストを構成する7つの要素
Andrej KarpathyとPhilipp Schmid(Google DeepMind、元Hugging Face)の整理を参考に、LLMが応答生成時に「見る」コンテキストの構成要素を一覧にします。
| # | 要素 | 説明 | 記事①②との対応 |
|---|---|---|---|
| 1 | システムプロンプト / 指示 | 行動ガイドラインと制約 | 記事①の「役割・制約」 |
| 2 | ユーザープロンプト | 即時のタスク指示 | 記事①の「タスク」 |
| 3 | 状態・履歴 | 会話メモリと過去のやり取り | 記事②の「ループ」で蓄積 |
| 4 | 長期メモリ | 永続的な設定・学習済みの知識 | 記事②の「CLAUDE.md / Auto Memory(自動メモリ)」 |
| 5 | 取得情報(RAG) | 外部データソースからの動的取得 | 本記事で新規に扱う |
| 6 | 利用可能なツール定義 | モデルが呼び出せる関数の仕様 | 記事②の「ツール一覧」 |
| 7 | 出力構造の指定 | 応答フォーマット(JSON等) | 記事①の「出力形式」 |
LLMが応答を生成する際に参照する「コンテキストウィンドウ」は、以下の7要素で構成されます。
- システムプロンプト / 指示 ― 行動ガイドラインと制約(記事①の「役割・制約」)
- ユーザープロンプト ― 即時のタスク指示(記事①の「タスク」)
- 状態・履歴 ― 会話メモリと過去のやり取り(記事②の「ループ」で蓄積)
- 長期メモリ ― 永続的な設定・学習済みの知識(記事②の「CLAUDE.md / Auto Memory」)
- 取得情報(RAG) ― 外部データソースからの動的取得(本記事で新規に扱う)
- ツール定義 ― モデルが呼び出せる関数の仕様(記事②の「ツール一覧」)
- 出力構造の指定 ― 応答フォーマット(記事①の「出力形式」)
これら7要素の質と構成を設計するのがコンテキストエンジニアリングです。
記事①②で学んだ要素の多くはすでにコンテキストの一部です。本記事ではこれらを統合的に設計する視点を加えます。
コンテキストウィンドウの仕組みと制約
コンテキストウィンドウとは ― LLMの「作業机」
コンテキストウィンドウとは、LLMが1回の応答生成時に参照できるトークンの総量です。「作業机」に例えると、机の広さ(容量)は決まっており、資料を載せすぎると整理しきれなくなります。
現在のClaude主要モデルのコンテキストウィンドウサイズは以下のとおりです。
| モデル | 標準コンテキスト | 拡張(ベータ) | 最大出力 |
|---|---|---|---|
| Claude Opus 4.6 | 200Kトークン | 1Mトークン | 128Kトークン |
| Claude Sonnet 4.6 | 200Kトークン | 1Mトークン | 64Kトークン |
| Claude Haiku 4.5 | 200Kトークン | なし | 64Kトークン |
出典: Models overview – Anthropic
コンテキストロット ― 「大きい器」の落とし穴
コンテキストウィンドウが大きくなっても、中に入れた情報の質が問われます。
Anthropicは「Effective context engineering for AI agents」(2025年9月)の中で、トークン数の増加に伴い精度と回想能力が低下する現象に言及しています。業界ではこの現象をコンテキストロット(Context Rot)と呼びます。「コンテキストに何が入っているか」は「どれだけ入るか」と同じくらい重要です。
インフラ業務での例を挙げます。障害対応中に過去のSSH接続セッションのログを全量コンテキストに入れると、直近のエラー情報が大量のログの中に埋もれ、エージェントの検出精度が下がります。必要な範囲に絞ってログを読み込む方が、正確な分析結果が得られます。
出典: Effective context engineering for AI agents – Anthropic
コンパクション ― コンテキストの圧縮
Claude Codeでは、会話が長くなるとコンテキストウィンドウが圧迫されます。これに対処するのがコンパクション(圧縮)です。
手動コンパクション(/compact):
- 現在の会話履歴全体を要約し、コンテキストを大幅に圧縮する
/compact <指示>の形式で保持したいコンテキストを指定可能(例:/compact APIの変更点に集中して)- 詳細なコンテキストは失われるが、作業の骨格は保持される
自動コンパクション:
- コンテキストウィンドウの制限に近づいた時点で自動トリガー
- 作業中のファイル、決定事項、現在のタスク状態を優先的に保持
出典: Best Practices for Claude Code – Anthropic
CLAUDE.md設計のベストプラクティス
記事②ではCLAUDE.mdの概念と基本的な書き方を扱いました。本記事では、Anthropic公式の推奨に基づく設計のベストプラクティスに踏み込みます。
書くべきこと・書かないこと
CLAUDE.mdに「何を書くか」の判断基準は明確です。
| 書くべき | 書かないこと |
|---|---|
| Claudeが推測できないBashコマンド | コードを読めばわかること |
| デフォルトと異なるスタイルルール | 標準的な言語規約 |
| テスト手順と推奨テストランナー | 詳細なAPIドキュメント(リンクで代用) |
| プロジェクト固有のアーキテクチャ決定 | 頻繁に変わる情報 |
| 開発環境の特殊事項(環境変数等) | ファイルごとのコードベース説明 |
| 非自明な振る舞いやよくある落とし穴 | 「クリーンなコードを書く」等の自明な事項 |
サイズ目標は1ファイルあたり200行未満です。200行を超える場合は、後述の .claude/rules/ への分割を検討してください。
/init コマンドを実行すると、Claude Codeがプロジェクトの構成を分析し、スターターCLAUDE.mdを自動生成します。ゼロから書き始めるよりも効率的です。
出典: Best Practices for Claude Code – Anthropic
ルール分割 ― .claude/rules/ ディレクトリ
CLAUDE.mdが大きくなりすぎた場合、.claude/rules/ ディレクトリにルールファイルを分割配置できます。
your-project/
├── .claude/
│ ├── CLAUDE.md # メインのプロジェクト指示
│ └── rules/
│ ├── code-style.md # コードスタイルガイドライン
│ ├── testing.md # テスト規約
│ └── security.md # セキュリティ要件
特に有効なのがパス指定ルールです。paths フロントマターを記述すると、対象ファイルを操作するときだけルールが読み込まれます。
---
paths:
- "config/nginx/**/*.conf"
---
# nginx設定ルール
- 必ずバックアップを取得してから変更する
- `nginx -t` で構文チェック後に `systemctl reload nginx` を実行する
この仕組みにより、nginx設定を操作するときだけnginxルールが読み込まれ、Ansible Playbookを操作するときはAnsibleルールが読み込まれます。コンテキストの無駄が減り、コンテキストロットを防止できます。
出典: How Claude remembers your project – Anthropic
Auto Memory ― エージェントの学習メモリ
記事②で紹介したAuto Memory(自動メモリ)について、設計の観点から補足します。
| CLAUDE.md(手動メモリ) | Auto Memory(自動メモリ) | |
|---|---|---|
| 誰が書くか | ユーザー | Claude |
| 内容 | 指示とルール | 学習内容とパターン |
| スコープ | プロジェクト / ユーザー | ワーキングツリーごと |
| 読み込み | 毎セッション全文 | 毎セッション先頭200行 |
Auto Memoryは ~/.claude/projects/<project>/memory/ に保存されます。エントリポイントとなる MEMORY.md の先頭200行が毎セッション読み込まれ、トピック別ファイル(debugging.md、patterns.md 等)は必要時にオンデマンドで読み込まれます。
コンテキストエンジニアリングの観点で重要なのは、CLAUDE.md(手動)とAuto Memory(自動)の役割分担です。プロジェクトのルールや制約はCLAUDE.mdに明示的に書き、ビルドコマンドやデバッグの知見など作業中に発見した情報はAuto Memoryに任せる、という分担が有効です。
/memory コマンドでオン/オフを切り替え可能です。
出典: How Claude remembers your project – Anthropic
本ブログのCLAUDE.md設計 ― 実例で学ぶ
記事②で構成を紹介した本ブログ(インフラエンジニアの羅針盤)のCLAUDE.mdについて、設計上の判断ポイントを解説します。
記事②ではCLAUDE.mdの階層構造(ユーザー設定 / プロジェクト設定 / サブディレクトリ設定 / マネージドポリシー)を紹介しました。ここでは「何をどの階層に書くか」の設計判断に焦点を当てます。
C:\ClaudeWorkspaces\
├── CLAUDE.md ← グローバル設定(約350行)
│ ├── 文体ルール(です・ます調、禁止表現一覧)
│ ├── Agent Team構成(6 Instance定義)
│ └── HTML納品ルール(WordPress/Cocoon向け)
└── series\generative-ai\
└── CLAUDE.md ← シリーズ設定(約200行)
├── 記事ごとの詳細設定
└── 各Instanceへの追加指示
設計上の5つの判断ポイント:
- 不変のルールはグローバルに配置する: 文体ルール・品質基準・Agent Team構成は全記事で共通のため、グローバルCLAUDE.mdに定義。1箇所を変更すれば全記事に反映される
- 変動するルールはサブディレクトリに分離する: 記事ごとのキーワード戦略・構成・検証観点はシリーズCLAUDE.mdに定義。記事が増えてもグローバル設定は肥大化しない
- ルールの根拠を書く: 「何をすべきか」だけでなく「なぜそうするのか」を記載する。例: 禁止表現の一覧だけでなく、各表現を禁止する理由を併記すると、エージェントの遵守率が上がる
- 強調表現で遵守率を上げる: 「IMPORTANT」「YOU MUST」等の表現はClaude Codeの遵守率を高める効果がある(Anthropic公式推奨)
@importで分割読み込みする:@path/to/import構文で追加ファイルをインポート可能(最大深度5段階、公式ドキュメント参照)。CLAUDE.mdが200行を超えた場合の分割手段として有効
.claude/rules/ への分割を検討してください。長すぎるCLAUDE.mdはコンテキストを圧迫し、コンテキストロットの原因になります。
情報設計パターン5選 ― Anthropic公式テクニックの実践
Anthropicは「Effective context engineering for AI agents」(2025年9月)でコンテキスト設計のガイダンスと3つの主要テクニック(Compaction、Structured note-taking、Sub-agent architectures)を紹介しています。ここではAnthropicの記事とPhilipp Schmidの整理を組み合わせ、インフラ業務で実用性の高い5つのパターンを紹介します。
| # | パターン | 概要 | Claude Codeでの実現手段 |
|---|---|---|---|
| 1 | 段階的開示 | 必要な情報を必要なタイミングで取得 | サブエージェント、Read/Grep |
| 2 | ツール設計の最適化 | ツール定義のオーバーラップを最小化 | settings.json、MCP設定 |
| 3 | 厳選されたFew-shot | 量より質の例示 | CLAUDE.mdに厳選例を記載 |
| 4 | 構造化メモ | 作業結果を外部ファイルに記録 | Write + Auto Memory |
| 5 | サブエージェント構造 | 独立コンテキストで並列作業 | Agentツール |
パターン1: 段階的開示(Progressive Disclosure)
「事前にすべてをコンテキストに詰め込む」のではなく、必要な情報を必要なタイミングで取得する戦略です。Anthropicはこれを “just in time” 戦略と呼んでいます。
インフラ業務での例:
障害対応を依頼された場合、エージェントは以下の順序で段階的に情報を取得します。
- まずアラート情報だけを読み込む(Read)
- アラート内容をもとに、関連するログファイルを特定して読み込む(Grep)
- ログ分析の結果、設定ファイルの確認が必要と判断したら設定ファイルを読む(Read)
- 必要に応じて変更履歴を確認する(Bash:
git log)
最初からログ全量 + 設定ファイル全量 + 変更履歴全量をコンテキストに入れるのではなく、分析の進行に応じて段階的に取得します。これにより、コンテキストの無駄が減り、精度が上がります。
Claude Codeでの実装:
サブエージェント(Agentツール)を活用すると、調査タスクを別コンテキストで実行し、要約だけをメインに返すことができます。メインのコンテキストウィンドウを汚染せずに、広範な調査が可能です。
パターン2: ツール設計の最適化
ツール定義もコンテキストの一部です。不要なツールが多すぎると、ツール定義だけでトークンを大量に消費し、コンテキストロットの原因になります。
インフラ業務での例:
MCP(Model Context Protocol / モデルコンテキストプロトコル)サーバーで外部ツール(Notion、Jira、監視ツール等)を連携する際、プロジェクトに必要なツールだけを有効化します。全ツールを有効にするとツール定義だけで数千トークンを消費する場合があります。
Claude Codeでの実装:
settings.jsonでツールの許可範囲を適切に設定する/permissionsコマンドで安全なコマンドをホワイトリスト登録する- MCPサーバーの設定で、プロジェクトに不要なツールは無効化する
パターン3: 厳選されたFew-shot
記事①でFew-shotテクニックの使い方を学びました。コンテキストエンジニアリングの観点では、例の「量」ではなく「質と多様性」が重要です。
インフラ業務での例:
障害対応の分類ルールをCLAUDE.mdに定義する場合を考えます。
# 障害分類ルール(CLAUDE.md抜粋)
以下の3例を基準に、アラートの重要度を分類すること:
- IGNORE例: `INFO [httpd] GET /health 200` → 正常動作。対応不要
- CHECK例: `WARN [disk] /var usage 82%` → 閾値超過だが即時障害ではない。翌営業日確認
- URGENT例: `ERROR [mysqld] Too many connections` → サービス影響あり。即時対応
100パターンのログ例を列挙するのではなく、重要度が異なる3パターンを厳選して記載します。多様性のある少数の例が、大量の似通った例よりも効果的です。
パターン4: 構造化メモ(Structured Notes)
長時間のエージェントセッションでは、初期の情報がコンパクションで消える可能性があります。重要な中間結果を外部ファイルに記録しておくことで、情報の喪失を防ぎます。
インフラ業務での例:
複数サーバーにまたがる構築作業で、各ステップの実行結果をファイルに記録しながら進めます。
# CLAUDE.md(構造化メモの指示例)
## 作業ルール
- 各ステップの実行結果を `work-log.md` に記録すること
- 記録形式: 「ステップ番号 / 実行コマンド / 結果 / 成否」
- エラーが発生した場合は原因と対処もあわせて記録すること
この指示をCLAUDE.mdに書いておくと、エージェントは自律的にWriteツールで作業ログを更新しながら作業を進めます。コンパクションが発生しても、ファイルに記録された情報はReadツールで再取得できます。
Auto Memoryも構造化メモの一種です。ビルドコマンドの知見やデバッグパターンなど、作業中に発見した情報をClaude自身が自動で保存し、次回のセッションで活用します。
パターン5: サブエージェント構造
複数の専門化されたエージェントが独立したコンテキストウィンドウで作業する構成です。メインのコンテキストウィンドウを汚染せずに、広範な調査や処理が可能になります。
インフラ業務での例:
セキュリティ監査タスクをサブエージェントに委任し、メインエージェントは結果だけを受け取ってレポートを生成する構成です。
本ブログの実例:
記事②で紹介したAgent Team構成がサブエージェント構造の実例です。
- Researcher(調査): 公式ドキュメントを調査し、結果を要約してメインに報告
- Verifier(検証): コマンド・手順を実際に実行して検証結果を報告
- Designer(設計): アイキャッチ仕様・図解を設計して仕様書を出力
- Reviewer(監査): 品質チェック結果を報告
各サブエージェントは独立したコンテキストウィンドウで動作するため、互いの作業がコンテキストを汚染しません。Verifierが大量のコマンド実行ログを生成しても、Writerのコンテキストには影響しません。
出典: Effective context engineering for AI agents – Anthropic
RAG ― 外部知識の動的取得
RAGとは何か
RAG(Retrieval-Augmented Generation / 検索拡張生成)は、コンテキストの7要素の1つであり、外部知識の動的取得を担当する仕組みです。
処理フローは3段階です。
- Retrieval(検索) ― 外部データソース(ベクトルDB、ドキュメント、API等)から関連情報を検索する
- Augmentation(拡張) ― 検索結果をLLMのコンテキストに組み込む
- Generation(生成) ― 拡張されたコンテキストをもとにLLMが応答を生成する
RAGの目的は、LLMの知識カットオフを超えた最新情報へのアクセス、ハルシネーション(幻覚)の低減、組織固有のプライベートデータの活用です。
コンテキストエンジニアリングとの関係では、RAGはコンテキストを動的に充実させるための手段の1つです。Andrej Karpathyもコンテキストエンジニアリングの構成要素としてRAGを明示的に挙げています。
Claude Codeで実現するRAG的アプローチ
Claude Code自体はベクトルDBを内蔵したRAGシステムではありません。しかし、以下の機能を組み合わせることで、実用的なRAG的フローを実現できます。
| 手段 | Claude Codeの機能 | RAGの対応フェーズ |
|---|---|---|
| ファイル読み込み | Read / Grep / Glob | Retrieval |
| Web検索 | WebSearch / WebFetch | Retrieval |
| CLAUDE.md / Auto Memory | セッション開始時に自動読み込み | Augmentation |
| パス指定ルール | .claude/rules/ のオンデマンド読み込み | Retrieval(条件付き) |
| サブエージェント | Agentツールで別コンテキスト調査 | Retrieval + Augmentation |
| MCP連携 | 外部ツール(Notion、DB等)へのアクセス | Retrieval |
インフラ業務でのRAG活用例
具体的な活用例として、障害対応ナレッジベースの構築を紹介します。
構成:
project/
├── CLAUDE.md ← 「障害対応時はincidents/を参照」と記載
├── incidents/
│ ├── 2025-12-01-db-timeout.md
│ ├── 2026-01-15-disk-full.md
│ └── 2026-02-28-ssl-expire.md
└── runbooks/
├── db-troubleshoot.md
└── disk-cleanup.md
CLAUDE.mdの記載例:
# 障害対応ルール
- 障害対応時は `incidents/` ディレクトリの過去事例をGrepで検索し、類似事例を参照すること
- 対処手順は `runbooks/` ディレクトリの手順書に従うこと
- 新しい障害の対応が完了したら、`incidents/` に報告書を作成すること
この構成で障害対応タスクを依頼すると、エージェントは自律的に以下のフローを実行します。
- アラート内容をもとに
incidents/ディレクトリをGrepで検索(Retrieval) - 類似事例が見つかれば、その対処手順をコンテキストに追加(Augmentation)
- 過去の知見を踏まえて対処案を生成(Generation)
ベクトルDBの構築は不要です。プロジェクト内のMarkdownファイルとCLAUDE.mdの指示だけで、十分に実用的なRAG的フローが実現できます。
まとめ
シリーズ全3記事の位置づけを振り返ります。
| 記事 | テーマ | 核心 |
|---|---|---|
| ① プロンプトエンジニアリング | 1回の指示をどう書くか | 6構成要素 + 3テクニックで指示を構造化 |
| ② AIエージェントエンジニアリング | LLM + ツール + ループで自律的にタスク処理 | エージェントは「生成→検証→修正」をループで回す |
| ③ コンテキストエンジニアリング | エージェントに何を見せるかを設計する | コンテキストの質がエージェントの品質を決める |
この記事の要点は以下のとおりです。
- コンテキストエンジニアリング: プロンプトエンジニアリングを包含する上位概念。「モデルに何を見せるか」を設計する技術
- コンテキストウィンドウ: 容量制限があり、情報の「質」が問われる。コンテキストロットにより、詰め込みすぎは精度低下の原因になる
- CLAUDE.md設計: 書くべきこと/書かないことの判断基準、
.claude/rules/によるルール分割、Auto Memoryとの役割分担 - 情報設計パターン5選: 段階的開示、ツール設計最適化、厳選されたFew-shot、構造化メモ、サブエージェント構造
- RAG: コンテキストエンジニアリングの構成要素の1つ。Claude Codeでは既存機能の組み合わせで実現可能
次にやること
- 自分のCLAUDE.mdを「書くべきこと/書かないこと」の基準で見直し、不要な記述を削除する
.claude/rules/ディレクトリにパス指定ルールを1つ作成し、コンテキストの効率化を試す- 情報設計パターン5選の中から1つを選び、実際の業務タスクで適用する
前の記事
前の記事 → ②AIエージェントエンジニアリング
3記事を通じて、プロンプト設計→エージェント構築→情報設計の技術を段階的に扱いました。まずは自分のCLAUDE.mdを「書くべきこと/書かないこと」の基準で見直し、情報設計パターンを1つ選んで実際の業務タスクに適用するところから始めてください。
