トークン効率化戦略

プロジェクト設定、モデル選択、ワークフロー最適化により、品質を保ちながらトークン使用量を削減する。

Token使用量はコストだけの問題ではありません。フィードバックループの速度とコンテキストウィンドウの制限にも関わります。このガイドでは、プロジェクトの最適化、賢いモデル選択、ワークフローパターンを通じて、より少ないTokenでより多くのことを実現する方法を示します。

**Factory Appを使用していますか？**これらの戦略はCLIとFactory Appの両方に適用されます。Agent Readinessダッシュボードでプロジェクトの準備状況スコアを確認できます。

---

​

Token使用量の理解

Tokenは主に3つの領域で消費されます：

┌──────────────────────────────────────────────────────────┐
│                    Token Consumption                      │
├────────────────┬────────────────┬────────────────────────┤
│   Context      │   Tool Calls   │   Model Output         │
│   (Input)      │   (Overhead)   │   (Response)           │
├────────────────┼────────────────┼────────────────────────┤
│ • AGENTS.md    │ • Read files   │ • Explanations         │
│ • Memories     │ • Grep/search  │ • Generated code       │
│ • Conversation │ • Execute cmds │ • Analysis             │
│ • File content │ • Each retry   │ • Thinking tokens      │
└────────────────┴────────────────┴────────────────────────┘

高いトークン使用量は通常以下を意味します：

• 過度な探索（不明確な指示）
• 複数回の試行（コンテキスト不足またはテストの失敗）
• 冗長な出力（フォーマット制約なし）

---

​

効率性のためのプロジェクトセットアップ

最大のトークン節約は、無駄なサイクルを防ぐプロジェクト設定から生まれます。

​

1. 高速で信頼性の高いテスト

遅い、または不安定なテストは、トークンの無駄の最大の原因です。各リトライは完全なレスポンスサイクルのコストがかかります。

テストの特徴	トークンへの影響
高速テスト（30秒未満）	Droidは変更を即座に検証
低速テスト（2分超）	Droidは検証をスキップするか、待機中にコンテキストを無駄にする可能性
不安定なテスト	誤った失敗がデバッグサイクルを引き起こす
テストなし	Droidは変更を検証できず、より多くのやり取りが発生

アクション項目：

## In your AGENTS.md

## Testing
- Run single file: `npm test -- path/to/file.test.ts`
- Run fast smoke tests: `npm test -- --testPathPattern=smoke`
- Full suite takes ~3 minutes, use `--bail` for early exit on failure

​

2. リンティングと型チェック

Droidがエラーを即座に検出できる場合、あなたからの報告を待つのではなく、同じターンで修正します。

## In your AGENTS.md

## Validation Commands
- Lint (auto-fix): `npm run lint:fix`
- Type check: `npm run typecheck`
- Full validation: `npm run validate` (lint + typecheck + test)

Always run `npm run lint:fix` after making changes.

​

3. 明確なプロジェクト構造

Droidがトークンを無駄に消費して探索しないよう、ファイル構成を文書化してください：

## In your AGENTS.md

## Project Structure
- `src/components/` - React components (one per file)
- `src/hooks/` - Custom React hooks
- `src/services/` - API and business logic
- `src/types/` - TypeScript type definitions
- `tests/` - Test files mirror src/ structure

When adding a new component:
1. Create component in `src/components/ComponentName/`
2. Add index.ts for exports
3. Add ComponentName.test.tsx in same directory

---

​

エージェント準備チェックリスト

エージェント準備レポートは、トークン効率に直接影響する基準に対してプロジェクトを評価します。

​

高影響基準

基準	トークンへの影響	重要な理由
リンター設定	🟢 高	エラーを即座にキャッチし、デバッグサイクルを削減
型チェッカー	🟢 高	実行時エラーを防ぎ、コードをより明確に
実行可能なユニットテスト	🟢 高	同じターンでの検証
AGENTS.md	🟢 高	事前のコンテキスト、探索の削減
ビルドコマンドドキュメント	🟡 中	推測不要、失敗の試行を削減
依存関係の固定	🟡 中	再現可能なビルド
プリコミットフック	🟡 中	自動品質強制

準備レポートを実行してギャップを特定してください：

droid
> /readiness-report

---

​

モデル選択戦略

異なるモデルには異なるコスト倍率と機能があります。タスクに応じてモデルを選択しましょう：

​

コスト倍率

現在のモデル倍率については利用可能なモデルを参照してください。

​

タスク別モデル選択

Simple edit, formatting      → Haiku 4.5 (0.4×)
Implement feature from spec  → GPT-5.3-Codex (0.7×)
Debug complex issue          → Sonnet 4.5 (1.2×)
Architecture planning        → Opus 4.7 (1x, 2x after 4/30) or Opus 4.6 (2×)
Bulk file processing         → Droid Core (MiniMax M2.7 at 0.12× or Kimi K2.6 at 0.4×)

​

推論努力の影響

推論レベルが高い = より多くの「思考」トークンを使用するが、多くの場合再試行回数は減る。

推論	使用タイミング	トークンのトレードオフ
オフ/なし	シンプルで明確なタスク	ターンあたり最少、より多くのターンが必要な場合あり
低	標準的な実装	良いバランス
中	複雑なロジック、デバッグ	ターンあたり高め、再試行回数は少なめ
高	アーキテクチャ、分析	ターンあたり最高、初回試行の成功率が最も高い

経験則: 初回試行を間違えた場合の修正コストが高いタスクでは、より高い推論レベルを使用する。

混合モデルを設定して、計画と実装で異なるモデルを自動的に使用できます。設定については混合モデルを参照してください。

---

​

効率性のためのワークフローパターン

​

パターン1: 複雑な作業のための仕様モード

実装前の計画に仕様モード（Shift+Tabまたは/spec）を使用します。

**仕様モードを使わない場合:**
Turn 1: Start implementing → wrong approach → wasted tokens
Turn 2: Undo and try different approach → more tokens
Turn 3: Finally get it right
Total: 3 turns of implementation tokens

**Spec Modeで:**
Turn 1: Plan with exploration → correct approach identified
Turn 2: Implement correctly
Total: 1 turn of planning + 1 turn of implementation

以下のようなタスクには、Specモード（Shift+Tabまたは/spec）を使用してください：

• 2つ以上のファイルに触れる
• 既存のパターンの理解が必要
• 要件が不明確
• セキュリティに敏感

​

パターン2: コンテキストのためのIDEプラグイン

IDEプラグインがない場合、Droidはコンテキストを理解するためにファイルを読む必要があります：

Read file A → Read file B → Read file C → Understand context → Work
(4 tool calls before actual work)

IDE プラグインを使用すると、コンテキストが即座に利用できます：

Work (IDE provides open files, errors, selection)
(0 extra tool calls for context)

​

パターン3: 一般的なものよりも具体的なもの

**高コストなプロンプト:**
"Fix the bug in the auth module"

→ Droidは複数のファイルを読み取ってバグを見つけ、さまざまな可能性を探る

**効率的なプロンプト：**
"Fix the timeout bug in src/auth/session.ts line 45 where the session expires after 5 minutes instead of 24 hours"

→ Droidが直接イシューに移動します

​

パターン4: 類似作業のバッチ処理

**コストが高い:**
Turn 1: "Add logging to userService"
Turn 2: "Add logging to orderService"
Turn 3: "Add logging to paymentService"
(3 turns, context rebuilt each time)

**効率的:**
Turn 1: "Add structured logging to all services in src/services/. Use the pattern from src/lib/logger.ts. Services: user, order, payment."
(1 turn, pattern established once)

---

​

トークンの無駄遣いを減らす

​

よくある無駄遣いパターン

パターン	原因	修正方法
複数回の探索サイクル	不明確な要件	事前に具体的に指定する
ファイルの繰り返し読み込み	IDEコンテキストの不足	IDEプラグインをインストールする
失敗した試行	テスト/リンティングなし	検証ツールを追加する
冗長な説明	フォーマット制約なし	簡潔な出力を求める
間違ったアーキテクチャ	コンテキストの不足	Spec Modeを使用する

​

フォーマット制約

冗長性を減らすため、特定の出力フォーマットを要求する：

"Add the feature. Return only the changed code, no explanations unless something is unclear."

"Review this code. Format: bullet list of issues only, no preamble."

"Debug this test failure. Show me the fix, then explain in 2-3 sentences."

---

​

使用量の監視

​

現在のセッション費用を確認

droid
> /cost

現在のセッションのトークン使用量を表示します。

​

時間経過の追跡

使用パターンを確認しましょう：

1. 各セッション後、/cost の出力をメモする
2. 高コストセッションを特定：何が高コストの原因だったか？
3. アプローチの改善：より多くのコンテキスト？異なるモデル？より良いプロンプト？

​

使用量の警告サイン

以下のパターンに注意してください：

• 🚩 高い読み取り回数：Droidが過剰に探索している（AGENTS.mdのコンテキストを追加）
• 🚩 複数のgrep/検索呼び出し：何を探すかが不明確（より具体的に）
• 🚩 類似の編集の繰り返し：失敗した試行（テスト/リンティングを確認）
• 🚩 非常に長い会話：スコープの拡大（小さなタスクに分割）

---

​

即効性チェックリスト

即座にトークンを節約するために以下を実装してください：

• IDEプラグインをインストール - コンテキスト収集のツール呼び出しを排除
• AGENTS.mdを作成 - Droidがビルド/テストコマンドを事前に把握
• リンティングを設定 - エラーを即座にキャッチ
• 高速テストコマンド - 同一ターンでの検証
• Spec Modeを使用 - 高コストな誤ったスタートを防止
• 具体的に指示 - 探索サイクルを削減
• タスクに適したモデルを選択 - 単純な編集にOpusを使わない

---

​

トークン予算ガイドライン

一般的なタスクの大まかなガイドライン：

タスクタイプ	典型的なトークン範囲	備考
簡単な編集	5k-15k	シンプルで具体的な変更
機能実装	30k-80k	Spec Modeプランニング込み
複雑なデバッグ	50k-150k	複数回の試行が必要な場合
アーキテクチャ計画	20k-50k	高推論モデル
コードレビュー	30k-60k	PRサイズに依存
一括リファクタリング	50k-200k	多数のファイル、効率的なモデルを使用

これらの範囲を大幅に超えている場合は、上記の無駄なパターンを確認してください。

---

## まとめ：トークン効率的なワークフロー
1. Set up your project
   └─ AGENTS.md with commands
   └─ Fast tests
   └─ Linting configured
   └─ IDE plugin installed

2. Start each task right
   └─ Use Spec Mode for complex work
   └─ Be specific about the goal
   └─ Reference existing patterns

3. Choose the right model
   └─ Simple → Haiku/Droid Core
   └─ Standard → Codex/Sonnet
   └─ Complex → Opus (with reasoning)

4. Monitor and adjust
   └─ Check /cost periodically
   └─ Identify expensive patterns
   └─ Refine your approach

---

​

次のステップ

セットアップチェックリスト

パワーユーザー設定を完了する

準備状況レポート

プロジェクトのAI対応状況を評価する