ファイルシステムベースのコンテキストエンジニアリング

ファイルシステムをエージェントコンテキストの主要なオーバーフローレイヤーとして使用してください。コンテキストウィンドウは限定的である一方、タスクはしばしば単一ウィンドウに収まるよりも多くの情報を必要とするためです。ファイルによって、エージェントは単一のインターフェースを通じて、事実上無制限の量のコンテキストを保存、取得、更新できます。

静的な包含よりも動的なコンテキスト発見（オンデマンドで関連するコンテキストを取得すること）を優先してください。静的なコンテキストは関連性に関わらず常にトークンを消費し、タスク固有の情報のための空間を圧迫するためです。

アクティベーションのタイミング

以下の場合にこのスキルをアクティベートしてください：

• ツール出力がコンテキストウィンドウを肥大化させている
• エージェントが長い軌跡全体で状態を永続化する必要がある
• サブエージェントが直接メッセージパッシングなしに情報を共有する必要がある
• タスクがウィンドウに収まるより多くのコンテキストを必要とする
• 独自の命令を学習・更新するエージェントを構築している
• 中間結果用のスクラッチパッドを実装している
• ターミナル出力またはログをエージェントがアクセスする必要がある

コアコンセプト

これら4つのモードに対してコンテキスト障害を診断してください。各モードは異なるファイルシステムの対応策を必要とするためです：

1. コンテキスト欠落 -- 必要な情報が利用可能な合計コンテキストから欠落している。ツール出力と中間結果をファイルに永続化することで修正して、何も失われないようにしてください。
2. コンテキスト取得不足 -- 取得されたコンテンツがエージェントが必要とするものを正確に表現できない。ファイルを対象取得用に構造化することで修正してください（grep対応形式、明確なセクションヘッダー）。
3. コンテキスト過剰取得 -- 取得されたコンテンツが必要とされるものをはるかに超えており、トークンを無駄にしており注意力を低下させている。バルクコンテンツをファイルにオフロードし、コンパクトな参照を返すことで修正してください。
4. 埋もれたコンテキスト -- ニッチな情報が多数のファイルに分散している。構造的検索用にglobとgrepを組み合わせる一方で、概念的なクエリに対してセマンティック検索を使用することで修正してください。

ファイルシステムをこれら4つすべてに対応する永続層として使用してください：一度書き込むと耐久的に保存され、選別的に取得できます。

詳細トピック

静的コンテキスト対動的コンテキストのトレードオフ

静的コンテキスト（システム命令、ツール定義、重要なルール）を高価な不動産として扱ってください -- 関連性に関わらず毎ターン常にトークンを消費します。エージェントが機能を蓄積するにつれて、静的コンテキストは増加し、動的情報のための空間を圧迫します。

代わりに動的コンテキスト発見を使用してください：最小限の静的ポインタ（名前、1行の説明、ファイルパス）のみを含め、関連する場合に検索ツールで完全なコンテンツを読み込んでください。これはより効率的なトークン使用につながり、しばしばウィンドウ内の矛盾した、または無関係な情報を削減することで応答品質を向上させます。

トレードオフを受け入れてください：動的発見は、モデルがより多くのコンテキストを必要とするときを認識する必要があります。現在のフロンティアモデルはこれをうまく処理していますが、能力が低いモデルは読み込みのトリガーに失敗することがあります。疑わしい場合は、重要なセキュリティまたは正確性の制約を静的に含めることに偏ってください。

パターン1：スクラッチパッドとしてのファイルシステム

大きなツール出力をコンテキストに直接返す代わりにファイルにリダイレクトしてください。単一のウェブ検索またはデータベースクエリは、数千のトークンをメッセージ履歴に投下し、会話全体を通じて永続化する可能性があるためです。

出力をスクラッチファイルに書き込み、コンパクトな概要を抽出し、ファイル参照を返してください。エージェントはその後、ターゲット検索（パターン用のgrep、範囲指定の読み込み）を使用して、必要なものだけにアクセスします。

def handle_tool_output(output: str, threshold: int = 2000) -> str:
    if len(output) < threshold:
        return output

    file_path = f"scratch/{tool_name}_{timestamp}.txt"
    write_file(file_path, output)

    key_summary = extract_summary(output, max_tokens=200)
    return f"[Output written to {file_path}. Summary: {key_summary}]"

オフロードされたファイルをgrepで検索し、ラインレンジを指定してread_fileを使用してください。これは後の参照用に完全な出力を保持しながら、アクティブなコンテキストに約100トークンのみを保つのに役立ちます。

パターン2：計画の永続化

長期的なタスクが注意から外れたり、要約によって失われたりするため、計画をファイルシステムに書き込んでください。エージェントは任意の時点で計画を再読み込みして、目的とプログレスの認識を復元できます。

計画を構造化形式で保存して、人間が読める形式とマシンがパースできる形式の両方になるようにしてください：

# scratch/current_plan.yaml
objective: "Refactor authentication module"
status: in_progress
steps:
  - id: 1
    description: "Audit current auth endpoints"
    status: completed
  - id: 2
    description: "Design new token validation flow"
    status: in_progress
  - id: 3
    description: "Implement and test changes"
    status: pending

各ターンの開始時またはコンテキストリフレッシュ後に計画を再読み込みして、再方向付けしてください。これは「朗誦による注意操作」として機能します。

パターン3：ファイルシステムを介したサブエージェント通信

メッセージパッシングの代わりに、ファイルシステムを通じてサブエージェント調査結果をルーティングしてください。マルチホップメッセージチェーンは各ホップでの要約を通じて情報を低下させるためです（「ゲーム・オブ・テレフォン」）。

各サブエージェントに自身のワークスペースディレクトリに直接書き込ませてください。コーディネーターはこれらのファイルを直接読み込み、完全なフィデリティを保持します：

workspace/
  agents/
    research_agent/
      findings.md
      sources.jsonl
    code_agent/
      changes.md
      test_results.txt
  coordinator/
    synthesis.md

エージェントごとのディレクトリ分離を強制して、書き込みの競合を防ぎ、各出力アーティファクトの所有権を明確に保つようにしてください。

パターン4：動的スキル読み込み

スキルをファイルとして保存し、静的コンテキストには名前と簡潔な説明のみを含めてください。すべての命令をシステムプロンプトに詰め込むことはトークンを無駄にし、矛盾したガイダンスでモデルを混乱させる可能性があるためです。

Available skills (load with read_file when relevant):
- database-optimization: Query tuning and indexing strategies
- api-design: REST/GraphQL best practices
- testing-strategies: Unit, integration, and e2e testing patterns

現在のタスクがそれを要求する場合にのみ、完全なスキルファイル（例：skills/database-optimization/SKILL.md）を読み込んでください。これにより、O(n)の静的トークンコストをタスクごとのO(1)に変換できます。

パターン5：ターミナルおよびログの永続化

ターミナル出力を自動的にファイルに永続化し、選別的な取得用にgrepを使用してください。長時間実行プロセスからのターミナル出力は急速に蓄積し、手動コピー・ペーストはエラーが発生しやすいためです。

terminals/
  1.txt    # Terminal session 1 output
  2.txt    # Terminal session 2 output

ターミナル履歴全体をコンテキストに読み込む代わりに、ターゲット化されたgrepでクエリしてください（grep -A 5 "error" terminals/1.txt）。

パターン6：自己変更による学習

エージェントが習得した優先事項とパターンを独自の命令ファイルに書き込み、以降のセッションがこのコンテキストを自動的に読み込むようにしてください。これにより、手動でのシステムプロンプト更新が不要になります。

def remember_preference(key: str, value: str):
    preferences_file = "agent/user_preferences.yaml"
    prefs = load_yaml(preferences_file)
    prefs[key] = value
    write_yaml(preferences_file, prefs)

自己変更は時間とともに正確でない、または矛盾した命令を蓄積する可能性があるため、このパターンは検証で保護してください。それを実験的として扱い -- 永続化された優先事項を定期的に確認してください。

ファイルシステム検索技法

コンテキスト発見用にls/list_dir、glob、grep、およびラインレンジ付きread_fileを組み合わせてください。モデルはファイルシステムトラバーサルで特別に訓練されており、この組み合わせはしばしば構造パターンが明確な技術コンテンツに対するセマンティック検索をしのぐためです。

• ls / list_dir：ディレクトリ構造を発見
• glob：パターンに一致するファイルを検出（例：**/*.py）
• grep：ファイル内容を検索し、コンテキスト付きの一致する行を返す
• read_file（範囲付き）：ファイル全体を読み込まずに特定のセクションを読む

構造的および完全一致クエリにはファイルシステム検索を使用し、概念的クエリにはセマンティック検索を使用してください。包括的な発見用に両方を組み合わせてください。

実践的なガイダンス

ファイルシステムコンテキストをいつ使用するか

これらの基準に状況が一致する場合にファイルシステムパターンを適用してください。それらはトークン節約または永続化のニーズで正当化される場合にのみI/Oオーバーヘッドを追加するためです。

使用する場合：

• ツール出力が約2000トークンを超えている
• タスクが複数の会話ターンにわたっている
• 複数のエージェントが共有された状態を必要とする
• スキルまたは命令が快適なシステムプロンプトサイズを超えている
• ログまたはターミナル出力を選別的にクエリする必要がある

避ける場合：

• タスクが単一ターンで完了する（オーバーヘッドが正当化されない）
• コンテキストがウィンドウに快適に収まる（解決する問題がない）
• レイテンシが重要である（ファイルI/Oが測定可能な遅延を追加する）
• モデルにファイルシステムツール機能がない

ファイル組織

エージェント発見用にファイルを構造化してください。エージェントはディレクトリ名のリストと読み込みで移動するためです：

project/
  scratch/           # Temporary working files
    tool_outputs/    # Large tool results
    plans/           # Active plans and checklists
  memory/            # Persistent learned information
    preferences.yaml # User preferences
    patterns.md      # Learned patterns
  skills/            # Loadable skill definitions
  agents/            # Sub-agent workspaces

一貫した命名規則を使用し、スクラッチファイルにタイムスタンプまたはIDを含めて曖昧性を解決してください。

トークン会計

ファイルシステムパターンを適用する前後でトークンがどこから発生するかを測定してください。測定なしで最適化すると、無駄な労力につながるためです：

• 静的コンテキスト対動的コンテキスト比率を追跡する
• オフロード前後のツール出力サイズを監視する
• 動的に読み込まれたコンテキストが実際にどれくらい頻繁に使用されるかを測定する

例

例1：ツール出力オフロード

入力：ウェブ検索が8000トークンを返す
実行前：8000トークンがメッセージ履歴に追加される
実行後：
  - scratch/search_results_001.txtに書き込む
  - 返す：「[結果はscratch/search_results_001.txt内。主な発見：APIレート制限は毎分1000リクエスト]」
  - エージェントが詳細が必要な場合、ファイルをグリップ
結果：コンテキストに約100トークン、オンデマンドで8000トークン利用可能

例2：動的スキル読み込み

入力：ユーザーがデータベースインデックスについて質問
静的コンテキスト：「database-optimization: Query tuning and indexing」
エージェント操作：read_file("skills/database-optimization/SKILL.md")
結果：関連する場合にのみ完全なスキルが読み込まれる

例3：ファイル参照としてのチャット履歴

トリガー：コンテキストウィンドウ制限に達した、要約が必要
操作：
  1. 完全な履歴をhistory/session_001.txtに書き込む
  2. 新しいコンテキストウィンドウ用の概要を生成する
  3. 参照を含める：「完全な履歴はhistory/session_001.txt内」
結果：エージェントが履歴ファイルを検索して、要約で失われた詳細を復元できる

ガイドライン

1. 大きな出力をファイルに書き込む；要約と参照をコンテキストに返す
2. 計画と状態を構造化されたファイルに保存して再読み込みする
3. メッセージチェーンの代わりにサブエージェントファイルワークスペースを使用する
4. すべてをシステムプロンプトに詰め込む代わりに、スキルを動的に読み込む
5. ターミナルおよびログ出力を検索可能なファイルとして永続化する
6. 包括的な発見のためにgrep/globをセマンティック検索と組み合わせる
7. 明確な命名でエージェント発見用にファイルを組織化する
8. トークン節約を測定して、ファイルシステムパターンが効果的であることを検証する
9. スクラッチファイルのクリーンアップを実装して、無制限の増加を防ぐ
10. 自己変更パターンを検証で保護する

落とし穴

1. スクラッチディレクトリの無制限成長：エージェントがクリーンアップなしでテンポラリファイルを作成し、最終的にディスクを消費し、ディレクトリリストが騒々しくなる。セッション境界でリテンションポリシー（年齢ベースまたはカウントベース）を実装し、クリーンアップを実行してください。
2. マルチエージェントファイルアクセスでの競合状態：同じファイルへの同時書き込みが状態をサイレント破損させる。エージェントごとのディレクトリ分離を強制するか、エージェント接頭辞付きエントリを持つアペンドのみファイルを使用してください。
3. 移動/名前変更後の古いファイル参照：エージェントが以前のターンから保持しているパスが、リファクタリングまたはファイル再編成後に存在しなくなる。キャッシュされたパスを読み込む前に常にファイル存在を確認してください；チェックが失敗した場合はglobで再発見してください。
4. Globパターンの誤った一致：過度に広いパターン（例：**/*）は無関係なファイルをコンテキストに引き込み、トークンを無駄にしてモデルを混乱させる。globを特定のディレクトリと拡張子にスコープしてください。
5. ファイルサイズの仮定：サイズをチェックしないでファイルを読み込むと、単一のツール呼び出しで100K+トークンをコンテキストに投下する可能性がある。読み込む前にファイルサイズをチェックしてください；大きなファイルにはラインレンジ読み込みを使用してください。
6. ファイル存在チェックの欠落：エージェントは以前のターンからファイルが存在すると想定していますが、削除または移動されている可能性があります。常に存在チェックで読み込みを保護し、見つからないファイルエラーを適切に処理してください。
7. スクラッチパッド形式の漂流：構造化されていないスクラッチパッドは多くの書き込み後にパースできなくなります。連続した追加を通じて形式規約が劣化するためです。スキーマ（YAML、JSON、または構造化マークダウン）を最初の書き込みから定義して強制してください。
8. ハードコードされた絶対パス：リポジトリが異なる場所でチェックアウトされるか、コンテナ内で実行される場合に破損します。プロジェクトルートからの相対パスを使用するか、パスを動的に解決してください。

統合

このスキルは以下に接続されています：

• context-optimization - ファイルシステムオフロードは観察マスキングの一形式
• memory-systems - ファイルシステム-メモリは簡潔なメモリレイヤー
• multi-agent-patterns - サブエージェントファイルワークスペースは分離を有効にする
• context-compression - ファイル参照はロスレス「圧縮」を有効にする
• tool-design - ツールは大きな出力用にファイル参照を返すべき

参考資料

内部参考：

• 実装パターン - 読む場合：スクラッチパッド、計画永続化、またはツール出力オフロードを実装し、インライン例を超えた具体的なコードが必要な場合

このコレクション内の関連スキル：

• context-optimization - 読む場合：ファイルシステムオフロードと並行してトークン削減技法を適用する
• memory-systems - 読む場合：単一セッションを超えて永続化する永続ストレージを構築する
• multi-agent-patterns - 読む場合：共有ファイルワークスペースを持つエージェント調整を設計する

外部リソース：

• LangChain Deep Agents — 読む場合：LangChain/LangGraphパイプラインでファイルシステムベースのコンテキストパターンを実装する
• Cursor context discovery — 読む場合：本番環境IDEが動的コンテキスト読み込みを実装する方法を学習する
• Anthropic Agent Skills specification — 読む場合：ファイルシステムプログレッシブ開示を活用するスキルを構築する

---

Skill Metadata

Created: 2026-01-07 Last Updated: 2026-03-17 Author: Agent Skills for Context Engineering Contributors Version: 1.1.0