context-mode

大量の出力には常にコンテキストモードを使用

必須ルール

<context_mode_logic> <mandatory_rule> すべてのコマンドでコンテキストモードをデフォルトで使用してください。Bash は、出力が確実に少量である操作にのみ使用してください。 </mandatory_rule> </context_mode_logic>

Bash の許可リスト（直接実行しても安全です）：

• ファイルの変更：mkdir、mv、cp、rm、touch、chmod
• Git の書き込み操作：git add、git commit、git push、git checkout、git branch、git merge
• ナビゲーション：cd、pwd、which
• プロセス制御：kill、pkill
• パッケージ管理：npm install、npm publish、pip install
• 簡単な出力：echo、printf

それ以外はすべて → ctx_execute または ctx_execute_file。 読み取り、問い合わせ、取得、一覧表示、ログ出力、テスト、ビルド、差分確認、調査、外部サービスの呼び出しを行うコマンドが対象です。これには、すべての CLI（gh、aws、kubectl、docker、terraform、wrangler、fly、heroku、gcloud など）が含まれます。数え切れないほどあるため、すべてを列挙することはできません。

迷ったら、コンテキストモードを使用してください。 不要なコンテキストが 1 KB 増えるごとに、セッション全体の品質と速度が低下します。

判断フローチャート

About to run a command / read a file / call an API?
│
├── Command is on the Bash whitelist (file mutations, git writes, navigation, echo)?
│   └── Use Bash
│
├── Output MIGHT be large or you're UNSURE?
│   └── Use context-mode ctx_execute or ctx_execute_file
│
├── Fetching web documentation or HTML page?
│   └── Use ctx_fetch_and_index → ctx_search
│
├── Using Playwright (navigate, snapshot, console, network)?
│   └── ALWAYS use filename parameter to save to file, then:
│       browser_snapshot(filename) → ctx_index(path) or ctx_execute_file(path)
│       browser_console_messages(filename) → ctx_execute_file(path)
│       browser_network_requests(filename) → ctx_execute_file(path)
│       ⚠ browser_navigate returns a snapshot automatically — ignore it,
│         use browser_snapshot(filename) for any inspection.
│       ⚠ Playwright MCP uses a SINGLE browser instance — NOT parallel-safe.
│         For parallel browser ops, use agent-browser via execute instead.
│
├── Using agent-browser (parallel-safe browser automation)?
│   └── Run via execute (shell) — each call gets its own subprocess:
│       execute("agent-browser open example.com && agent-browser snapshot -i -c")
│       ✓ Supports sessions for isolated browser instances
│       ✓ Safe for parallel subagent execution
│       ✓ Lightweight accessibility tree with ref-based interaction
│
├── Processing output from another MCP tool (Context7, GitHub API, etc.)?
│   ├── Output already in context from a previous tool call?
│   │   └── Use it directly. Do NOT re-index with ctx_index(content: ...).
│   ├── Need to search the output multiple times?
│   │   └── Save to file via ctx_execute, then ctx_index(path) → ctx_search
│   └── One-shot extraction?
│       └── Save to file via ctx_execute, then ctx_execute_file(path)
│
└── Reading a file to analyze/summarize (not edit)?
    └── Use ctx_execute_file (file loads into FILE_CONTENT, not context)

各ツールを使用する状況

状況	ツール	例
API エンドポイントを呼び出す	ctx_execute	fetch('http://localhost:3000/api/orders')
データを返す CLI を実行する	ctx_execute	gh pr list、aws s3 ls、kubectl get pods
テストを実行する	ctx_execute	npm test、pytest、go test ./...
Git 操作	ctx_execute	git log --oneline -50、git diff HEAD~5
Docker/K8s の調査	ctx_execute	docker stats --no-stream、kubectl describe pod
ログファイルを読む	ctx_execute_file	access.log、error.log、ビルド出力を解析する
データファイルを読む	ctx_execute_file	CSV、JSON、YAML、XML を分析する
分析のためにソースコードを読む	ctx_execute_file	関数の数を数える、パターンを見つける、指標を抽出する
Web ドキュメントを取得する	ctx_fetch_and_index	React/Next.js/Zod のドキュメントをインデックス化してから検索する
Playwright のスナップショット	browser_snapshot(filename) → ctx_index(path) → ctx_search	ファイルに保存し、サーバー側でインデックス化してから検索する
Playwright のスナップショット（1 回限り）	browser_snapshot(filename) → ctx_execute_file(path)	ファイルに保存し、サンドボックス内で抽出する
Playwright のコンソール／ネットワーク	browser_*(filename) → ctx_execute_file(path)	ファイルに保存し、サンドボックス内で分析する
MCP の出力（すでにコンテキスト内にある）	そのまま使用する	再度インデックス化しないでください。すでに読み込まれています
MCP の出力（複数のクエリが必要）	ctx_execute で保存 → ctx_index(path) → ctx_search	まずファイルに保存し、サーバー側でインデックス化する
インデックス化された KB コンテンツを消去する	ctx_purge(confirm: true)	インデックス化されたコンテンツをすべて完全に削除する

自動トリガー

以下のいずれかに該当する場合、指示がなくてもコンテキストモードを使用してください。

• API のデバッグ：「このエンドポイントを呼び出して」「API を呼び出して」「レスポンスを確認して」「レスポンスのバグを見つけて」
• ログの分析：「ログを確認して」「エラーは何か」「access.log を読んで」「500 エラーをデバッグして」
• テストの実行：「テストを実行して」「テストが通るか確認して」「テストスイートの出力」
• Git 履歴：「最近のコミットを表示して」「git log」「何が変更されたか」「ブランチ間の差分」
• データの調査：「CSV を見て」「JSON を解析して」「設定を分析して」
• インフラストラクチャ：「コンテナを一覧表示して」「ポッドを確認して」「S3 バケット」「実行中のサービスを表示して」
• 依存関係の監査：「依存関係を確認して」「古いパッケージ」「セキュリティ監査」
• ビルド出力：「プロジェクトをビルドして」「警告がないか確認して」「コンパイルエラー」
• コードの指標：「行数を数えて」「TODO を見つけて」「関数の数」「コードベースを分析して」
• Web ドキュメントの検索：「ドキュメントを調べて」「API リファレンスを確認して」「例を見つけて」

言語の選択

状況	言語	理由
HTTP/API 呼び出し、JSON	javascript	ネイティブの fetch、JSON.parse、async/await
データ分析、CSV、統計	python	csv、statistics、collections、re
パイプを使うシェルコマンド	shell	grep、awk、jq、ネイティブツール
ファイルのパターンマッチング	shell	find、wc、sort、uniq

検索クエリの戦略

• BM25 は OR セマンティクス を使用します。一致する語句が多い結果ほど、自動的に上位にランクされます
• クエリごとに、具体的な技術用語を 2～4 個使用します
• 複数のドキュメントがインデックスされている場合は、ソース間の混同を避けるため、必ず source パラメーターを使用します
  • 部分一致が機能します。source: "Node" は "Node.js v22 CHANGELOG" に一致します
• 必ず queries 配列を使用します。すべての検索質問を 1 回の呼び出しにまとめます
  • ctx_search(queries: ["transform pipe", "refine superRefine", "coerce codec"], source: "Zod")
  • ctx_search() を複数回に分けて呼び出さないでください。すべてのクエリを 1 つの配列に入れます

外部ドキュメント

• 外部ドキュメントには 必ず ctx_fetch_and_index を使用してください。自分が所有していないパッケージに対して、ローカルパスを使った cat や ctx_execute は使用しないでください
• GitHub でホストされているプロジェクトでは、raw URL を使用します。https://raw.githubusercontent.com/org/repo/main/CHANGELOG.md
• インデックス作成後は、検索で source パラメーターを使用し、対象のドキュメントに結果を絞り込みます

重要なルール

1. 調査結果は必ず console.log/print で出力します。 コンテキストに入るのは stdout の内容だけです。出力がなければ、呼び出しは無駄になります。
2. データをそのまま出力するのではなく、分析コードを書きます。 console.log(JSON.stringify(data)) は使わず、先に分析してから調査結果を出力します。
3. 出力は具体的にします。 件数だけでなく、ID、行番号、正確な値を含むバグの詳細を出力します。
4. 編集が必要なファイルには、通常の Read ツールを使用します。 context-mode は分析用であり、編集用ではありません。
5. Bash では許可リストにあるコマンドのみを使用します。 ファイルの変更、git の書き込み、ナビゲーション、プロセス制御、パッケージのインストール、echo には Bash を使用します。それ以外はすべて context-mode を使用します。
6. ctx_index(content: large_data) は使用しないでください。 サーバー側でファイルを読み込むには ctx_index(path: ...) を使用します。content パラメーターはデータをツールパラメーターとしてコンテキスト経由で送信するため、小さなインラインテキストにのみ使用します。
7. Playwright ツール（browser_snapshot、browser_console_messages、browser_network_requests）では、必ず filename パラメーターを使用します。 使用しないと、出力全体がコンテキストに入ります。
8. すでにコンテキストにあるデータを再インデックスしないでください。 MCP ツールが以前の応答でデータを返している場合、そのデータはすでに読み込まれています。そのまま使用するか、先にファイルに保存します。

サンドボックス化されたデータのワークフロー

<sandboxed_data_workflow> <critical_rule> ファイルへの保存に対応したツールを使用する場合は、必ず 'filename' パラメーターを使用します。 大きな生データセットをコンテキストに直接返してはいけません。 </critical_rule> LargeDataTool(filename: "path") → mcp__context-mode__ctx_index(path: "path") → ctx_search() </sandboxed_data_workflow>

これは、データの取得元ツール（Playwright、GitHub API、AWS CLI など）に関係なく、コンテキストを保持するための汎用パターンです。

例

API エンドポイントをデバッグする

const resp = await fetch('http://localhost:3000/api/orders');
const { orders } = await resp.json();

const bugs = [];
const negQty = orders.filter(o => o.quantity < 0);
if (negQty.length) bugs.push(`Negative qty: ${negQty.map(o => o.id).join(', ')}`);

const nullFields = orders.filter(o => !o.product || !o.customer);
if (nullFields.length) bugs.push(`Null fields: ${nullFields.map(o => o.id).join(', ')}`);

console.log(`${orders.length} orders, ${bugs.length} bugs found:`);
bugs.forEach(b => console.log(`- ${b}`));

テスト出力を分析する

npm test 2>&1
echo "EXIT=$?"

GitHub の PR を確認する

gh pr list --json number,title,state,reviewDecision --jq '.[] | "\(.number) [\(.state)] \(.title) — \(.reviewDecision // "no review")"'

大きなファイルを読み込んで分析する

# FILE_CONTENT is pre-loaded by ctx_execute_file
import json
data = json.loads(FILE_CONTENT)
print(f"Records: {len(data)}")
# ... analyze and print findings

ブラウザーと Playwright の統合

Playwright のスナップショット、スクリーンショット、ページの調査を伴うタスクでは、必ず file → sandbox 経由で処理します。

Playwright の browser_snapshot は、アクセシビリティツリーのデータを 10K～135K トークン返します。filename を指定せずに呼び出すと、そのすべてがコンテキストに出力されます。出力を ctx_index(content: ...) に渡すと、パラメーターとしてもう一度コンテキストに送信されます。どちらも誤った方法です。

重要なポイント：browser_snapshot には、コンテキストに返す代わりにファイルへ保存する filename パラメーターがあります。ctx_index には、ファイルをサーバー側で読み込む path パラメーターがあります。ctx_execute_file はサンドボックス内でファイルを処理します。いずれもコンテキストには触れません。

ワークフロー A：スナップショット → ファイル → インデックス作成 → 検索（複数のクエリ）

Step 1: browser_snapshot(filename: "/tmp/playwright-snapshot.md")
        → saves to file, returns ~50B confirmation (NOT 135K tokens)

Step 2: ctx_index(path: "/tmp/playwright-snapshot.md", source: "Playwright snapshot")
        → reads file SERVER-SIDE, indexes into FTS5, returns ~80B confirmation

Step 3: ctx_search(queries: ["login form email password"], source: "Playwright")
        → returns only matching chunks (~300B)

合計コンテキスト：約430B。270Kトークンと比べて、実に99％削減できます。

ワークフロー B：スナップショット → ファイル → ファイルを実行（1回限りの抽出）

Step 1: browser_snapshot(filename: "/tmp/playwright-snapshot.md")
        → saves to file, returns ~50B confirmation

Step 2: ctx_execute_file(path: "/tmp/playwright-snapshot.md", language: "javascript", code: "
          const links = [...FILE_CONTENT.matchAll(/- link \"([^\"]+)\"/g)].map(m => m[1]);
          const buttons = [...FILE_CONTENT.matchAll(/- button \"([^\"]+)\"/g)].map(m => m[1]);
          const inputs = [...FILE_CONTENT.matchAll(/- textbox|- checkbox|- radio/g)];
          console.log('Links:', links.length, '| Buttons:', buttons.length, '| Inputs:', inputs.length);
          console.log('Navigation:', links.slice(0, 10).join(', '));
        ")
        → processes in sandbox, returns ~200B summary

合計コンテキスト：約250B。135Kトークンと比べて削減できます。

ワークフロー C：コンソールとネットワーク（大きい場合はファイルに保存）

browser_console_messages(level: "error", filename: "/tmp/console.md")
→ ctx_execute_file(path: "/tmp/console.md", ...) or ctx_index(path: "/tmp/console.md", ...)

browser_network_requests(includeStatic: false, filename: "/tmp/network.md")
→ ctx_execute_file(path: "/tmp/network.md", ...) or ctx_index(path: "/tmp/network.md", ...)

重要：filename と path が必須である理由

アプローチ	コンテキストのコスト	正しい？
browser_snapshot() → 生データをコンテキストに取り込む	135Kトークン	いいえ
browser_snapshot() → ctx_index(content: raw)	270Kトークン（2倍！）	いいえ
browser_snapshot(filename) → ctx_index(path) → ctx_search	約430B	はい
browser_snapshot(filename) → ctx_execute_file(path)	約250B	はい

重要なルール

browser_snapshot、browser_console_messages、または browser_network_requests を呼び出すときは、必ず filename パラメーターを使用してください。 その後、ctx_index(path: ...) または ctx_execute_file(path: ...) で処理してください。ctx_index(content: ...) は使用しないでください。

データフロー：Playwright → ファイル → サーバー側で読み取り → コンテキスト。次の流れは避けてください：Playwright → コンテキスト → ctx_index(content) → 再びコンテキスト。

サブエージェントの使用

サブエージェントには、PreToolUse フックを介してコンテキストモードのツールルーティングが自動的に適用されます。サブエージェントのプロンプトにツール名を手動で追加する必要はありません。フックが自動で挿入します。自然なタスクの説明を書くだけでかまいません。

アンチパターン

• Bash 経由で curl http://api/endpoint を使用する → 50KB のデータがコンテキストを圧迫します。代わりに ctx_execute と fetch を使用してください。
• Bash 経由で cat large-file.json を使用する → ファイル全体がコンテキストに入ります。代わりに ctx_execute_file を使用してください。
• Bash 経由で gh pr list を使用する → 生の JSON がコンテキストに入ります。代わりに ctx_execute と --jq フィルターを使用してください。
• Bash の出力を | head -20 に渡す → 残りのデータが失われます。ctx_execute を使ってすべてのデータを分析し、要約を出力してください。
• キャプチャー前に ctx_execute の出力を上流で絞り込む → ctx_execute がキャプチャーし、ctx_search がフィルターします。この2つの層をまとめると、インデックスに取り込まれないデータが失われます。references/anti-patterns.md §8 を参照してください。
• Bash 経由で npm test を実行する → テスト出力全体がコンテキストに入ります。代わりに ctx_execute でキャプチャーして要約してください。
• filename パラメーターなしで browser_snapshot() を呼び出す → 135Kトークンがコンテキストを圧迫します。必ず browser_snapshot(filename: "/tmp/snap.md") を使用してください。
• filename なしで browser_console_messages() または browser_network_requests() を呼び出す → 出力全体がコンテキストを圧迫します。必ず filename パラメーターを使用してください。
• 大きなデータを ctx_index(content: ...) に渡す → データがパラメーターとしてコンテキストに入ります。必ず ctx_index(path: ...) を使用してサーバー側で読み取ってください。content パラメーターは、自分で作成した小さなインラインテキストにのみ使用してください。
• MCP ツール（Context7 の query-docs、GitHub API など）を呼び出してから、レスポンスを ctx_index(content: response) に渡す → コンテキストの使用量が2倍になります。レスポンスはすでにコンテキストにあるため、そのまま使用するか、先にファイルに保存してください。
• browser_navigate による自動スナップショットを無視する → ナビゲーションのレスポンスにはページ全体のスナップショットが含まれます。これを検査に頼らず、別途 browser_snapshot(filename) を呼び出してください。
• ctx_stats がリセットや消去を行うと思い込む → ctx_stats は読み取り専用で、統計情報を表示するだけです。インデックス化されたコンテンツをすべて完全に削除するには、ctx_purge(confirm: true) を使用してください。

参照ファイル

• JavaScript／TypeScript のパターン
• Python のパターン
• シェルのパターン
• アンチパターンとよくある間違い