customaize-agent:context-engineering

コンテキストエンジニアリングの基礎

コンテキストとは、推論時に言語モデルが利用できる状態全体です。応答を生成する際にモデルが参照できるすべての情報が含まれます。システム指示、ツール定義、検索されたドキュメント、メッセージ履歴、ツールの出力などです。効果的なコンテキストエンジニアリングには、コンテキストの基礎を理解することが欠かせません。

基本概念

コンテキストはいくつかの異なる要素で構成され、それぞれ特性や制約が異なります。アテンション機構によって有限の予算が生じ、コンテキストを効果的に利用するうえでの制約となります。段階的な開示によって、必要な情報だけを読み込み、この制約に対処します。エンジニアリングでは、望ましい成果を実現する、信号価値の高いトークンを最小限に厳選します。

詳細トピック

コンテキストの解剖学

システムプロンプト システムプロンプトは、エージェントの核となるアイデンティティ、制約、および行動ガイドラインを確立します。これらはセッション開始時に一度読み込まれ、通常は会話全体を通じて持続します。システムプロンプトは極めて明確であるべきで、エージェントに適した高度でシンプルかつ直接的な言葉を使用する必要があります。

適切な高度とは、2つの失敗モードのバランスを取ることです。一方の極端では、エンジニアは複雑で脆いロジックをハードコードし、脆弱性とメンテナンス負担を生み出します。もう一方の極端では、エンジニアは曖昧な高レベルのガイダンスを提供し、望ましい出力に対する具体的なシグナルを与えられず、あるいは共有コンテキストを誤って前提としてしまいます。最適な高度はバランスを取ります。つまり、行動を効果的に導くのに十分具体的でありながら、強力なヒューリスティクスを提供するのに十分柔軟であることです。

プロンプトは、XMLタグまたはMarkdown見出しを使用して明確なセクションに整理し、背景情報、指示、ツールガイダンス、および出力の説明を区別します。モデルがより高性能になるにつれて正確なフォーマットの重要性は低くなりますが、構造の明確さは依然として価値があります。

ツール定義 ツール定義は、エージェントが実行できるアクションを指定します。各ツールには、名前、説明、パラメータ、および戻り値の形式が含まれます。ツール定義はシリアライズ後、コンテキストの前方付近、通常はシステムプロンプトの前または後に配置されます。

ツールの説明は集合的にエージェントの行動を導きます。不十分な説明はエージェントに推測を強います。最適化された説明には、使用コンテキスト、例、およびデフォルト値が含まれます。統合の原則とは、人間のエンジニアが特定の状況でどのツールを使用すべきかを明確に言えないのであれば、エージェントがそれ以上にうまくできるとは期待できないというものです。

取得されたドキュメント 取得されたドキュメントは、ドメイン固有の知識、参考資料、またはタスクに関連する情報を提供します。エージェントは検索拡張生成を使用して、すべての可能な情報を事前に読み込むのではなく、実行時に関連するドキュメントをコンテキストに取り込みます。

ジャストインタイムのアプローチでは、軽量な識別子（ファイルパス、保存されたクエリ、Webリンク）を維持し、これらの参照を使用してデータを動的にコンテキストに読み込みます。これは人間の認知を反映しています。私たちは通常、情報の全集を暗記するのではなく、外部の整理およびインデックスシステムを使用して、必要に応じて関連情報を取得します。

メッセージ履歴 メッセージ履歴には、以前のクエリ、応答、および推論を含む、ユーザーとエージェントの間の会話が含まれます。長時間実行されるタスクでは、メッセージ履歴が拡大してコンテキスト使用量を支配する可能性があります。

メッセージ履歴は、エージェントが進捗を追跡し、タスク状態を維持し、ターンをまたいで推論を保持するスクラッチパッドメモリとして機能します。メッセージ履歴の効果的な管理は、長期的なタスク完了にとって重要です。

ツール出力 ツール出力は、エージェントのアクションの結果です。ファイル内容、検索結果、コマンド実行出力、API応答、および類似のデータが含まれます。ツール出力は、一般的なエージェントの軌跡におけるトークンの大部分を占め、調査によると観察（ツール出力）は総コンテキスト使用量の83.9%に達することがあります。

ツール出力は、現在の意思決定に関連するかどうかに関わらずコンテキストを消費します。これは、観察のマスキング、圧縮、および選択的なツール結果の保持といった戦略への圧力を生み出します。

コンテキストウィンドウと注意機構

注意予算の制約 言語モデルは、コンテキスト内のすべてのトークン間にペアごとの関係を作り出す注意機構を通じてトークンを処理します。n 個のトークンがある場合、計算して保存する必要のある関係は n^2 個になります。コンテキストが長くなるにつれて、モデルがこうした関係を捉える能力は低下します。

モデルは、短いシーケンスが多くを占める学習データの分布から注意パターンを身につけます。そのため、コンテキスト全体にわたる依存関係の経験が少なく、そうした依存関係に特化したパラメーターも多くありません。その結果、コンテキストが大きくなるにつれて「注意予算」が減っていきます。

位置エンコーディングとコンテキスト拡張 位置エンコーディングの補間を使うと、モデルがもともと学習したより短いコンテキストに合わせて調整することで、より長いシーケンスを扱えるようになります。しかし、この調整により、トークン位置の理解が劣化します。モデルは長いコンテキストでも高い能力を保ちますが、短いコンテキストでの性能と比べると、情報検索や長距離推論の精度は低下します。

段階的開示の原則 段階的開示では、必要なときにだけ情報を読み込むことで、コンテキストを効率的に管理します。起動時にエージェントが読み込むのはスキル名と説明だけで、スキルが関係する可能性がある場面を判断するには十分です。特定のタスクでスキルが有効化されたときに限り、全内容を読み込みます。

この方法により、必要に応じて追加のコンテキストにアクセスできるようにしながら、エージェントの処理速度を保てます。この原則は、スキルの選択、ドキュメントの読み込み、さらにはツールの結果の取得など、複数の段階で適用できます。

コンテキストの品質と量

コンテキストウィンドウを大きくすればメモリの問題が解決するという前提は、実証的に否定されています。コンテキストエンジニアリングとは、望ましい結果が得られる可能性を最大化する、高い有用性を持つトークンの集合を可能な限り小さく見つけることです。

複数の要因により、コンテキストの効率化が求められます。処理コストはコンテキストの長さに応じて不釣り合いに増大します。トークン数が2倍ならコストも2倍になるのではなく、時間と計算資源は指数関数的に増えます。ウィンドウが技術的により多くのトークンをサポートしていても、一定のコンテキスト長を超えるとモデルの性能は低下します。また、プレフィックスキャッシュを使っても、長い入力の処理には高いコストがかかります。

指針となる原則は、網羅性より情報量です。そのときの判断に重要な情報を含め、重要でない情報を除外し、必要に応じて追加情報にアクセスできるシステムを設計します。

有限なリソースとしてのコンテキスト

コンテキストは、限界効用が逓減する有限なリソースとして扱う必要があります。作業記憶に限りのある人間と同様に、大量のコンテキストを解析する言語モデルも、注意予算を消費します。

新しいトークンが追加されるたびに、この予算は一定量減少します。そのため、利用可能なトークンを慎重に選別する必要があります。エンジニアリング上の課題は、本質的な制約のもとで有用性を最適化することです。

コンテキストエンジニアリングは反復的なプロセスであり、何をモデルに渡すかを決めるたびに選別の段階が発生します。これは一度きりのプロンプト作成ではなく、継続的にコンテキストを管理する取り組みです。

実践的なガイダンス

ファイルシステムによるアクセス

ファイルシステムにアクセスできるエージェントは、段階的開示を自然に活用できます。参照資料、ドキュメント、データは外部に保存します。標準的なファイルシステム操作を使い、必要なときにだけファイルを読み込みます。このパターンにより、関係するとは限らない情報でコンテキストを埋めずに済みます。

ファイルシステム自体が、エージェントがたどれる構造を提供します。ファイルサイズは複雑さの目安となり、命名規則は用途の手がかりとなり、タイムスタンプは関連性を推測する材料となります。ファイル参照のメタデータは、振る舞いを効率的に絞り込む手段となります。

ハイブリッド戦略

最も効果的なエージェントはハイブリッド戦略を採用しています。速度のために一部のコンテキスト（CLAUDE.md ファイルやプロジェクトルールなど）を事前に読み込みつつ、必要に応じて追加のコンテキストを自律的に探索できるようにします。この判断の境界は、タスクの特性とコンテキストの動的な性質によって決まります。

動きの少ないコンテンツを含むコンテキストでは、より多くの情報を事前に読み込むことが理にかなっています。急速に変化する情報や非常に特殊な情報については、ジャストインタイムで読み込むことで古くなったコンテキストを避けられます。

コンテキストの予算管理

明示的なコンテキスト予算を念頭に置いて設計してください。モデルとタスクにとっての有効なコンテキスト上限を把握しましょう。開発中はコンテキストの使用量を監視してください。適切なしきい値で圧縮のトリガーを実装しましょう。コンテキストが劣化しないことを期待するのではなく、劣化することを前提にシステムを設計してください。

効果的なコンテキストの予算管理には、生のトークン数だけでなく、注意の配分パターンを理解することが必要です。コンテキストの中央は、先頭や末尾よりも注意が向けられにくくなります。重要な情報は注意が向けられやすい位置に配置してください。

例

例 1: システムプロンプトの整理

<BACKGROUND_INFORMATION>
You are a Python expert helping a development team.
Current project: Data processing pipeline in Python 3.9+
</BACKGROUND_INFORMATION>

<INSTRUCTIONS>
- Write clean, idiomatic Python code
- Include type hints for function signatures
- Add docstrings for public functions
- Follow PEP 8 style guidelines
</INSTRUCTIONS>

<TOOL_GUIDANCE>
Use bash for shell operations, python for code tasks.
File operations should use pathlib for cross-platform compatibility.
</TOOL_GUIDANCE>

<OUTPUT_DESCRIPTION>
Provide actionable feedback with specific line references.
Explain the reasoning behind suggestions.
</OUTPUT_DESCRIPTION>

例 2: プログレッシブなドキュメント読み込み

# Instead of loading all documentation at once:

# Step 1: Load summary
docs/architecture_overview.md     # Lightweight overview

# Step 2: Load specific section as needed
docs/api/endpoints.md             # Only when API work needed
docs/database/schemas.md          # Only when data layer work needed

例 3: スキル説明の設計

# Bad: Vague description that loads into context but provides little signal
description: Helps with code things

# Good: Specific description that helps model decide when to activate
description: Analyze code quality and suggest refactoring patterns. Use when reviewing pull requests or improving existing code structure.

ガイドライン

1. コンテキストを、収穫逓減を伴う有限のリソースとして扱う
2. 重要な情報は注意が向けられやすい位置（先頭と末尾）に配置する
3. プログレッシブディスクロージャーを使い、必要になるまで読み込みを遅延させる
4. 明確なセクションの境界を設けてシステムプロンプトを整理する
5. 開発中はコンテキストの使用量を監視する
6. 使用率が 70～80% になったら圧縮のトリガーを実装する
7. コンテキストの劣化を避けられることを期待するのではなく、劣化を前提に設計する
8. 大きくシグナルの弱いコンテキストよりも、小さくシグナルの強いコンテキストを優先する

コンテキスト劣化パターン

言語モデルは、コンテキスト長が増加するにつれて予測可能な劣化パターンを示します。これらのパターンを理解することは、障害を診断し、回復力のあるシステムを設計するために不可欠です。コンテキストの劣化は二値的な状態ではなく、いくつかの異なる形で現れる性能低下の連続体です。

中核となる概念

コンテキストの劣化は、いくつかの異なるパターンを通じて現れます。ロスト・イン・ザ・ミドル現象は、コンテキストの中央にある情報に注意が向けられにくくなることを引き起こします。コンテキストポイズニングは、繰り返し参照されることでエラーが複合化するときに発生します。コンテキストディストラクションは、無関係な情報が関連するコンテンツを圧倒するときに起こります。コンテキストコンフュージョンは、モデルがどのコンテキストが適用されるかを判断できなくなるときに生じます。コンテキストクラッシュは、蓄積された情報が直接的に矛盾するときに発展します。

これらのパターンは予測可能であり、圧縮、マスキング、分割、分離といったアーキテクチャパターンによって緩和できます。

詳細なトピック

ミドルでの情報損失現象

最もよく記録されている劣化パターンは「ミドルでの情報損失」効果で、モデルの注意曲線がU字型を示す現象です。コンテキストの冒頭と末尾にある情報には安定して注意が向けられますが、中央に埋もれた情報の想起精度は大幅に低下します。

実証的証拠 研究によると、コンテキストの中央に配置された関連情報は、冒頭または末尾に同じ情報を配置した場合と比べて、想起精度が10～40％低下します。これはモデルの失敗ではなく、注意の仕組みと学習データの分布に起因するものです。

モデルは内部状態を安定させるため、最初のトークン（多くの場合、BOSトークン）に膨大な注意を割り当てます。その結果、注意の「シンク」が生じ、注意の予算を大量に消費します。コンテキストが長くなるにつれて限られた予算がさらに分散し、中央のトークンには信頼性の高い検索に十分な注意の重みが割り当てられなくなります。

実践的な意味 注意のパターンを考慮して、コンテキスト内の情報の配置を設計してください。重要な情報はコンテキストの冒頭か末尾に配置します。その情報が直接問い合わせられるのか、それとも推論を支える必要があるのかを検討してください。後者の場合、配置の重要性は低くなりますが、全体的なシグナル品質の重要性は高くなります。

長いドキュメントや会話では、注意が向きやすい位置に重要な情報を示す要約構造を使用してください。モデルが構造を把握しやすいように、明示的なセクション見出しとつなぎの表現を使用します。

コンテキスト汚染

コンテキスト汚染は、幻覚、エラー、または誤った情報がコンテキストに入り、繰り返し参照されることで増幅する現象です。いったん汚染されると、コンテキスト内にフィードバックループが生じ、誤った信念が強化されます。

汚染の発生経路 汚染は通常、3つの経路から発生します。第一に、ツールの出力にエラーや予期しない形式が含まれ、モデルがそれを正しい情報として受け入れる場合があります。第二に、取得したドキュメントに誤った情報や古い情報が含まれ、モデルが推論に取り込む場合があります。第三に、モデルが生成した要約や中間出力に幻覚が入り、それがコンテキスト内に残り続ける場合があります。

増幅による影響は深刻です。エージェントの目標セクションが汚染されると、それを元に戻すのに多大な労力を要する戦略が生み出されます。その後の各判断で汚染された内容が参照され、誤った前提が強化されます。

検出と復旧 以前は成功していたタスクで出力品質が低下する、エージェントが誤ったツールやパラメーターを呼び出すなどツールとの連携がずれる、修正を試みても幻覚が残る、といった兆候に注意してください。これらの兆候が見られた場合は、コンテキスト汚染を疑ってください。

復旧するには、汚染された内容を削除するか、置き換える必要があります。汚染が発生した箇所より前までコンテキストを切り詰める、コンテキスト内で汚染について明示して再評価を求める、または検証済みの情報だけを残してクリーンなコンテキストでやり直す、といった方法があります。

コンテキストの注意散漫

コンテキストが長くなりすぎると、モデルが学習済みの知識よりも提供された情報を過度に重視するようになり、コンテキストの注意散漫が生じます。モデルは関連性にかかわらずコンテキスト内のすべてに注意を向けるため、内部知識のほうが正確な場合でも、提供された情報を使おうとする圧力が生まれます。

注意をそらす情報の影響 研究によると、コンテキストに関連性のない文書が1つ含まれるだけでも、関連文書を使うタスクの性能が低下します。注意をそらす情報が複数あると、性能低下はさらに大きくなります。この影響は、単純にノイズの量によるものではなく、注意の配分に関係しています。つまり、関連性のない情報が限られた注意の枠をめぐって、関連情報と競合するのです。

モデルには、関連性のないコンテキストを「読み飛ばす」仕組みがありません。与えられた情報すべてに注意を向けなければならず、関連性のない情報が明らかに役立たない場合でも、この制約によって注意が散漫になります。

軽減策 コンテキストに含める情報を慎重に選別して、注意散漫を軽減しましょう。取得した文書を読み込む前に、関連性をフィルタリングします。名前空間や整理方法を活用し、関連性のないセクションを構造上無視しやすくします。また、情報を本当にコンテキストに含める必要があるのか、それともツール呼び出しで取得できるのかを検討してください。

コンテキストの混乱

コンテキストの混乱は、関連性のない情報が応答に影響を与え、品質を低下させるときに生じます。注意散漫と関係していますが、異なる現象です。混乱では、注意の配分ではなく、コンテキストがモデルの振る舞いに与える影響が問題になります。

コンテキストに何かを含めると、モデルはそれに注意を向けなければなりません。モデルは関連性のない情報を取り込んだり、不適切なツール定義を使ったり、別のコンテキストに由来する制約を適用したりする可能性があります。コンテキストに複数のタスク種別が含まれている場合や、1つのセッション内でタスクを切り替える場合、混乱は特に問題になります。

混乱の兆候 質問の誤った側面に答える応答、別のタスクには適切に見えるツール呼び出し、複数の情報源からの要件を混ぜ合わせた出力に注意してください。こうした兆候は、現在の状況にどのコンテキストが適用されるか、モデルが混乱していることを示します。

アーキテクチャ上の解決策 アーキテクチャ上の解決策には、タスクごとに異なるコンテキストウィンドウを割り当てる明示的なタスク分割、タスクのコンテキスト間を明確に切り替える仕組み、異なる目的のコンテキストを分離する状態管理などがあります。

コンテキストの衝突

コンテキストの衝突は、蓄積された情報が直接矛盾し、推論を妨げるときに生じます。誤った情報が1つ含まれるポイズニングとは異なり、衝突では複数の正しい情報が互いに矛盾します。

衝突の原因 衝突は、情報源によって内容が異なるマルチソース検索、古い情報と最新情報の両方がコンテキストに含まれるバージョンの競合、異なる視点がそれぞれ妥当でありながら両立しない視点の競合などから生じることがよくあります。

解決方法 解決方法には、矛盾を特定して確認を求める明示的な競合表示、どの情報源を優先するかを定める優先順位ルール、古い情報をコンテキストから除外するバージョンフィルタリングなどがあります。

直感に反する調査結果

調査により、コンテキスト管理に関する前提に反する、いくつかのパターンが明らかになっています。

一貫性のない干し草の山が、一貫性のあるものを上回る 研究によると、シャッフルされた（一貫性のない）干し草の山は、論理的に一貫性のあるものよりも優れた性能をもたらします。これは、一貫性のあるコンテキストが誤った関連付けを生み、検索を混乱させる一方で、一貫性のないコンテキストではモデルが正確な一致に頼らざるを得ないことを示唆しています。

1つのノイズ情報が不釣り合いに大きな影響を与える 無関係な文書が1つあるだけでも、性能は大幅に低下します。その影響はノイズの量に比例するのではなく、ノイズ情報が1つでも存在すると劣化が引き起こされる階段関数に従います。

ニードルと質問の類似度の相関 ニードルと質問のペアの類似度が低いほど、コンテキスト長に伴う劣化が速くなります。類似性の低い内容をまたいだ推論を必要とするタスクは、特に影響を受けやすくなります。

より大きなコンテキストが悪影響をもたらす場合

コンテキストウィンドウを大きくしても、性能が一様に向上するわけではありません。多くの場合、より大きなコンテキストは、メリットを上回る新たな問題を引き起こします。

性能劣化曲線 モデルの性能は、コンテキスト長に対して非線形に劣化します。あるしきい値までは安定していますが、その後急速に劣化します。このしきい値はモデルとタスクの複雑さによって異なります。多くのモデルでは、コンテキストウィンドウがはるかに大きなサイズに対応していても、8,000～16,000トークンあたりから顕著な劣化が始まります。

コストへの影響 処理コストは、コンテキスト長が増えるにつれて不釣り合いに大きくなります。400Kトークンのコンテキストの処理コストは、200Kトークンの2倍ではなく、時間と計算リソースの両面で指数関数的に増加します。多くのアプリケーションでは、このため大規模なコンテキスト処理は経済的に実用的ではありません。

認知負荷のたとえ コンテキストが無限にあっても、1つのモデルに数十の独立したタスク全体で一貫した品質を保たせることは、認知的なボトルネックを生みます。モデルは項目間でコンテキストを絶えず切り替え、比較の枠組みを保ち、文体の一貫性を確保しなければなりません。これは、コンテキストを増やしても解決できない問題です。

実践的なガイダンス

4つのバケットアプローチ

コンテキストの劣化におけるさまざまな側面には、次の4つの戦略が有効です。

書き出す：スクラッチパッド、ファイルシステム、外部ストレージを使って、コンテキストウィンドウの外にコンテキストを保存します。これにより、情報へのアクセスを維持しながら、アクティブなコンテキストを軽量に保てます。

選択する：検索、フィルタリング、優先順位付けによって、関連するコンテキストをウィンドウに取り込みます。無関係な情報を除外することで、注意散漫を抑えます。

圧縮する：要約、抽象化、観察結果のマスキングによって、情報を保ったままトークン数を減らします。これにより、実効コンテキスト容量を拡張できます。

分離する：コンテキストが劣化するほど大きくなるのを防ぐため、サブエージェントやセッション間でコンテキストを分割します。これは最も積極的な戦略ですが、多くの場合、最も効果的です。

アーキテクチャパターン

具体的なアーキテクチャパターンを通じて、これらの戦略を実装します。必要なときにだけ情報を取得する、ジャストインタイムのコンテキスト読み込みを使用します。冗長なツール出力を簡潔な参照に置き換える、観察結果のマスキングを使用します。異なるタスクのコンテキストを分離するために、サブエージェントアーキテクチャを使用します。コンテキストが上限を超える前に要約する、コンパクションを使用します。

例

例1：プロンプト設計で劣化を検出する

# Signs your command/skill prompt may be too large:

Early signs (context ~50-70% utilized):
- Agent occasionally misses instructions
- Responses become less focused
- Some guidelines ignored

Warning signs (context ~70-85% utilized):
- Inconsistent behavior across runs
- Agent "forgets" earlier instructions
- Quality varies significantly

Critical signs (context >85% utilized):
- Agent ignores key constraints
- Hallucinations increase
- Task completion fails

例2：プロンプト構造でLost-in-Middleを緩和する

# Organize prompts with critical info at edges

<CRITICAL_CONSTRAINTS>                    # At start (high attention)
- Never modify production files directly
- Always run tests before committing
- Maximum file size: 500 lines
</CRITICAL_CONSTRAINTS>

<DETAILED_GUIDELINES>                     # Middle (lower attention)
- Code style preferences
- Documentation templates
- Review checklists
- Example patterns
</DETAILED_GUIDELINES>

<KEY_REMINDERS>                           # At end (high attention)
- Run tests: npm test
- Format code: npm run format
- Create PR with description
</KEY_REMINDERS>

例3：サブエージェントによるコンテキスト分離

# Instead of one agent handling everything:

## Coordinator Agent (lean context)
- Understands task decomposition
- Delegates to specialized sub-agents
- Synthesizes results

## Code Review Sub-Agent (isolated context)
- Loaded only with code review guidelines
- Focuses solely on review task
- Returns structured findings

## Test Writer Sub-Agent (isolated context)
- Loaded only with testing patterns
- Focuses solely on test creation
- Returns test files

ガイドライン

1. 開発中はコンテキストの長さとパフォーマンスの相関を監視します
2. 重要な情報はコンテキストの冒頭または末尾に配置します
3. 劣化が深刻になる前に、圧縮のトリガーを実装します
4. コンテキストに追加する前に、取得したドキュメントの正確性を検証します
5. バージョン管理を使用して、古い情報による衝突を防ぎます
6. 目的の異なるタスク間でコンテキストが混乱しないよう、タスクを分割します
7. 完璧な条件を前提とせず、段階的な劣化を想定して設計します
8. コンテキストを段階的に大きくしながらテストし、劣化のしきい値を見つけます

コンテキスト劣化のパターン：マルチエージェントワークフロー

このセクションでは、コンテキスト劣化の検出と軽減に関する概念を、Claude Code 向けの実用的なマルチエージェントワークフローに変換します。品質と信頼性を確保するために、コマンド、スキル、複雑なエージェントパイプラインを構築する際に、これらのパターンを使用してください。

ハルシネーション検出ワークフロー

エージェントの出力に含まれるハルシネーションは、後続のコンテキストを汚染し、複数ステップのワークフロー全体にエラーを伝播させる可能性があります。このワークフローでは、エラーが積み重なる前にハルシネーションを検出します。

使用するタイミング

• 事実に基づく主張を生成するタスクをエージェントが完了した後
• エージェントが生成したコードやドキュメントをコミットする前
• 出力が後続のエージェントへの入力として使用される場合
• 長時間実行されるエージェントセッションをレビューする際

マルチエージェント検証パターン

ステップ 1：出力を生成する

プライマリエージェントに通常どおりタスクを完了させます。

ステップ 2：主張を抽出する

次のプロンプトを使用して、検証用のサブエージェントを起動します。

<TASK>
Extract all factual claims from the following output. List each claim on a separate line.
</TASK>

<FOCUS_AREAS>
- File paths and their existence
- Function/class/method names referenced
- Code behavior assertions ("this function returns X")
- External facts about APIs, libraries, or specifications
- Numerical values and metrics
</FOCUS_AREAS>

<OUTPUT_TO_ANALYZE>
{agent_output}
</OUTPUT_TO_ANALYZE>

<OUTPUT_FORMAT>
One claim per line, prefixed with category:
[PATH] /src/auth/login.ts exists
[CODE] validateCredentials() returns a boolean
[FACT] JWT tokens expire after 24 hours by default
[METRIC] The function has O(n) complexity
</OUTPUT_FORMAT>

ステップ 3：主張を検証する

抽出した主張のグループごとに、検証エージェントを起動します。

<TASK>
Verify this claim by checking the actual codebase and context.
</TASK>

<CLAIM>
{claim}
</CLAIM>

<VERIFICATION_APPROACH>
- For file paths: Use file tools to check existence
- For code claims: Read the actual code and verify behavior
- For external facts: Cross-reference with documentation or web search
- For metrics: Analyze the code structure
</VERIFICATION_APPROACH>

<RESPONSE_FORMAT>
STATUS: [VERIFIED | FALSE | UNVERIFIABLE]
EVIDENCE: [What you found]
CONFIDENCE: [HIGH | MEDIUM | LOW]
</RESPONSE_FORMAT>

ステップ 4：汚染リスクを計算する

検証結果を集計します。

total_claims = number of claims extracted
verified_count = claims marked VERIFIED
false_count = claims marked FALSE
unverifiable_count = claims marked UNVERIFIABLE

poisoning_risk = (false_count * 2 + unverifiable_count) / total_claims

ステップ 5：判定のしきい値

• リスク < 0.1：出力は信頼できるため、通常どおり進めます
• リスク 0.1-0.3：進める前に、フラグが付いた主張を手動で確認します
• リスク > 0.3：根拠を明示する指示を追加して、出力を再生成します。

<REGENERATION_PROMPT>
Previous output contained {false_count} false claims and {unverifiable_count} unverifiable claims.

Specific issues:
{list of FALSE and UNVERIFIABLE claims with evidence}

Please regenerate your response. For each factual claim:
1. Explicitly verify it using tools before stating it
2. If you cannot verify, state "I cannot verify..." instead of asserting
3. Cite the specific file/line/source for verifiable facts
</REGENERATION_PROMPT>

ミドルロスト検出ワークフロー

長いプロンプトの中ほどに埋もれた重要な情報は、注意が払われにくくなります。このワークフローでは、複数のエージェントを実行し、その出力を元の指示と照合することで、プロンプトのどの部分が無視されるおそれがあるかを検出します。

使用するタイミング

• 長いプロンプトを含む新しいコマンドやスキルを設計する場合
• 実行のたびにエージェントの指示遵守が一貫しない場合
• プロンプトを本番環境にデプロイする前
• プロンプトを最適化する際

複数回実行による検証パターン

ステップ 1：重要な指示を特定する

エージェントが必ず従わなければならない、プロンプト内の重要な指示をすべて抽出します。

Critical instructions to verify:
1. "Never modify files in /production"
2. "Always run tests before committing"
3. "Use TypeScript strict mode"
4. "Maximum function length: 50 lines"
5. "Include JSDoc for public APIs"
6. "Format output as JSON"
7. "Log all file modifications"

ステップ 2：同じプロンプトで複数のエージェントを実行する

同じプロンプト（テスト対象のコマンド／スキル／エージェント）を使用して、3～5 個のエージェントを起動します。各エージェントは、同一の入力を使用して独立して実行されます。

<AGENT_RUN_CONFIG>
Number of runs: 5
Prompt: {your_full_prompt_being_tested}
Task: {representative_task_that_exercises_all_instructions}

For each run, save:
- run_id: unique identifier
- agent_output: complete response from agent
- timestamp: when run completed
</AGENT_RUN_CONFIG>

ステップ 3：各出力を元のプロンプトと照合して検証する

各エージェントの出力について、すべての重要な指示への準拠を確認する新しい検証エージェントを起動します。

<VERIFICATION_AGENT_PROMPT>
<TASK>
You are a compliance verification agent. Analyze whether the agent output followed each instruction from the original prompt.
</TASK>

<ORIGINAL_PROMPT>
{the_full_prompt_being_tested}
</ORIGINAL_PROMPT>

<CRITICAL_INSTRUCTIONS>
{numbered_list_of_critical_instructions}
</CRITICAL_INSTRUCTIONS>

<AGENT_OUTPUT>
{output_from_run_N}
</AGENT_OUTPUT>

<VERIFICATION_APPROACH>
For each critical instruction:
1. Determine if the instruction was applicable to this task
2. If applicable, check whether the output complies
3. Look for both explicit violations and omissions
4. Note any partial compliance
</VERIFICATION_APPROACH>

<OUTPUT_FORMAT>
RUN_ID: {run_id}

INSTRUCTION_COMPLIANCE:
- Instruction 1: "Never modify files in /production"
  STATUS: [FOLLOWED | VIOLATED | NOT_APPLICABLE]
  EVIDENCE: {quote from output or explanation}

- Instruction 2: "Always run tests before committing"
  STATUS: [FOLLOWED | VIOLATED | NOT_APPLICABLE]
  EVIDENCE: {quote from output or explanation}

[... continue for all instructions ...]

SUMMARY:
- Instructions followed: {count}
- Instructions violated: {count}
- Not applicable: {count}
</OUTPUT_FORMAT>
</VERIFICATION_AGENT_PROMPT>

ステップ 4：結果を集計し、リスクのある箇所を特定する

すべての実行の検証結果を収集し、一貫して従われなかった指示を特定します。

<AGGREGATION_LOGIC>
For each instruction:
  followed_count = number of runs where STATUS == FOLLOWED
  violated_count = number of runs where STATUS == VIOLATED
  applicable_runs = total_runs - (runs where STATUS == NOT_APPLICABLE)

  compliance_rate = followed_count / applicable_runs

  Classification:
  - compliance_rate == 1.0: RELIABLE (always followed)
  - compliance_rate >= 0.8: MOSTLY_RELIABLE (minor inconsistency)
  - compliance_rate >= 0.5: AT_RISK (inconsistent - likely lost-in-middle)
  - compliance_rate < 0.5: FREQUENTLY_IGNORED (severe issue)
  - compliance_rate == 0.0: ALWAYS_IGNORED (critical failure)

AT_RISK instructions are the primary signal for lost-in-middle problems.
These are instructions that work sometimes but not consistently, indicating
they are in attention-weak positions.
</AGGREGATION_LOGIC>

<AGGREGATION_OUTPUT_FORMAT>
INSTRUCTION COMPLIANCE SUMMARY:

| Instruction | Followed | Violated | Compliance Rate | Status |
|-------------|----------|----------|-----------------|--------|
| 1. Never modify /production | 5/5 | 0/5 | 100% | RELIABLE |
| 2. Run tests before commit | 3/5 | 2/5 | 60% | AT_RISK |
| 3. TypeScript strict mode | 4/5 | 1/5 | 80% | MOSTLY_RELIABLE |
| 4. Max function length 50 | 2/5 | 3/5 | 40% | FREQUENTLY_IGNORED |
| 5. Include JSDoc | 5/5 | 0/5 | 100% | RELIABLE |
| 6. Format as JSON | 1/5 | 4/5 | 20% | ALWAYS_IGNORED |
| 7. Log modifications | 3/5 | 2/5 | 60% | AT_RISK |

AT-RISK INSTRUCTIONS (likely in lost-in-middle zone):
- Instruction 2: "Run tests before commit" (60% compliance)
- Instruction 4: "Max function length 50" (40% compliance)
- Instruction 6: "Format as JSON" (20% compliance)
- Instruction 7: "Log modifications" (60% compliance)
</AGGREGATION_OUTPUT_FORMAT>

ステップ 5：推奨事項を出力する

特定したリスクのある箇所に基づいて、具体的な修正方法を提示します。

<RECOMMENDATIONS_OUTPUT>
LOST-IN-MIDDLE ANALYSIS COMPLETE

At-Risk Instructions Detected: {count}
These instructions are inconsistently followed, indicating they likely
reside in attention-weak positions (middle of prompt).

SPECIFIC RECOMMENDATIONS:

1. MOVE CRITICAL INFORMATION TO ATTENTION-FAVORED POSITIONS
   The following instructions should be relocated to the beginning or end of your prompt:
   - "Run tests before commit" -> Move to <CRITICAL_CONSTRAINTS> at prompt START
   - "Max function length 50" -> Move to <KEY_REMINDERS> at prompt END
   - "Format as JSON" -> Move to <OUTPUT_FORMAT> at prompt END
   - "Log modifications" -> Add to both START and END sections

2. USE EXPLICIT MARKERS TO HIGHLIGHT CRITICAL INFORMATION
   Restructure at-risk instructions with emphasis:

   Before: "Always run tests before committing"
   After:  "**CRITICAL:** You MUST run tests before committing. Never skip this step."

   Before: "Maximum function length: 50 lines"
   After:  "3. [REQUIRED] Maximum function length: 50 lines"

   Use numbered lists, bold markers, or explicit tags like [REQUIRED], [CRITICAL], [MUST].

3. CONSIDER SPLITTING CONTEXT TO REDUCE MIDDLE SECTION
   If your prompt has many instructions, consider:
   - Breaking into focused sub-prompts for different aspects
   - Using sub-agents with specialized, shorter contexts
   - Moving detailed guidance to on-demand sections loaded only when needed

   Current prompt structure creates a large middle section where
   {count} instructions are being lost. Reduce middle section by:
   - Moving 2-3 most critical items to edges
   - Converting remaining middle items to a numbered checklist
   - Adding explicit "verify these items" reminder at end
</RECOMMENDATIONS_OUTPUT>

ワークフロー全体の例

# Example: Testing a Code Review Command

## Original Prompt Being Tested:
"Review the code for: security issues, performance problems,
code style, test coverage, documentation completeness,
error handling, and logging practices."

## Run 5 Agents:
Each agent reviews the same code sample with this prompt.

## Verification Results:
| Instruction | Run 1 | Run 2 | Run 3 | Run 4 | Run 5 | Rate |
|-------------|-------|-------|-------|-------|-------|------|
| Security | Y | Y | Y | Y | Y | 100% |
| Performance | Y | X | Y | X | Y | 60% |
| Code style | X | X | Y | X | X | 20% |
| Test coverage | X | Y | X | X | Y | 40% |
| Documentation | X | X | X | Y | X | 20% |
| Error handling | Y | Y | X | Y | Y | 80% |
| Logging | Y | Y | Y | Y | Y | 100% |

## Analysis:
- RELIABLE: Security, Logging (at edges of list)
- AT_RISK: Performance, Error handling
- FREQUENTLY_IGNORED: Code style, Test coverage, Documentation (middle of list)

## Remediation Applied:
"**CRITICAL REVIEW AREAS:**
1. Security vulnerabilities
2. Test coverage gaps
3. Documentation completeness

Review also: performance, code style, error handling, logging.

**BEFORE COMPLETING:** Verify you addressed items 1-3 above."

エラー伝播分析ワークフロー

マルチエージェントチェーンでは、初期のエージェントで発生したエラーが後続のエージェントに伝播し、増幅されます。このワークフローでは、エラーの発生源を追跡します。

使用するタイミング

• 中間ステップは正しいにもかかわらず、最終出力にエラーが含まれる場合
• 複雑なマルチエージェントワークフローをデバッグする場合
• エージェントチェーン内のエラー境界を確立する場合
• 失敗したエージェントタスクの事後分析を行う際

エラートレースパターン

ステップ 1: エージェントチェーンの出力をキャプチャする

チェーン内の各エージェントの出力を記録します:

Agent Chain Record:
- Agent 1 (Analyzer): {output_1}
- Agent 2 (Planner): {output_2}
- Agent 3 (Implementer): {output_3}
- Agent 4 (Reviewer): {output_4}

ステップ 2: エラー症状を特定する

エラー特定エージェントを起動します:

<TASK>
Analyze the final output and identify all errors, inconsistencies, or quality issues.
</TASK>

<FINAL_OUTPUT>
{output_from_last_agent}
</FINAL_OUTPUT>

<OUTPUT_FORMAT>
ERROR_ID: E1
DESCRIPTION: Function missing null check
LOCATION: src/utils/parser.ts:45
SEVERITY: HIGH

ERROR_ID: E2
...
</OUTPUT_FORMAT>

ステップ 3: 各エラーを逆方向にトレースする

特定された各エラーについて、トレースエージェントを起動します:

<TASK>
Trace this error backward through the agent chain to find its origin.
</TASK>

<ERROR>
{error_description}
</ERROR>

<AGENT_CHAIN_OUTPUTS>
Agent 1 Output: {output_1}
Agent 2 Output: {output_2}
Agent 3 Output: {output_3}
Agent 4 Output: {output_4}
</AGENT_CHAIN_OUTPUTS>

<ANALYSIS_APPROACH>
For each agent output (starting from the last):
1. Does this output contain the error?
2. If yes, was the error present in the input to this agent?
3. If error is in output but not input: This agent INTRODUCED the error
4. If error is in both: This agent PROPAGATED the error
</ANALYSIS_APPROACH>

<OUTPUT_FORMAT>
ERROR: {error_id}
ORIGIN_AGENT: Agent {N}
ORIGIN_TYPE: [INTRODUCED | PROPAGATED_FROM_CONTEXT | PROPAGATED_FROM_TOOL_OUTPUT]
ROOT_CAUSE: {explanation}
CONTEXT_THAT_CAUSED_IT: {relevant context snippet if applicable}
</OUTPUT_FORMAT>

ステップ 4: 伝播メトリクスを計算する

For each agent in chain:
  errors_introduced = count of errors this agent created
  errors_propagated = count of errors this agent passed through
  errors_caught = count of errors this agent fixed or flagged

propagation_rate = errors_at_end / errors_introduced_total
amplification_factor = errors_at_end / errors_at_start

ステップ 5: エラー境界を確立する

分析に基づいて、検証チェックポイントを追加します:

<ERROR_BOUNDARY_TEMPLATE>
After Agent {N} completes:

1. Spawn verification agent to check for common error patterns:
   - {error_pattern_1 that Agent N tends to introduce}
   - {error_pattern_2 that Agent N tends to introduce}

2. If errors detected:
   - Log error for analysis
   - Either: Fix inline and continue
   - Or: Regenerate Agent N output with explicit guidance

3. Only proceed to Agent {N+1} if verification passes
</ERROR_BOUNDARY_TEMPLATE>

コンテキスト関連性スコアリングワークフロー

プロンプトのすべての部分が、タスクの完了に等しく貢献するわけではありません。このワークフローは、価値を追加することなくアテンション予算を消費する、プロンプト内の妨害的部分を特定します。

使用するタイミング

• プロンプトの長さと内容を最適化するとき
• CLAUDE.md に何を含めるかを決定するとき
• プロンプトが肥大化していると感じるが、何を削除すべきかわからないとき
• 提供されたコンテキストを無視するエージェントをデバッグするとき
• 新しいコマンド、スキル、エージェントプロンプトをデプロイする前

妨害的部分の特定パターン

ステップ 1: プロンプトを部分に分割する

プロンプト(コマンド/スキル/エージェント)を論理的なセクションに分割します。各部分はまとまりのある単位であるべきです:

<PROMPT_PARTS>
PART_1:
  ID: background
  CONTENT: |
    You are a Python expert helping a development team.
    Current project: Data processing pipeline in Python 3.9+

PART_2:
  ID: code_style_rules
  CONTENT: |
    - Write clean, idiomatic Python code
    - Include type hints for function signatures
    - Add docstrings for public functions
    - Follow PEP 8 style guidelines

PART_3:
  ID: historical_context
  CONTENT: |
    The project was migrated from Python 2.7 in 2019.
    Original team used camelCase naming but we now use snake_case.
    Legacy modules in /legacy folder are frozen.

PART_4:
  ID: output_format
  CONTENT: |
    Provide actionable feedback with specific line references.
    Explain the reasoning behind suggestions.
</PROMPT_PARTS>

分割のガイドライン:

• 各 XML セクションまたは Markdown 見出しが 1 つの部分になります
• 概念的にはっきり異なる指示は、それぞれ別の部分に分けます
• 関連する指示はまとめておきます(思考の途中で分割しないでください)
• プロンプトの長さに応じて、3〜15 個の部分を目指します

ステップ 2: スコアリングエージェントを起動する

複数のスコアリングエージェントを並列で起動します:

<TASK>
Score how relevant this prompt parts is for accomplishing the specified task.
</TASK>

<TASK_DESCRIPTION>
{description of what the agent should accomplish}
Example: "Review a pull request for code quality issues and suggest improvements"
</TASK_DESCRIPTION>

<PROMPT_PARTS>
{contents of all the parts being evaluated}
</PROMPT_PARTS>

<SCORING_CRITERIA>
Score 0-10 based on these criteria:

ESSENTIAL (8-10):
- Part directly enables task completion
- Removing this part would cause task failure
- Part contains critical constraints that prevent errors
- Part defines required output format or structure

HELPFUL (5-7):
- Part improves output quality but is not strictly required
- Part provides useful context that guides better decisions
- Part contains preferences that affect style but not correctness

MARGINAL (2-4):
- Part has tangential relevance to the task
- Part might occasionally be useful but usually is not
- Part provides historical context rarely needed

DISTRACTOR (0-1):
- Part is irrelevant to the task
- Part could confuse the agent about what to focus on
- Part competes for attention without contributing value
</SCORING_CRITERIA>

<OUTPUT_FORMAT>
RELEVANCE_SCORE: [0-10]
JUSTIFICATION: [2-3 sentences explaining the score]
USAGE_LIKELIHOOD: [How often would the agent reference this part during task execution? ALWAYS | OFTEN | SOMETIMES | RARELY | NEVER]
</OUTPUT_FORMAT>

ステップ 3: 関連性スコアを集計する

すべてのスコアリングエージェントからスコアを収集します:

PART_SCORES = [
  {id: "background", score: 8, usage: "ALWAYS"},
  {id: "code_style_rules", score: 9, usage: "ALWAYS"},
  {id: "historical_context", score: 3, usage: "RARELY"},
  {id: "output_format", score: 7, usage: "OFTEN"}
]

集計メトリクスを計算します:

total_parts = count(PART_SCORES)
high_relevance_parts = count(parts where score >= 5)
distractor_parts = count(parts where score < 5)

context_efficiency = high_relevance_parts / total_parts
average_relevance = sum(scores) / total_parts

ステップ 4: 妨害的部分を特定する

妨害的しきい値(スコア < 5)を適用します:

DISTRACTOR_ANALYSIS:

Identified Distractors:
1. PART: historical_context
   SCORE: 3/10
   JUSTIFICATION: "Migration history from Python 2.7 is rarely relevant to reviewing current code. The naming convention note is useful but should be in code_style_rules instead."
   RECOMMENDATION: REMOVE or RELOCATE

Summary:
- Total parts: 4
- High-relevance parts (>=5): 3
- Distractor parts (<5): 1
- Context efficiency: 75%
- Average relevance: 6.75

Token Impact:
- Distractor tokens: ~45 (historical_context)
- Potential savings: 45 tokens (11% of prompt)

ステップ 5: 最適化の推奨事項を生成する

妨害的部分の分析に基づいて、実行可能な推奨事項を提供します:

OPTIMIZATION_RECOMMENDATIONS:

1. REMOVE: historical_context
   Reason: Score 3/10, usage RARELY. Migration history does not inform code review decisions.

2. RELOCATE: "we now use snake_case" from historical_context
   Target: code_style_rules section
   Reason: This specific rule is relevant but buried in irrelevant historical context.

3. CONSIDER CONDENSING: background
   Current: 2 sentences
   Could be: 1 sentence ("Python 3.9+ data pipeline expert")
   Savings: ~15 tokens

OPTIMIZED PROMPT STRUCTURE:
- background (condensed): 8 tokens
- code_style_rules (with snake_case added): 52 tokens
- output_format: 28 tokens
- Total: 88 tokens (down from 133 tokens)
- Efficiency improvement: 34% reduction

妨害的しきい値のガイドライン

デフォルトのしきい値である 5 は、網羅性と効率性のバランスを取ります:

しきい値	ユースケース
< 3	トークンが制約されたコンテキスト向けの積極的な刈り込み
< 5	標準的な最適化(推奨デフォルト)
< 7	重要なプロンプト向けの保守的な刈り込み

しきい値は以下に基づいて調整してください:

• コンテキスト予算の圧迫: 上限に近づいているときはしきい値を下げます
• タスクの重要度: 本番プロンプトではしきい値を上げます
• プロンプトの安定性: 実験的なプロンプトではしきい値を下げます

スコアリングエージェントのデプロイ

効率化のために、スコアリングエージェントを並列化します:

# Parallel execution pattern
spawn_parallel([
  scoring_agent(part_1, task_description),
  scoring_agent(part_2, task_description),
  scoring_agent(part_3, task_description),
  ...
])

# Collect and aggregate
scores = await_all(scoring_agents)
analysis = aggregate_scores(scores)

大きなプロンプト(10 個を超える部分)の場合、オーケストレーションのオーバーヘッドを管理するために、スコアリングエージェントを 5〜7 個ずつのグループに分けてバッチ処理します。

コンテキストヘルスモニタリングワークフロー

長時間実行されるエージェントセッションでは、時間の経過とともに劣化するコンテキストが蓄積されます。このワークフローは、コンテキストのヘルスを監視し、介入をトリガーします。

使用するタイミング

• 長時間実行されるエージェントセッション中(20 ターンを超える場合)
• エージェントが劣化症状を示し始めたとき
• エージェントオーケストレーションシステムにおける定期的なヘルスチェックとして
• エージェントワークフローにおける重要な意思決定ポイントの前

ヘルスチェックパターン

ステップ 1: 定期的な症状検出

N ターンごと(推奨: 10 ターンごと)に、ヘルスチェックエージェントを起動します:

<TASK>
Analyze the recent conversation history for signs of context degradation.
</TASK>

<RECENT_HISTORY>
{last 10 turns of conversation}
</RECENT_HISTORY>

<SYMPTOM_CHECKLIST>
Check for these degradation symptoms:

LOST_IN_MIDDLE:
- [ ] Agent missing instructions from early in conversation
- [ ] Critical constraints being ignored
- [ ] Agent asking for information already provided

CONTEXT_POISONING:
- [ ] Same error appearing repeatedly
- [ ] Agent referencing incorrect information as fact
- [ ] Hallucinations that persist despite correction

CONTEXT_DISTRACTION:
- [ ] Responses becoming unfocused
- [ ] Agent using irrelevant context inappropriately
- [ ] Quality declining on previously-successful tasks

CONTEXT_CONFUSION:
- [ ] Agent mixing up different task requirements
- [ ] Wrong tool selections for obvious tasks
- [ ] Outputs that blend requirements from different tasks

CONTEXT_CLASH:
- [ ] Agent expressing uncertainty about conflicting information
- [ ] Inconsistent behavior between turns
- [ ] Agent asking for clarification on resolved issues
</SYMPTOM_CHECKLIST>

<OUTPUT_FORMAT>
HEALTH_STATUS: [HEALTHY | DEGRADED | CRITICAL]
SYMPTOMS_DETECTED: [list of checked symptoms]
RECOMMENDED_ACTION: [CONTINUE | COMPACT | RESTART]
SPECIFIC_ISSUES: [detailed description of problems found]
</OUTPUT_FORMAT>

ステップ 2: 自動介入

ヘルスステータスに基づいて、適切な介入をトリガーします:

IF HEALTH_STATUS == "DEGRADED" or HEALTH_STATUS == "CRITICAL":
  <RESTART_INTERVENTION>
  1. Extract essential state to preserve and save to a file
  2. Ask user to start a new session with clean context and load the preserved state from the file after the new session is started
  </RESTART_INTERVENTION>

マルチエージェント検証のガイドライン

1. 焦点を絞った単一目的のプロンプトで検証エージェントを起動します
2. 信頼性の高い解析のために構造化された出力形式を使用します
3. 続行するかアクションを起こすかの明確なしきい値を設定します
4. デバッグと最適化のために、すべての検証結果をログに記録します
5. 検証のオーバーヘッドとエラー防止の価値のバランスを取ります
6. 毎ターンではなく、自然なチェックポイントで検証を実装します
7. 定常的な操作には軽量なチェックを、重要な操作にはより重いチェックを使用します
8. 時間が重要なシナリオではスキップ可能なように検証を設計します

コンテキスト最適化の手法

コンテキスト最適化では、圧縮、マスキング、キャッシュ、分割を戦略的に活用し、限られたコンテキストウィンドウの実効容量を拡張します。目的は、コンテキストウィンドウを魔法のように大きくすることではなく、利用可能な容量をより効果的に使うことです。効果的に最適化すれば、より大きなモデルや長いコンテキストを必要とせずに、実効容量を2倍、あるいは3倍に増やせます。

基本概念

コンテキスト最適化では、主に4つの戦略を通じて実効容量を拡張します。コンパクション（上限に近づいたコンテキストを要約する）、観測のマスキング（冗長な出力を参照情報に置き換える）、KV キャッシュの最適化（キャッシュ済みの計算を再利用する）、コンテキストの分割（作業を分離されたコンテキストに分ける）です。

重要なのは、コンテキストの質が量よりも大切だという点です。最適化では、ノイズを減らしながら重要な情報を保ちます。何を残し、何を捨てるか、そして各手法をいつ適用するかが肝心です。

詳細なトピック

コンパクションの戦略

コンパクションとは コンパクションとは、上限に近づいたときにコンテキストの内容を要約し、その要約を使って新しいコンテキストウィンドウを初期化する手法です。これにより、コンテキストウィンドウの内容を高い忠実度で要約でき、パフォーマンスの低下を最小限に抑えながらエージェントが作業を続けられます。

コンパクションは通常、コンテキスト最適化における最初の手段です。何を残し、何を捨てるかが肝心です。

実際のコンパクション コンパクションでは、圧縮できる箇所を特定し、重要な点を捉えた要約を作成して、元の内容を要約に置き換えます。圧縮の優先順位は次のとおりです。

1. ツールの出力 - 冗長な出力を重要な調査結果に置き換えます
2. 古い会話のターン - 初期のやり取りを要約します
3. 取得したドキュメント - タスクのコンテキストを取り込めている場合は要約します
4. 圧縮しないもの - システムプロンプトと重要な制約

要約の生成 効果的な要約では、内容の種類に応じて異なる要素を保持します。

• ツールの出力：重要な調査結果、指標、結論を保持します。冗長な生の出力は削除します。
• 会話のターン：重要な決定、約束、コンテキストの変化を保持します。不要な部分や応酬は削除します。
• 取得したドキュメント：重要な事実や主張を保持します。それを裏付ける証拠や詳細な説明は削除します。

観測のマスキング

観測の問題 エージェントの実行履歴では、ツールの出力がトークン使用量の80％以上を占めることがあります。その多くは、すでに役目を終えた冗長な出力です。エージェントがツールの出力を使って判断した後は、出力全体を保持しても得られる価値は次第に小さくなる一方で、コンテキストを大きく消費します。

観測のマスキングでは、冗長なツールの出力を簡潔な参照情報に置き換えます。必要であれば情報にアクセスできますが、常にコンテキストを消費することはありません。

マスキング戦略の選択 すべての観測を同じようにマスキングすべきではありません。

マスキングしないもの：

• 現在のタスクに不可欠な観測
• 最も直近のターンからの観測
• 現在の推論で使用中の観測

マスキングを検討するもの：

• 3ターン以上前の観測
• 重要な点を抽出できる冗長な出力
• すでに役目を終えた観測

必ずマスキングするもの：

• 繰り返される出力
• 定型的なヘッダーやフッター
• すでに会話内で要約されている出力

コンテキストの分割

サブエージェントによる分割 最も積極的なコンテキスト最適化の方法は、コンテキストを分離したサブエージェントに作業を分割することです。各サブエージェントは、ほかのサブタスクで蓄積されたコンテキストを引き継がず、担当するサブタスクに集中できるクリーンなコンテキストで動作します。

この方法では、関心事を分離できます。詳細な検索コンテキストはサブエージェント内に隔離され、コーディネーターは統合と分析に集中できます。

分割するタイミング 次の場合は、分割を検討してください。

• タスクを自然に独立したサブタスクに分解できる
• サブタスクごとに異なる専門的なコンテキストが必要である
• コンテキストの蓄積によって上限を超えるおそれがある
• サブタスクごとに要件が競合する

結果の統合 分割したサブタスクの結果は、次の手順で統合します。

1. すべての分割タスクが完了していることを確認する
2. 互換性のある結果を統合する
3. 統合後の結果がまだ大きすぎる場合は要約する
4. 分割した各タスクの出力間の競合を解決する

実践的なガイダンス

最適化の判断フレームワーク

最適化するタイミング：

• 会話が長くなるにつれて応答品質が低下する
• 長いコンテキストによってコストが増加する
• 会話の長さに伴ってレイテンシーが増加する

適用する方法：

• ツールの出力が大部分を占める場合：観測データのマスキング
• 取得したドキュメントが大部分を占める場合：要約または分割
• メッセージ履歴が大部分を占める場合：要約を伴う圧縮
• 複数の要素がある場合：複数の戦略を組み合わせる

Claude Code のプロンプトへの最適化の適用

コマンドの最適化 コマンドは必要に応じて読み込まれるため、個々のコマンドに焦点を絞ることに重点を置きます。

# Good: Focused command with clear scope
---
name: review-security
description: Review code for security vulnerabilities
---
# Specific security review instructions only

# Avoid: Overloaded command trying to do everything
---
name: review-all
description: Review code for everything
---
# 50 different review checklists crammed together

スキルの最適化 スキルの説明はデフォルトで読み込まれるため、簡潔にする必要があります。

# Good: Concise description
description: Analyze code architecture. Use for design reviews.

# Avoid: Verbose description that wastes context budget
description: This skill provides comprehensive analysis of code
architecture including but not limited to class hierarchies,
dependency graphs, coupling metrics, cohesion analysis...

サブエージェントのコンテキスト設計 サブエージェントを起動する際は、焦点を絞ったコンテキストを提供します。

# Coordinator provides minimal handoff:
"Review authentication module for security issues.
Return findings in structured format."

# NOT this verbose handoff:
"I need you to look at the authentication module which is
located in src/auth/ and contains several files including
login.ts, session.ts, tokens.ts... [500 more tokens of context]"

ガイドライン

1. 最適化する前に測定し、現状を把握する
2. 可能であれば、マスキングより先に圧縮を適用する
3. 一貫したプロンプトでキャッシュの安定性を確保する
4. コンテキストが問題になる前に分割する
5. 最適化の効果を継続的に監視する
6. トークンの節約と品質の維持のバランスを取る
7. 本番環境の規模で最適化をテストする
8. エッジケースに備えて、段階的に機能を縮退できるようにする