## Context

### 背景

search_contentツールは、LLMがコード検索を行う際の主要なインターフェースであり、ripgrepを使用して高速なテキスト検索を提供している。しかし、現在のツール定義では、LLMが最適なパラメータを選択するための十分な情報が提供されていない。

### 問題の具体例

実際のLLM使用パターンを分析すると、以下のような非効率な使用が頻繁に発生している：

1. **デフォルトでフル詳細を取得**: LLMは件数確認だけで十分な状況でも、デフォルトのnormal mode（~10,000-50,000トークン）を使用
2. **パラメータ競合エラー**: `total_only`と`count_only_matches`を同時指定し、実行時エラーが発生
3. **段階的取得の欠如**: 最初から詳細情報を取得し、後で「やはり件数だけで良かった」と判明

### ステークホルダー

- **LLM開発者**: より効率的なツール使用パターンを実現したい
- **エンドユーザー**: トークン消費を削減し、応答速度を向上させたい
- **プロジェクトメンテナ**: ツールの使いやすさと保守性を向上させたい

## Goals / Non-Goals

### Goals

1. **LLMの自律的最適化**: LLMがツール定義だけで最適なパラメータを選択できるようにする
2. **トークン効率30-50%改善**: 段階的使用戦略の採用により、平均30-50%のトークン削減
3. **エラー率80%削減**: パラメータ競合エラーを80%以上削減
4. **完全な後方互換性**: 既存のAPI、パラメータ、動作を一切変更しない
5. **再利用可能なパターン**: 他のMCPツールにも適用可能なLLMガイダンスパターンの確立

### Non-Goals

1. **APIの変更**: 既存のパラメータ、レスポンス形式、エラーハンドリングは変更しない
2. **新規パラメータの追加**: 新しい出力形式パラメータは追加しない（既存パラメータの説明強化のみ）
3. **ripgrepの置き換え**: 検索エンジンの変更は行わない
4. **動的なガイダンス**: 実行時にLLMにガイダンスを提供する仕組みは導入しない（ツール定義のみで完結）

## Decisions

### Decision 1: ツール定義への埋め込み vs 外部ドキュメント

**選択**: ツール定義（`get_tool_definition()`のdescriptionフィールド）に直接埋め込む

**理由**:
- LLMはツール使用時にツール定義を参照するため、最も即効性が高い
- 外部ドキュメントは参照されない可能性が高い（システムプロンプトに含める必要がある）
- MCPプロトコルの標準的な方法であり、他のツールとの一貫性を保てる

**トレードオフ**:
- ✅ メリット: 即座に効果が出る、追加の仕組み不要、プロトコル標準に準拠
- ⚠️ デメリット: ツール定義が長くなる（約150行追加）、メンテナンス箇所が増える

**代替案**:
- システムプロンプトに追加: Rooモードごとに異なるルールが必要になり、複雑化
- 外部ドキュメント: LLMが参照しない可能性が高く、効果が不確実

### Decision 2: マーカー（絵文字）の使用

**選択**: `⚠️`, `🎯`, `💡`, `📊`などの絵文字マーカーを使用する

**理由**:
- LLMは視覚的マーカーを認識し、重要情報の識別が容易になる
- 人間が読む場合も可読性が向上する
- 業界標準のプラクティス（GitHub、各種ドキュメントで広く使用）

**トレードオフ**:
- ✅ メリット: 情報の階層化、スキャン性向上、標準化されたパターン
- ⚠️ デメリット: 一部のレンダラーで絵文字が表示されない可能性（稀）

**代替案**:
- テキストマーカー（`[IMPORTANT]`など）: 冗長で可読性が低い
- マーカーなし: 重要情報の識別が困難

### Decision 3: トークンコストの数値提示

**選択**: 具体的なトークン数の目安を提示する（例：`~10 tokens`, `~50-200 tokens`）

**理由**:
- LLMは定量的情報に基づいて判断を行うため、具体的な数値が必要
- 相対的な表現（「効率的」「非効率的」）だけでは不十分
- 実測値に基づいた信頼性の高い情報

**トレードオフ**:
- ✅ メリット: LLMの判断精度向上、定量的な最適化、透明性
- ⚠️ デメリット: 実際のトークン数はクエリやマッチ数に依存するため、目安に過ぎない

**代替案**:
- 相対的表現のみ（「最も効率的」）: 定量的判断ができない
- トークン数を提示しない: LLMが試行錯誤で学習する必要がある

### Decision 4: 段階的使用フローの明示

**選択**: 5ステップの推奨ワークフローを明示する

```
Step 1: total_only (件数確認) → 0件なら終了
Step 2: count_only_matches (ファイル別件数) → 少数ファイルならStep 3
Step 3: summary_only (サマリー確認) → 詳細が必要ならStep 4
Step 4: group_by_file (グループ化) → 全詳細が必要ならStep 5
Step 5: Normal (全詳細取得)
```

**理由**:
- LLMは明示的なフローチャートに従いやすい
- 各ステップでの判断基準を示すことで、無駄な情報取得を回避
- 実際の使用パターンを分析した結果に基づく最適化

**トレードオフ**:
- ✅ メリット: トークン効率30-50%改善、明確なガイダンス、学習不要
- ⚠️ デメリット: 全てのユースケースに適合しない可能性（柔軟性とのバランス）

**代替案**:
- フローを提示しない: LLMが非効率な使用を継続
- より複雑なフロー（7-10ステップ）: 複雑すぎて逆効果

### Decision 5: エラーメッセージの多言語化

**選択**: 英語と日本語の両方でエラーメッセージを提供

**理由**:
- このプロジェクトは日本語圏でも広く使用されている
- エラーメッセージの理解度向上により、LLMの学習効率が上がる
- グローバルなベストプラクティス

**トレードオフ**:
- ✅ メリット: ユーザビリティ向上、グローバル対応、学習効率向上
- ⚠️ デメリット: メンテナンスコスト増加、メッセージが長くなる

**代替案**:
- 英語のみ: 日本語圏ユーザーの理解度低下
- 動的な言語選択: 複雑な実装が必要、LLMには効果が限定的

## Risks / Trade-offs

### Risk 1: ツール定義の肥大化

**リスク**: descriptionフィールドが約150行増加し、ツール定義全体が約500行になる

**影響**: 
- ツール定義の読み込みにわずかな遅延（推定: +10-20ms）
- MCPプロトコルでの転送サイズ増加（約5-10KB）

**緩和策**:
- description内容は静的で一度読み込むだけなので、パフォーマンスへの影響は最小
- 必要に応じて圧縮やキャッシングを検討
- 効果測定により、トークン削減効果がコスト増を上回ることを確認

### Risk 2: LLMがガイダンスを無視する可能性

**リスク**: 一部のLLMモデルがツール定義のdescriptionを十分に解析しない可能性

**影響**: 
- 期待されるトークン効率改善が得られない
- エラー削減効果が限定的

**緩和策**:
- 複数のLLMモデル（Claude、GPT-4、etc）でテストを実施
- システムプロンプトとの併用（Rooルールに同様の内容を追加）
- 効果測定を行い、必要に応じて追加の改善策を検討

### Risk 3: メンテナンスコストの増加

**リスク**: ツール定義の説明が詳細化されることで、将来の変更時のメンテナンスコストが増加

**影響**:
- パラメータ追加時に複数箇所の更新が必要
- 一貫性維持のための追加作業

**緩和策**:
- テストによる検証（必須セクションとマーカーの存在確認）
- ドキュメント生成の自動化を検討
- 変更ガイドラインの作成（tasks.mdに含む）

## Migration Plan

### Phase 1: 実装とテスト（Week 1-2）

1. **Day 1-3**: ツール定義の修正
   - search_content_tool.pyのdescription拡張
   - パラメータdescriptionの強化
   - コードレビューと調整

2. **Day 4-6**: エラーメッセージの多言語化
   - output_format_validator.pyの修正
   - 英語・日本語メッセージの作成
   - テストの作成と実行

3. **Day 7-10**: ドキュメント更新
   - Rooルールの作成
   - README更新
   - 設計ドキュメント更新

4. **Day 11-14**: テストと検証
   - 単体テスト
   - 統合テスト
   - LLMシミュレーションテスト

### Phase 2: 効果測定（Week 3）

1. **Day 15-17**: メトリクス収集
   - トークン消費量の測定
   - 応答速度の測定
   - エラー発生率の測定

2. **Day 18-19**: 分析と調整
   - データ分析
   - 必要に応じた微調整
   - ドキュメント最終化

3. **Day 20-21**: リリース準備
   - CHANGELOG更新
   - リリースノート作成
   - 最終レビュー

### Rollback Plan

変更は完全に後方互換性があるため、ロールバックは容易：

1. **ツール定義の復元**: `get_tool_definition()`メソッドを以前のバージョンに戻す
2. **エラーメッセージの復元**: `output_format_validator.py`を以前のバージョンに戻す
3. **ドキュメントの復元**: Gitで該当コミットをrevert

**影響範囲**: 
- APIやパラメータに変更がないため、既存コードへの影響なし
- 既存テストは全て通過する（後方互換性テストで確認済み）

## Open Questions

### Q1: LLMモデルごとの効果の差異

**Question**: Claude、GPT-4、その他のLLMモデルで、ガイダンスの効果に差はあるか？

**調査計画**: 
- 複数のLLMモデルでA/Bテストを実施
- トークン削減率、エラー率をモデルごとに測定
- 結果に基づいて、モデル別のガイダンス調整を検討

### Q2: descriptionの最適な長さ

**Question**: 約150行の追加は適切か？より簡潔にできないか？

**調査計画**:
- 段階的に情報を削減したバリエーションでテスト
- 効果（トークン削減率）とdescription長のトレードオフを測定
- 最適なバランスポイントを特定

### Q3: 動的ガイダンスの必要性

**Question**: 静的なツール定義だけで十分か？実行時に動的なガイダンスを提供すべきか？

**今後の検討事項**:
- 現在の静的アプローチの効果を測定
- 効果が不十分な場合、動的ガイダンス（例：前回の検索結果に基づく推奨）を検討
- ただし、複雑性増加とのバランスを考慮

### Q4: 他のMCPツールへの展開

**Question**: このLLMガイダンスパターンは、他のMCPツール（list_files、find_and_grepなど）にも適用すべきか？

**今後の計画**:
- search_contentでの効果測定を完了
- 効果が実証された場合、他のツールにも段階的に適用
- OpenSpec「llm-guidance」capabilityを正式な標準として確立