moai-foundation-context

クイックリファレンス

エンタープライズ向けのコンテキストおよびセッション管理 — 200K トークンの予算管理、セッションの永続化、マルチエージェントの引き継ぎプロトコルを備えた、Claude Code 向けの統合コンテキスト最適化およびセッション状態管理です。

主な機能：

• 200K トークンの予算割り当てと監視
• 永続化を伴うセッション状態の追跡
• コンテキストを考慮したトークン最適化
• マルチエージェントの引き継ぎプロトコル
• 段階的な情報開示とメモリ管理
• 並行探索のためのセッション分岐

使用する場面：

• セッションの初期化とクリーンアップ
• 10 分を超える長時間のワークフロー
• マルチエージェントのオーケストレーション
• コンテキストウィンドウが 150K トークンを超えて上限に近づいている場合
• Haiku と Sonnet 間でモデルを切り替える場合
• ワークフローのフェーズが移行する場合

主な原則：

最後の 20% を避ける：コンテキストウィンドウの最後の 5 分の 1 では、パフォーマンスが低下します。

積極的なクリア：SPEC ワークフローでは、1～3 メッセージごとに /clear を実行します。

簡潔なメモリファイル：各ファイルを 500 行未満に保ちます。

未使用の MCP を無効化：ツール定義のオーバーヘッドを最小限に抑えます。

量より質：関連性のあるコンテキスト 10% は、ノイズ 90% に勝ります。

---

実装ガイド

機能

• Claude Code セッション向けのインテリジェントなコンテキストウィンドウ管理
• 優先度ベースのキャッシュによる段階的なファイル読み込み
• トークン予算の追跡と最適化アラート
• /clear の前後でコンテキストを選択的に保持
• MCP 統合コンテキストの永続化

使用する場面

• 150K トークンの上限を超える大規模なコードベースの管理
• 長時間の開発セッションにおけるトークン使用量の最適化
• セッションのリセットをまたいだ重要なコンテキストの保持
• 共有コンテキストを使ったマルチエージェントワークフローの調整
• Claude Code でのコンテキスト関連の問題のデバッグ

主なパターン

パターン 1 — 段階的なファイル読み込み：

優先度の段階に従ってファイルを読み込みます。第 1 段階には、常に読み込まれる CLAUDE.md と config.json が含まれます。第 2 段階には、現在の SPEC と実装ファイルが含まれます。第 3 段階には、関連モジュールと依存関係が含まれます。第 4 段階には、必要に応じて読み込むリファレンスドキュメントが含まれます。

パターン 2 — コンテキストのチェックポイント作成：

トークン使用量を監視し、150K で警告、180K で重大警告を出します。保持すべき重要なコンテキストを特定します。/clear を実行してセッションをリセットします。第 1 段階と第 2 段階のファイルを自動的に再読み込みします。保持したコンテキストを使って作業を再開します。

パターン 3 — MCP コンテキストの継続性：

agent_id を保存することで、/clear の前後で MCP エージェントのコンテキストを保持します。/clear の後は、MCP エージェントを新たに初期化してコンテキストを復元します。

主なパターンの詳細

パターン 1：トークン予算の管理

概念：200K トークンのコンテキストウィンドウを戦略的に割り当て、監視します。

予算の内訳：システムプロンプトと指示には約 15K トークン（7.5%）を割り当てます。内訳は CLAUDE.md が 8K、コマンド定義が 4K、スキルのメタデータが 3K です。アクティブな会話には約 80K トークン（40%）を割り当てます。内訳は最近のメッセージが 50K、コンテキストキャッシュが 20K、アクティブな参照情報が 10K です。段階的な情報開示を伴う参照コンテキストには約 50K トークン（25%）を割り当てます。内訳はプロジェクト構造が 15K、関連スキルが 20K、ツール定義が 15K です。緊急復旧用の予備には約 55K トークン（27.5%）を割り当てます。内訳はセッション状態のスナップショットが 10K、TAG と相互参照が 15K、エラー復旧コンテキストが 20K、空きバッファーが 10K です。

監視のしきい値：使用量が 85% を超えた場合、緊急圧縮を実行し、clear コマンドを実行します。使用量が 75% を超えた場合、重要度の低いコンテキストの追加を延期し、上限が近づいていることをユーザーに警告します。使用量が 60% を超えた場合、コンテキストの増加パターンを追跡します。

ユースケース：SPEC First の長時間ワークフローでコンテキストのオーバーフローを防ぎます。

パターン 2: 積極的な /clear 戦略

概念: 戦略的なチェックポイントでプロアクティブにコンテキストをクリアし、効率を維持します。

必須の /clear ポイント: /moai:1-plan の完了後、45～50K トークンを節約するため。コンテキストが 150K トークンを超えたとき、オーバーフローを防ぐため。会話が 50 メッセージを超えたとき、古い履歴を削除するため。主要なフェーズ遷移の前に、クリーンな状態にするため。モデル切り替え時、Haiku から Sonnet へのハンドオフの間。

ユースケース: SPEC-Run-Sync サイクル全体でトークン効率を最大化します。

パターン 3: セッション状態の永続化

概念: 状態スナップショットによって、中断をまたいでセッションの継続性を維持します。

セッション状態のレイヤー: L1 は Claude 4.5+ 向けのコンテキスト認識レイヤーで、トークン予算のトラッキング、コンテキストウィンドウの位置、自動要約トリガー、モデル固有の最適化を含みます。L2 は現在のタスク、変数、スコープのためのアクティブコンテキストです。L3 は最近のアクションと決定のためのセッション履歴です。L4 は SPEC の進捗とマイルストーンのためのプロジェクト状態です。L5 は好み、言語、専門知識のためのユーザーコンテキストです。L6 はツール、権限、環境のためのシステム状態です。

ユースケース: コンテキストを失うことなく、中断後に長時間実行タスクを再開します。

パターン 4: マルチエージェントハンドオフプロトコル

概念: 最小限のトークンオーバーヘッドで、エージェント間のシームレスなコンテキスト転送を行います。

ハンドオフパッケージの内容: handoff_id、from_agent、to_agent、session_id・model・context_position・available_tokens・user_language を含む session_context、spec_id・current_phase・completed_steps・next_step を含む task_context、last_checkpoint・recovery_tokens_reserved・session_fork_available を含む recovery_info を含めます。

ハンドオフの検証: 最低 30K の利用可能バッファでトークン予算を確認します。エージェントの互換性を検証します。必要に応じてコンテキスト圧縮をトリガーします。

ユースケース: Plan から Run、Sync への効率的なワークフロー実行。

パターン 5: 段階的開示とメモリ最適化

概念: 関連性と必要性に基づいてコンテキストを段階的に読み込みます。

段階的要約: ターゲット比率 0.3 で、50K を 15K に圧縮するために重要な文を抽出します。参照用に元のコンテンツへのポインタを追加します。復元のために元のコンテンツをセッションアーカイブに保存します。結果として約 35K トークンを節約します。

コンテキストのタグ付け: 「The user configuration from the previous 20 messages...」のようなトークンコストの高いフレーズを避け、「Refer to @CONFIG-001 for user preferences」のような効率的な参照を使用します。

ユースケース: トークンオーバーヘッドを最小化しながらコンテキストの継続性を維持します。

---

高度なドキュメント

詳細なパターンと実装戦略については:

• modules/token-budget-allocation.md - 予算の内訳、割り当て戦略、監視しきい値
• modules/session-state-management.md - 状態レイヤー、永続化、再開パターン
• modules/context-optimization.md - 段階的開示、要約、メモリ管理
• modules/handoff-protocols.md - エージェント間通信、パッケージ形式、検証
• modules/memory-mcp-optimization.md - メモリファイル構造、MCP サーバー設定
• modules/reference.md - API リファレンス、トラブルシューティング、ベストプラクティス

---

ベストプラクティス

推奨プラクティス：

• SPEC の作成直後に /clear を実行する
• トークンの使用量を監視し、計画的に対応する
• コンテキストを考慮したトークン予算の追跡を使用する
• 重要な操作の前にチェックポイントを作成する
• 長いワークフローには段階的な要約を適用する
• 復旧に備えてセッションの永続化を有効にする
• 並行して調査する際はセッションのフォークを使用する
• 各メモリファイルを 500 行未満に保つ
• オーバーヘッドを削減するため、使用していない MCP サーバーを無効にする

必須プラクティス：

定期的にクリアを行い、コンテキスト履歴を一定の範囲内に保ちます。コンテキストが際限なく蓄積すると、パフォーマンスが低下し、トークンコストが指数関数的に増加します。これにより、コンテキストのオーバーフローを防ぎ、応答品質を一定に保ち、トークンの無駄を 60～70% 削減できます。

トークン使用量が 150K トークンを超えた場合は、トークン予算の警告に直ちに対応します。コンテキストウィンドウの最後の 20% で動作すると、パフォーマンスが大幅に低下します。

セッションの復旧中に状態の検証チェックを実行します。状態が無効な場合、複数ステップのプロセスでワークフローの失敗やデータ損失が発生する可能性があります。

コンテキストをクリアする前に、セッション ID を永続化します。セッション ID は、中断されたワークフローを再開するための唯一の信頼できる方法です。

使用率が 85% のしきい値に達したら、コンテキストの圧縮またはクリアを実行します。これにより、緊急用に 55K トークンを確保し、強制的な中断を防ぎます。

---

相性の良いツール

• moai-cc-memory - メモリ管理とコンテキストの永続化
• moai-cc-configuration - セッション設定と環境設定
• moai-core-workflow - ワークフロー状態の永続化と復旧
• moai-cc-agents - セッション間のエージェント状態管理
• moai-foundation-trust - 品質ゲートとの統合

---

ワークフローとの統合

セッションの初期化：パターン 1 でトークン予算を初期化し、パターン 3 でセッション状態を読み込み、パターン 5 で段階的な開示を設定し、パターン 4 でハンドオフプロトコルを構成します。

SPEC 優先のワークフロー：/moai:1-plan を実行し、続いて必須の /clear で 45～50K トークンを節約し、その後 /moai:2-run SPEC-XXX を実行します。続いてパターン 4 で複数エージェントへのハンドオフを行い、/moai:3-sync SPEC-XXX を実行してから、パターン 3 でセッション状態を永続化します。

コンテキストの監視：パターン 1 でトークン使用量を継続的に追跡し、パターン 5 で段階的な開示を適用し、しきい値に達したらパターン 2 で /clear を実行し、パターン 4 でハンドオフを検証します。

---

成功指標

• トークン効率：積極的なクリアにより 60～70% 削減
• コンテキストのオーバーヘッド：システム／スキルのメタデータが 15K トークン未満
• ハンドオフ成功率：検証により 95% 超
• セッション復旧：状態の永続化により 5 秒未満
• メモリの最適化：各メモリファイルが 500 行未満

---

ステータス：本番環境で使用可能（エンタープライズ） モジュラーアーキテクチャ：SKILL.md + 6 モジュール 統合：Plan-Run-Sync ワークフローに最適化 生成元：MoAI-ADK Skill Factory