filesystem-context

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

コンテキストウィンドウには限りがある一方で、タスクでは単一のウィンドウに収まりきらない情報が必要になることが多いため、エージェントのコンテキストをあふれさせる際の主要な保存先としてファイルシステムを使用します。ファイルを使えば、単一のインターフェースを通じて、実質的に無制限の量のコンテキストをエージェントが保存、取得、更新できます。

静的にコンテキストを含める方法は、関連性にかかわらずトークンを消費し、タスク固有の情報を入れる余地を狭めるため、動的なコンテキスト探索、つまり必要に応じて関連するコンテキストを取得する方法を優先します。

使用するタイミング

次の場合にこのスキルを使用します：

• ツールの出力によってコンテキストウィンドウが肥大化している
• エージェントが長い実行経路をまたいで状態を保持する必要がある
• サブエージェントが、直接メッセージをやり取りせずに情報を共有する必要がある
• タスクにウィンドウへ収まりきらないコンテキストが必要である
• 自身の指示を学習して更新するエージェントを構築している
• 中間結果用のスクラッチパッドを実装している
• ターミナルの出力やログをエージェントが参照できるようにする必要がある

隣接領域の作業を担う他のスキルがある場合は、このスキルを使用しないでください：

• セッションをまたぐ意味的なメモリー、エンティティ追跡、時間的なナレッジグラフ：memory-systems。
• 会話の要約、圧縮、永続的な引き継ぎ文の作成：context-compression。
• ファイルベースの保存を必要としない、トークン効率化の手法：context-optimization。
• マルチエージェントの構成や引き継ぎプロトコルの設計：multi-agent-patterns。
• ライブウィンドウ自体からコンテンツを退避させるモデルの編集：self-managed-context。

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 トークンを超える
• タスクが複数の会話ターンにまたがる
• 複数のエージェントが共有状態を必要とする
• スキルや指示がシステムプロンプトに収まるサイズを超える
• ログやターミナル出力を選択的に検索する必要がある

使用を避ける場合：

• タスクが 1 ターンで完了する（オーバーヘッドに見合わない）
• コンテキストがウィンドウに無理なく収まる（解決すべき問題がない）
• レイテンシが重要（ファイル 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 を含めてください。

自律的な調査ループでは、取得した未加工のエビデンスを、それを使用した実行の下に保存してください。たとえば、researcher/runs/<run-id>/sources/evidence/raw/ のようにします。未加工の調査データをリポジトリのルートに残さないでください。ルートレベルの成果物は監査が困難になり、出典を示さずに引用されやすくなります。

トークンの計測

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

• 静的コンテキストと動的コンテキストの比率を追跡する
• オフロードの前後でツール出力のサイズを監視する
• 動的に読み込まれたコンテキストが実際にどの程度使われているかを測定する

例

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

Input: Web search returns 8000 tokens
Before: 8000 tokens added to message history
After:
  - Write to scratch/search_results_001.txt
  - Return: "[Results in scratch/search_results_001.txt. Key finding: API rate limit is 1000 req/min]"
  - Agent greps file when needing specific details
Result: ~100 tokens in context, 8000 tokens accessible on demand

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

Input: User asks about database indexing
Static context: "database-optimization: Query tuning and indexing"
Agent action: read_file("skills/database-optimization/SKILL.md")
Result: Full skill loaded only when relevant

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

Trigger: Context window limit reached, summarization required
Action:
  1. Write full history to history/session_001.txt
  2. Generate summary for new context window
  3. Include reference: "Full history in history/session_001.txt"
Result: Agent can search history file to recover details lost in summarization

ガイドライン

1. 大きな出力はファイルに書き込み、要約とコンテキストへの参照を返す
2. 計画と状態は、読み返せるよう構造化ファイルに保存する
3. メッセージのやり取りではなく、サブエージェント用のファイルワークスペースを使用する
4. すべてをシステムプロンプトに詰め込むのではなく、スキルを動的に読み込む
5. ターミナルとログの出力を、検索可能なファイルとして永続化する
6. 包括的に見つけられるよう、grep/glob とセマンティック検索を組み合わせる
7. わかりやすい命名で、エージェントがファイルを見つけやすいように整理する
8. トークンの節約量を測定し、ファイルシステムのパターンが効果的であることを検証する
9. スクラッチファイルの増加を防ぐため、クリーンアップを実装する
10. 自己変更パターンには検証を設ける
11. 未加工のエビデンスは、それを使用した実行、評価、提案の近くに保管する

注意点

1. スクラッチディレクトリが無制限に増大する：エージェントが一時ファイルを作成しても削除せず、最終的にディスクを使い切り、ディレクトリ一覧が煩雑になります。保持ポリシー（経過時間またはファイル数に基づく）を実装し、セッションの区切りでクリーンアップを実行してください。
2. 複数エージェントによるファイルアクセスの競合状態：同じファイルへの同時書き込みによって、状態が気付かれないまま破損します。エージェントごとにディレクトリを分離するか、エージェント名を接頭辞とするエントリーを追記専用ファイルに記録してください。
3. 移動や名前変更後の古いファイル参照：リファクタリングやファイルの再編成後も、エージェントが以前のターンのパスを保持していると、そのファイルが存在しなくなっている場合があります。キャッシュされたパスから読み取る前に、必ずファイルの存在を確認してください。確認に失敗した場合は、globで再検索してください。
4. globパターンによる誤った一致：広すぎるパターン（例：**/*）は無関係なファイルまでコンテキストに取り込み、トークンを浪費してモデルを混乱させます。globの範囲は特定のディレクトリと拡張子に限定してください。
5. ファイルサイズの想定：サイズを確認せずにファイルを読み込むと、1回のツール呼び出しで10万トークン以上がコンテキストに流れ込む可能性があります。読み込む前にファイルサイズを確認し、大きなファイルには行範囲を指定した読み込みを使用してください。
6. ファイルの存在確認漏れ：以前のターンで存在していたファイルが削除または移動されている可能性があるにもかかわらず、エージェントが存在すると想定することがあります。読み込み前には必ず存在確認を行い、ファイルが見つからない場合のエラーを適切に処理してください。
7. スクラッチパッドの形式が徐々に変化する：構造化されていないスクラッチパッドは、追記を重ねるうちに形式の規則が崩れ、多数の書き込み後には解析できなくなります。最初の書き込みからスキーマ（YAML、JSON、または構造化されたMarkdown）を定義し、遵守してください。
8. 絶対パスのハードコード：リポジトリのチェックアウト先が異なる場合やコンテナ内で実行する場合に動作しなくなります。プロジェクトルートからの相対パスを使用するか、パスを動的に解決してください。

統合

このスキルは、ファイルベースのコンテキストの保存と取得を担います。隣接するスキルは、意味記憶、要約、トポロジーを担います。

• context-optimization：完全な出力を引き続き取得できる状態で保持する場合、ファイルシステムへのオフロードは観察マスキングの実装方法の1つです。
• memory-systems：ファイルベースのメモだけでは不十分になり、意味、エンティティ、または時間に基づく検索が必要な場合に使用します。
• multi-agent-patterns：サブエージェントのファイルワークスペースによって、コンテキストの分離と直接的な引き継ぎが可能になります。
• context-compression：ファイル参照は要約の基点となり、圧縮されたコンテキストから省かれた詳細を保持できます。
• tool-design：大きな出力にはファイル参照を返し、安全な読み込み・検索操作を提供するようにツールを設計してください。
• self-managed-context：オフロードしても元の内容はライブウィンドウに残ります。それを取り除くには、モデル自身がコンテキストを編集する必要があります。

参考資料

内部資料：

• 実装パターン - 参照するタイミング：スクラッチパッド、計画の永続化、またはツール出力のオフロードを実装する際に、インラインの例より具体的なコードが必要な場合

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

• context-optimization - 参照するタイミング：ファイルシステムへのオフロードと併せてトークン削減手法を適用する場合
• memory-systems - 参照するタイミング：単一セッションを超えて存続する永続ストレージを構築する場合
• multi-agent-patterns - 参照するタイミング：共有ファイルワークスペースを用いたエージェントの連携を設計する場合

外部リソース：

• LangChain Deep Agents — 参照するタイミング：LangChain／LangGraphのパイプラインでファイルシステムベースのコンテキストパターンを実装する場合
• Cursor context discovery — 参照するタイミング：本番環境のIDEが動的なコンテキスト読み込みをどのように実装しているか調べる場合
• Anthropic Agent Skills specification — 参照するタイミング：ファイルシステムを活用した段階的開示を利用するスキルを構築する場合

---

スキルのメタデータ

作成日：2026-01-07 最終更新日：2026-05-15 作成者：Agent Skills for Context Engineering Contributors バージョン：1.2.0