excalidraw

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 ファイルに対して Read ツールを使用する
• ❌ メインコンテキストで 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% が使われた	常に委任する
「一度きりの分析なので最適」	「一度きり」でもメインコンテキストは汚染される	サブエージェントで分離する
「JSON は単純だ」	単純さ ≠ トークン効率	それでも委任する
「フォーマットを理解する必要がある」	メインエージェントにフォーマットの理解は不要	サブエージェントがフォーマットを処理する
「妥当な範囲内」（18k トークン）	「妥当」は主観的な言い訳	厳格なルール: 委任する
「コンポーネントを軽く確認するだけ」	「軽い確認」でも JSON 全体を読み込んでしまう	サブエージェントでテキストを抽出する
「ファイルは小さい（16K）」	4k トークンは小さくない	サイズのしきい値は関係ない

レッドフラッグ - 立ち止まって委任する

次のような行動をしそうになったら気づいてください:

• .excalidraw ファイルに対して Read ツールを使おうとする
• どのコンポーネントがあるかを「さっと確認」しようとする
• 変更前に「構造を理解」しようとする
• 「中身を見る」ためにファイルを読み込もうとする
• 複数の図を並べて比較しようとする
• 「テキストだけ取り出す」ために 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 ファイルを決して読み込まない。例外はない。

次の理由であっても例外は認められません：

• 「ちょっとした確認」
• 「小さなファイル」
• 「形式の理解」
• 「一度きりの分析」
• 「最適な効率」

常に委譲すること。サブエージェントを使えば隔離は無償で行えます。