media-transformation

TOON v2.0 フォーマッタースキル（アグレッシブモード）

目的

構造化データのトークンを30～60％削減できるよう、TOON v2.0 形式を積極的に適用します。大きめで規則性のあるデータには、デフォルトで TOON を使用します。パフォーマンスを20倍にするには、ネイティブの Zig エンコーダーを使用します。

使用する場面（アグレッシブ）

いつでも TOON を使用 — 以下の場合は自動的に使用します：

• ✅ 類似した項目が5個以上ある配列
• ✅ テーブル、ログ、イベント、トランザクション、分析データ
• ✅ 構造が均一な API レスポンス（フィールドの重複率が60％以上）
• ✅ データベースのクエリ結果
• ✅ プロンプト内で繰り返し使用する構造化データ
• ✅ RAG パイプライン、ツール呼び出し、エージェント間で受け渡すデータ
• ✅ プロンプトサイズがコストに直結するベンチマーク／評価
• ✅ ラベルより形状が重要な場合
• ✅ 各列の意味がわかっている場合
• ✅ ヘッダーを一度定義して、行ごとに処理できる場合

必要に応じて使用 — 次の場合は慎重に判断します：

• ⚠️ 人間の共同作業者がデータを頻繁に読み書きする
• ⚠️ API／ツールが JSON を想定している（通信には JSON、プロンプトには TOON を使用）
• ⚠️ 構造が不均一（省略可能なキーが多い、ネストが複雑など）

使用しない — 次の場合は JSON／テキストを使用します：

• ❌ 短い配列（項目が5個未満）
• ❌ ドキュメント内の単発の例
• ❌ 叙述文、指示、エッセイ
• ❌ 階層が重要な、深く不規則なツリー

TOON v2.0 とは？

TOON（Token-Oriented Object Notation）v2.0 は、構造化データのトークン消費量を30～60％削減します：

3種類の配列

1. 表形式（均一なオブジェクトが5個以上）：

[2]{id,name,balance}:
  1,Alice,5420.50
  2,Bob,3210.75

2. インライン形式（プリミティブが10個以下）：

tags[5]: javascript,react,node,express,api

3. 展開形式（不均一）：

- name: Alice
  role: admin
- name: Bob
  level: 5

3種類の区切り文字

カンマ（デフォルト、最もコンパクト）：

[2]{name,city}: Alice,NYC Bob,LA

タブ（データにカンマが含まれる場合）：

[2\t]{name,address}: Alice	123 Main St, NYC

パイプ（Markdown 風）：

[2|]{method,path}: GET|/api/users

キーの折りたたみ

ネストしたオブジェクトをフラット化（さらに25～35％削減）：

server.host: localhost
server.port: 8080
database.host: db.example.com

手順

1. 適したデータを検出する

配列データを見つけたら、TOON の条件を満たしているか確認します：

• ✅ 項目が5個以上ある配列
• ✅ フィールドの均一性が60％以上のオブジェクト（ほとんどのオブジェクトが同じフィールドを持つ）
• ✅ フラット、または適度にネストした構造

均一性の確認方法：

1. すべてのオブジェクトからフィールド名を抽出する
2. 最も一般的なフィールドの組み合わせを持つオブジェクトの数を数える
3. 次の式で計算する：(共通フィールドを持つオブジェクト数 / オブジェクト総数) × 100
4. 60％以上なら、TOON に適した均一性です

2. トークン削減量を見積もる

簡易見積もり方法：

• JSON のトークン数 ≈ (項目数 × フィールド数 × 4) + オーバーヘッド
  • 例：10項目 × 5フィールド × 4 = 約200トークン
• TOON のトークン数 ≈ 20 (ヘッダー) + (項目数 × フィールド数 × 2)
  • 例：20 + (10 × 5 × 2) = 約120トークン
• 削減率 ≈ (JSON - TOON) / JSON × 100%
  • 例：(200 - 120) / 200 = 40％削減

3. TOON v2.0 を積極的に適用する

アグレッシブモード：最適な結果を得るには Zig エンコーダーを使用します

データが条件を満たす場合：

方法1：Zig エンコーダーを使用（推奨 — 20倍高速）：

.claude/utils/toon/zig-out/bin/toon encode data.json \
  --delimiter tab \
  --key-folding \
  > data.toon

方法2：手動で TOON を作成（インライン生成の場合）：

1. 配列の種類を判定する（インライン／表形式／展開形式）
2. 区切り文字を選択する（カンマ／タブ／パイプ）
3. ネストしたオブジェクトがある場合はキーを折りたたむ
4. TOON ヘッダーを作成する：[N]{fields}: または key[N]: values
5. TOON 形式で出力する

簡単な概要を表示します：

📊 Using TOON v2.0 (estimated 42% savings, 10 items)
Format: Tabular with tab delimiter
Key folding: enabled

[10\t]{id,name,address,status}:
  1	Alice	123 Main St, NYC	active
  2	Bob	456 Oak Ave, LA	inactive
  ...

それ以外の場合は、JSON を使用して理由を説明します：

Using JSON because:
- Only 3 items (too small)
- Or: Low uniformity (only 45% have same fields)
- Or: Deeply nested structure

4. 変換後の出力を表示する

簡単な説明を添えて、すぐに TOON 形式で表示します：

📊 API Endpoints (15 items, TOON format - saved 40.1% tokens):

[15]{method,path,description,auth,rateLimit}:
  GET,/api/users,List all users,required,100/min
  POST,/api/users,Create new user,required,50/min
  ...

長い説明は不要です。使うだけです！

ベストプラクティス

形式の選択を必ず示す

データを扱うときは、使用する形式とその理由を必ず示します：

📊 Using TOON (estimated 42% token savings)
[count]{fields}:...

または

ℹ️ Using JSON (deeply nested structure, TOON not suitable)
{...}

TOON を使用しない場面

JSON のほうが適している場合は、理由を説明します：

• 深くネストしたデータ：TOON はフラットな構造や表形式の構造に適しています
• 均一性が低い（70％未満）：オブジェクトごとにフィールドが異なると、TOON の効果が低下します
• 小さな配列（項目が10個未満）：オーバーヘッドに見合う効果がありません
• 単一レコード：明確さを優先して JSON を使用します

パフォーマンスのヒント

1. バッチ処理：大規模なデータセットを一度変換し、TOON 形式を再利用する
2. 均一性が重要：フィールドの重複率が高いほど、削減効果が高まる
3. ネストした配列：TOON はネストした構造に対応しますが、削減効果は小さくなります
4. 型の強制変換：TOON は型（数値、ブール値、日付）を保持します

例

例 1：API レスポンス

入力：

const apiResponse = await fetch('/api/users').then(r => r.json());
// 150 users returned

出力：

API Response (150 users):
Format: TOON (saves 41.2%, 1,847 tokens saved)

[150]{id,name,email,role,lastLogin}:
  1,Alice Smith,[email protected],admin,2024-01-15T10:30:00Z
  2,Bob Jones,[email protected],user,2024-01-15T09:15:00Z
  ...

例 2：データベースクエリ

入力：

SELECT * FROM transactions WHERE date > '2024-01-01' LIMIT 500;

出力：

Query Results (500 transactions):
Format: TOON (saves 38.9%, 3,421 tokens saved)

[500]{id,date,amount,merchant,category,status}:
  1,2024-01-15,42.50,Starbucks,Food & Drink,completed
  2,2024-01-15,125.00,Shell Gas,Transportation,completed
  ...

例 3：メトリクスダッシュボード

入力：

const metrics = analyzePerformance();
// Returns array of route performance metrics

出力：

Performance Metrics (45 routes):
Format: TOON (saves 44.1%, 892 tokens saved)

[45]{route,avgTime,p95,requests,errors}:
  /api/users,125,340,15420,3
  /api/products,89,210,8932,0
  /api/orders,450,1250,3421,12
  ...

例 4：混合データ（JSON が適しています）

入力：

const complexData = {
  metadata: { version: '1.0', timestamp: '...' },
  results: [
    { id: 1, data: { nested: { deep: 'value' } } },
    // Highly nested, non-uniform
  ]
};

出力：

ℹ️ Using JSON format (TOON not recommended):
- Deeply nested structure
- Low uniformity (45%)
- Small array (only 5 items)

{
  "metadata": { "version": "1.0", ... },
  "results": [ ... ]
}

他のスキルとの連携

財務分析

取引や財務データを分析する際は、大きな結果セットに TOON を使用します：

• 取引履歴（100 件以上）
• 複数口座の残高
• 支払いログと監査証跡

データのエクスポート

データをエクスポートする際は、TOON が適しているか確認します：

• 5 件以上かつ均一性が 60％以上 → TOON を使用
• それ以外 → JSON を使用

API ドキュメント

API エンドポイントを TOON 形式で記述すると、簡潔なリファレンスになります：

# API Endpoints

[15]{method,path,auth,rateLimit,description}:
  GET,/api/users,required,100/min,List all users
  POST,/api/users,required,50/min,Create new user
  ...

コマンド

次の TOON v2.0 コマンドを使用します：

• /toon-encode <file> [--delimiter tab] [--key-folding] - JSON → TOON v2.0
• /toon-validate <file> [--strict] - TOON ファイルを検証
• /analyze-tokens <file> - JSON と TOON のトークン削減量を比較
• /convert-to-toon <file> - レガシーコマンド（toon-encode を使用）

リソース

• Zig エンコーダー：.claude/utils/toon/toon.zig（601 行、20 倍高速）
• ユーザーガイド：.claude/docs/toon-guide.md
• 例：.claude/utils/toon/examples/（9 ファイル）
• ガイド：.claude/utils/toon/guides/（4 ファイル）
• FAQ：.claude/docs/FAQ.md
• TOON 仕様：https://github.com/toon-format/spec
• 公式サイト：https://toonformat.dev

成功指標

TOON の使用効果を追跡します：

• 平均トークン削減率：30～60％
• 精度の向上：+3～5％（公式ベンチマークによる）
• 解放されたコンテキストウィンドウ：大規模なデータセットで 15K 以上のトークン
• ユーザー満足度：応答の高速化、利用可能なコンテキストの増加