Excalidraw サブエージェント委譲

概要

コア原則： メインエージェントは Excalidraw ファイルを直接読み込まない。常にサブエージェントに委譲してコンテキスト消費を分離する。

Excalidraw ファイルはトークンコストが高いが情報密度が低い JSON です。単一ファイルは 4k～22k トークンの範囲です（最大ファイルは読み取り制限を超える場合がある）。複数の図を読み込むと、コンテキスト予算がすぐに消費されます（7 ファイル = 67k トークン = 予算の 33%）。

問題点

Excalidraw JSON の構造：

• 各要素は 20 以上のプロパティを持つ（x、y、width、height、strokeColor、seed、version など）
• ほとんどのプロパティは視覚的メタデータ（配置、スタイル、粗さ）
• 実際のコンテンツ：テキストラベルと要素の関係性（ファイルの 10% 未満）
• 信号対雑音比が非常に低い

例：14 要素の図 = 596 行、16K、約 4k トークン。79 要素の図 = 2,916 行、88K、約 22k トークン（読み取り制限を超える）。

使用するタイミング

以下のいずれかで委譲を選択：

• ファイルパスに .excalidraw または .excalidraw.json が含まれている
• ユーザーが以下を要求：「図を説明/更新/作成する」、「アーキテクチャを表示する」、「フローを可視化する」
• ユーザーが以下に言及：「フローチャート」、「アーキテクチャ図」、「Excalidraw ファイル」
• 視覚的なアーティファクトを含むアーキテクチャ/設計ドキュメントタスク

以下の場合でも委譲を使用：

• 「小さい」ファイル（最小でも 4k トークン - 依然として重要）
• 「クイックチェック」（コンポーネント名をチェックするだけでも完全な JSON をロード）
• 単一ファイル操作（分離はコンテキスト汚染を防止）
• 変更（メインコンテキストで完全なフォーマット理解は不要）

委譲パターン

メインエージェントの責務

してはいけないこと：

• ❌ *.excalidraw ファイルに読み取りツールを使用
• ❌ メインコンテキストで Excalidraw JSON を解析
• ❌ 複数の図をロードして比較
• ❌ ファイルを検査して「形式を理解する」

常にすること：

• ✅ すべての Excalidraw 操作をサブエージェントに委譲
• ✅ サブエージェントに明確なタスク説明を提供
• ✅ テキストのみのサマリーをリクエスト（生の JSON ではなく）
• ✅ 図の分析をメイン作業から分離

サブエージェントタスクテンプレート

読み込み/理解操作

Task: Extract and explain the components in [file.excalidraw.json]

Approach:
1. Read the Excalidraw JSON
2. Extract only text elements (ignore positioning/styling)
3. Identify relationships between components
4. Summarize architecture/flow

Return:
- List of components/services with descriptions
- Connection/dependency relationships
- Key insights about the architecture
- DO NOT return raw JSON or verbose element details

変更操作

Task: Add [component] to [file.excalidraw.json], connected to [existing-component]

Approach:
1. Read file to identify existing elements
2. Find [existing-component] and its position
3. Create new element JSON for [component]
4. Add arrow elements for connections
5. Write updated file

Return:
- Confirmation of changes made
- Position of new element
- IDs of created elements

作成操作

Task: Create new Excalidraw diagram showing [description]

Approach:
1. Design layout for [number] components
2. Create rectangle elements with text labels
3. Add arrows showing relationships
4. Use consistent styling (colors, fonts)
5. Write to [file.excalidraw.json]

Return:
- Confirmation of file created
- Summary of components included
- File location

比較操作

Task: Compare architecture approaches in [file1] vs [file2]

Approach:
1. Read both files
2. Extract text labels from each
3. Identify structural differences
4. Compare component relationships

Return:
- Key differences in architecture
- Components unique to each approach
- Relationship/flow differences
- DO NOT return full element details from both files

よくある言い訳（停止して委譲してください）

言い訳	実際	対処法
「直接読み込みが最も効率的」	不要に 4k～22k トークンを消費	サブエージェントに委譲
「トークン効率的に直接読み込める」	ベーステストで 9～45% の予算を使用	常に委譲
「これは 1 回限りの分析に最適」	「1 回限り」でもメインコンテキストを汚染	サブエージェント分離
「JSON はシンプル」	シンプル ≠ トークン効率	とにかく委譲
「形式を理解する必要がある」	形式の理解はメインエージェントで不要	サブエージェントが処理
「合理的な範囲内」（18k トークン）	「合理的」は主観的な正当化	ハード ルール：委譲
「コンポーネントのクイックチェック」	「クイックチェック」でも完全な JSON をロード	サブエージェント経由でテキスト抽出
「ファイルは小さい（16K）」	4k トークンは小さくない	ファイルサイズの閾値は無関係

危険信号 - 停止して委譲してください

以下を実行しようとしていることに気づいたら：

• .excalidraw ファイルに読み取りツールを使用
• コンポーネントが何か「クイックチェック」する
• 変更前に「構造を理解する」
• ファイルをロードして「何があるかを見る」
• 複数の図を並べて比較
• JSON を解析して「テキストだけを抽出する」

これらはすべて以下を意味します：代わりに Task ツールをサブエージェントで使用してください。

クイックリファレンス

操作	メインエージェントのアクション	サブエージェントが返すもの
図を理解する	「抽出して説明」テンプレートで委譲	コンポーネントリスト + 関係性
図を変更する	「[X] を [Y] に接続して追加」テンプレートで委譲	確認 + 加えた変更
図を作成する	「[説明]を表示する」テンプレートで委譲	ファイルの場所 + サマリー
図を比較する	「[A] を [B] と比較」テンプレートで委譲	主な違い（生の JSON ではなく）

トークン分析（重要な理由）

ベーステストの実際のデータ：

シナリオ	委譲なし	委譲あり	節約
単一の大規模ファイル	22k トークン（予算の 45%）	約 500 トークン（サブエージェントサマリー）	98%
2 ファイル比較	18k トークン（予算の 9%）	約 800 トークン（差分サマリー）	96%
変更タスク	14k トークン（予算の 7%）	約 300 トークン（確認）	98%

コンテキスト汚染の影響：

• すべての 7 つのプロジェクト図を読み込む：67k トークン（200k 予算の 33%）
• 委譲で：約 2k トークン（サブエージェント内で分離）
• 節約：コンテキスト予算の 97% を保持

実装例

❌ 悪い例（直接読み込み）：

User: "What architecture is shown in detailed-architecture.excalidraw.json?"
Agent: Let me read that file... [reads 22k tokens into main context]

✅ 良い例（サブエージェント委譲）：

User: "What architecture is shown in detailed-architecture.excalidraw.json?"
Agent: I'll use a subagent to extract the architecture details.

[Dispatches Task tool with general-purpose subagent]
Task: Extract and explain components in .ryanquinn3/ticketing/detailed-architecture.excalidraw.json

[Receives ~500 token summary with component list and relationships]
[Responds to user with architecture explanation, main context preserved]

なぜ「シンプルな JSON」は重要でないか

エージェントはしばしば正当化します：「フォーマットがシンプルだから、読むだけで済む」。

問題は複雑さではなく冗長性：

• シンプルな構造だが、要素ごとに 20 以上のプロパティ
• 繰り返されるメタデータ（seed、version、nonce、roughness）
• 配置データ（x、y、width、height）は意味的に有用でない
• ビジュアルスタイル（strokeColor、opacity、fillStyle）はコンテンツとは無関係

トークンコストは複雑さからではなく、ボリュームから来ます。

「シンプルな」JSON でも 4k～22k トークンを消費するのは：

• 79 要素 × 要素ごと約 280 トークン = 22k トークン
• ほとんどのトークンはメタデータノイズ
• テキストラベルと関係性だけが重要（コンテンツの約 10%）

鉄則

メインエージェントは Excalidraw ファイルを読み込まない。例外なし。

以下の場合ではない：

• 「クイックチェック」
• 「小さいファイル」
• 「形式の理解」
• 「1 回限りの分析」
• 「最適な効率」

常に委譲してください。分離はサブエージェント経由で無料です。