📚

Claude Codeのトークン使用量を削減するDSL設計(2025年07月26日更新)

2025/07/20に公開

CLAUDE.mdにDSLを導入してみた

概要：何をやったのか

Claude CodeのエンジニアリングガイドをMarkdown形式からYAML、DSL形式に展開し、構文最適化による37.4%のトークン削減を実現しました。

主な成果

項目	Markdown版	YAML版	DSL版	DSL削減率
ファイル数	10ファイル	30ファイル	30ファイル	-
総行数	1,264行	1,473行	1,573行	-
トークン数	7,041トークン	5,084トークン	4,404トークン	37.4%削減

技術的実現内容

構文効率化: DSL記法によるトークン密度向上
モジュラー設計: 30ファイルによる保守性向上
配列フォーマット標準化: 可読性とトークン効率の両立
Claude Code完全互換: 既存ワークフローを維持

実証された効果

コスト削減: 37.4%のトークン削減による利用料削減
保守性向上: モジュラー設計による更新の容易さ
品質安定: 構造化による一貫した出力品質
処理効率: トークン削減による応答速度改善

Why（なぜ）：トークン効率化の必要性

トークン経済の現実

Claude、GPT-4、Geminiなどの大規模言語モデル（LLM）は、トークン単位で課金されます。複雑なエンジニアリング指示では数千トークンを消費し、コストが急速に増加します。

トークン課金の例（Claude 3.5 Sonnet）:
- 入力: $3.00 / 1M tokens
- 出力: $15.00 / 1M tokens

Claude Codeでの課題

Claude Codeは、プロジェクトルートのCLAUDE.mdを自動読み込みしてAIに指示を与える革新的なツールです。しかし、実用的なエンジニアリングガイドを作ると：

実測値による比較:

Markdown版: 7,041トークン（ベースライン）
YAML版:    5,084トークン（27.8%削減）
DSL版:     4,404トークン（37.4%削減）

なぜこれが問題なのか

月間コストの増加
- 10人チーム、月1000タスクで約$21の利用料
- DSL化により約$13に削減可能（年間$95の節約）
処理効率の低下
- 長いプロンプトによる応答時間の増加
- 冗長な記述による処理負荷
開発体験への影響
- 遅いレスポンス → 開発リズムの悪化
- エンジニアがツール利用を控える傾向

How（どうやって）：実装戦略

トークン効率化の3つのアプローチ

1. 構文の簡潔性

YAML版（クォート必要）:

items: [
  "first_item",
  "second_item"
]

DSL版（クォート不要）:

items: [
  first_item,
  second_item
]

2. 変数参照の効率性

YAML版:

validation_order: "${variables.validation_order}"

DSL版:

validation_order: ${variables.validation_order}

3. 構造化による情報密度向上

DSLの階層構造により、効率的な情報配置：

components:
  validation_rules: ${variables.validation_order}
  mandatory_validation:
    halt_condition: validation_passed = false

実装アーキテクチャ

全バージョン共通の実行フロー

CLAUDE.md → entry-point.[dsl|yml|md] → 全30ファイル読み込み

ファイル構成と役割

dsl/
├── CLAUDE.md (9行)
├── entry-point.dsl (98行) 
├── development.dsl (135行)
├── app-types.dsl (77行)
├── checklist.dsl (24行)
├── risk-assessment.dsl (70行)
├── behavior-rules/ (7ファイル、331行)
├── coding-rules/ (4ファイル、244行)
├── design-rules/ (3ファイル、177行)
├── security-rules/ (5ファイル、254行)
├── validation-rules/ (4ファイル、84行)
└── git-rules/ (2ファイル、79行)

Claude Code互換性の維持

# CLAUDE.md - DSL Version
Follow entry-point.dsl for complete DSL execution.

What（何を）：Claude DSL v0.3による構造化

DSLによる効率的な記述

従来のMarkdownではなく、構文効率を重視した構造化フォーマットを設計しました。

従来のMarkdown（冗長）

## Your Role (Professional Behavior)

You are a mission-critical super engineer focused on sustainable excellence. Embody these traits:

- **Ask clarifying questions BEFORE coding**: Never assume requirements
- **Explain technical decisions in business terms**: Quantify impact

Claude DSL v0.3（効率的）

variables:
  behaviors_list:
    ask clarifying questions: Never assume requirements
    explain technical decisions: Quantify impact (performance gains = revenue impact)

DSLの核心設計

1. 変数による一元管理

variables:
  validation_order: [
    run_unit_tests_if_available,
    verify_startup_success,
    test_end_to_end_user_experience,
    verify_critical_paths_manually,
    test_api_with_real_requests
  ]

2. コンポーネント参照

components:
  behaviors: ${variables.behaviors_list}
  checklist_basic: ${variables.checklist_questions}
  validation_rules: ${variables.validation_order}

3. 統一された配列フォーマット

files: [
  development.dsl,
  behavior-rules/index.dsl,
  coding-rules/index.dsl,
  design-rules/index.dsl,
  security-rules/index.dsl,
  validation-rules/index.dsl,
  git-rules/index.dsl,
  app-types.dsl,
  risk-assessment.dsl,
  checklist.dsl
]

実装結果：トークン削減の内訳

メトリック	Markdown	YAML	DSL	DSL効果
ファイル数	10	30	30	モジュラー化
総行数	1,264	1,473	1,573	構造化拡張
トークン数	7,041	5,084	4,404	37.4%削減
語数密度	5.57語/行	3.45語/行	2.80語/行	最適化

なぜ37.4%削減が可能だったのか

マークアップ記法の排除: **, ##, -などの装飾文字を削除
クォート削除: DSL構文による記述量削減
重複情報の変数化: 同一概念を変数で一元管理
構造化による情報密度向上: 効率的な階層配置

実装の詳細：設計判断と技術的解決策

モジュラー設計による保守性向上

カテゴリ別のファイル構成

# behavior-rules/index.dsl
flow:
  - action: load_external
    files: [
      behavior-rules/communication-behavior.dsl,
      behavior-rules/work-process-behavior.dsl,
      behavior-rules/task-classification-behavior.dsl,
      behavior-rules/failure-recovery-behavior.dsl,
      behavior-rules/unexpected-situation-behavior.dsl,
      behavior-rules/debugging-analysis-behavior.dsl
    ]

重複定義の排除

variables:
  validation_order: [
    run_unit_tests_if_available,
    verify_startup_success,
    test_end_to_end_user_experience,
    verify_critical_paths_manually,
    test_api_with_real_requests
  ]

components:
  validation_rules: ${variables.validation_order}
  all_must_complete: ${variables.validation_order}

役割ベースの命名規則

entry-point.dsl: メインエントリポイント
development.dsl: 開発専用ルール
checklist.dsl: チェックリスト
validation-rules/: 検証ルール定義
app-types.dsl: アプリケーション種別定義

効果測定と検証

トークン削減の実測値

実際のファイル内容を含む正確な計算:

測定条件:
- 全DSLファイル内容を含む
- ファイル読み込みコストを含む
- Claude Tokenizer使用

結果:
Markdown版: 7,041トークン
YAML版:    5,084トークン (27.8%削減)
DSL版:     4,404トークン (37.4%削減)

コスト削減効果

月間利用コストの比較（実測ベース）:

前提条件:
- チーム規模: 10名のエンジニア
- 月間タスク数: 1,000件
- Claude 3.5 Sonnet使用

Markdown版の月間コスト:
├── 全タスク: 1,000 × 7,041tokens = 7,041,000 tokens
└── 月額費用: $21.12

DSL版の月間コスト:
├── 全タスク: 1,000 × 4,404tokens = 4,404,000 tokens
└── 月額費用: $13.21

年間コスト削減: ($21.12 - $13.21) × 12 = $94.92

実用性の検証

実際のプロジェクトでの活用結果:

応答速度の改善: 37.4%のトークン削減による処理時間短縮
保守性の向上: モジュラー設計による更新の容易さ
品質の安定: 構造化により一貫した出力品質
開発効率: 統一フォーマットによる理解しやすさ

今後の展望：さらなる最適化

1. 構文最適化の余地

# 現在の最適化余地
current_tokens: 4,404
target_tokens: 3,500
potential_reduction: 20%

2. 自動最適化ツール

optimization_tool:
  token_analysis: true
  redundancy_detection: true
  syntax_optimization: true

3. 業界別DSLテンプレート

Web開発特化版: React、TypeScript、Node.js向け
ML/AI開発特化版: Python、PyTorch、TensorFlow向け
モバイル開発特化版: React Native、Flutter向け

まとめ：実証されたトークン効率化

Claude DSL v0.3は、実測ベースで37.4%のトークン削減を実現し、AIエンジニアリングの効率化を実証しました。

得られた知見

構文効率: DSL記法がYAMLより効率的
モジュラー設計: 保守性とトークン効率の両立
配列フォーマット標準化: 可読性向上とトークン削減
実用性の確保: Claude Code完全互換

実際の効果

コスト削減: 年間$95の節約（10人チーム）
速度向上: 37.4%のトークン削減による処理時間短縮
保守改善: モジュラー設計による更新の容易さ
品質向上: 構造化による一貫性確保

適用推奨場面

DSLが適している:

トークン効率を最優先する場合
長期的な保守性を重視する場合
チームでの一貫性が重要な場合

Markdownが適している:

簡単な設定で済ませたい場合
学習コストを避けたい場合
ファイル数を少なく保ちたい場合

リポジトリ

ファイル構成:

markdown/: 10ファイル、1,264行、7,041トークン
yaml/: 30ファイル、1,473行、5,084トークン
dsl/: 30ファイル、1,573行、4,404トークン

実測値に基づく37.4%のトークン削減により、AIエンジニアリングのコストと効率を実証的に改善しました。構文効率化により、ファイル数は増加したものの、トークン効率と保守性の両立を実現しています。