# 要件ドキュメント

## はじめに

本機能は、Tree-sitter Analyzer の MCP ツール群の作業効率を最大化し、ツール呼び出し回数を削減することを目的とします。現在のツールアーキテクチャには、重複処理、キャッシュ未活用、並列実行の欠如など複数の非効率性が存在し、これらを体系的に改善することで、ツール呼び出し回数を 50-70% 削減し、レスポンス時間を 40-60% 短縮することを目指します。

### 現状分析サマリー

| 指標 | 現状 | 目標 |
|------|------|------|
| 平均ツール呼び出し回数/タスク | 5-8回 | 2-3回 |
| 平均レスポンス時間 | 500-800ms | 200-400ms |
| キャッシュヒット率 | 20-30% | 60-80% |
| トークン消費量 | 100% | 50-70% |

### 特定された非効率性

| 問題 | 影響 | 発生箇所 |
|------|------|----------|
| **重複セキュリティ検証** | 同一ファイルへの複数呼び出しで毎回検証 | `BaseMCPTool`, `server.py` |
| **言語検出の重複** | 各ツールで独自に言語を再検出 | `analyze_scale_tool.py`, `table_format_tool.py` |
| **キャッシュ未活用** | ツール間でキャッシュが共有されていない | 各ツール実装 |
| **冗長なファイル読み込み** | 同一ファイルを複数回読み込む | `_calculate_file_metrics` |
| **パス解決の重複** | 各ツールで個別にパス解決 | `BaseMCPTool.path_resolver` |
| **並列実行の欠如** | 複数ファイル分析が逐次処理 | `MCPAdapter.analyze_batch_async` |

### 改善フェーズ計画

| フェーズ | 期間 | 改善項目 | 期待効果 |
|---------|------|----------|----------|
| Phase 1 | 1-2日 | 冗長処理の排除、基本キャッシュ | 10-20% |
| Phase 2 | 3-5日 | 共有キャッシュ、事前計算 | 30-40% |
| Phase 3 | 1-2週 | バッチツール、並列実行 | 50-70% |
| Phase 4 | 2-4週 | パイプライン再設計、統合ツール | 60-80% |

## 用語集

| 用語 | 説明 |
|------|------|
| **MCP** | Model Context Protocol - AI アシスタント統合プロトコル |
| **ツール呼び出し** | MCP クライアントからサーバーへの単一リクエスト |
| **SharedToolCache** | ツール間で共有されるキャッシュ機構 |
| **ToolContext** | ツール実行時に共有されるコンテキスト情報 |
| **バッチ処理** | 複数の操作を単一リクエストで実行する方式 |
| **事前計算** | 頻繁に使用される値を事前に計算・キャッシュする手法 |
| **遅延評価** | 値が実際に必要になるまで計算を遅延する手法 |
| **パイプライン** | 前処理・実行・後処理を統一的に管理するフロー |

## 要件

> 注記: 本ドキュメントでは、受け入れ基準を **日本語** で記述します（曖昧さを減らすため、「〜の場合、システムは〜しなければならない」の形式で統一します）。

### 要件1: 重複セキュリティ検証の排除 [Phase 1]

**ユーザーストーリー:** 開発者として、同一ファイルへの複数アクセス時にセキュリティ検証を一度だけ実行したい。これにより、不要なオーバーヘッドを削減できる。

**優先度:** ⭐⭐⭐⭐⭐ (Critical)
**実装難易度:** 低
**期待効果:** 10-15% 削減
**リスク:** 低

#### 受け入れ基準

1. ファイルパスを検証した場合、システムは同一セッション内の後続リクエストのために検証結果をキャッシュしなければならない
2. 解決済み（resolved）パスを検証した場合、システムは元のパスを別途再検証してはならない
3. 複数のツールが同一ファイルへアクセスする場合、システムはキャッシュ済みの検証結果を再利用しなければならない
4. プロジェクトパスが変更された場合、システムはキャッシュされた検証結果をすべて無効化しなければならない

#### 対象ファイル

| ファイル | 変更内容 |
|---------|---------|
| `mcp/tools/base_tool.py` | セキュリティ検証キャッシュの追加 |
| `mcp/tools/analyze_scale_tool.py` | 重複検証の削除 |
| `mcp/server.py` | 検証結果の共有機構 |

---

### 要件2: 言語検出キャッシュの実装 [Phase 1]

**ユーザーストーリー:** 開発者として、ファイルの言語検出結果をキャッシュしたい。同一ファイルに対する複数回の言語検出を防ぐことで、処理効率を向上させる。

**優先度:** ⭐⭐⭐⭐⭐ (Critical)
**実装難易度:** 低
**期待効果:** 5-10% 削減
**リスク:** 低

#### 受け入れ基準

1. ファイルの言語を検出した場合、システムは絶対パスをキーとして検出結果をキャッシュしなければならない
2. 同一ファイルが別ツールで処理される場合、システムは再検出せずにキャッシュ済み言語を返さなければならない
3. ファイルが更新された場合（mtime 変更）、システムはキャッシュされた言語を無効化しなければならない
4. 未対応の拡張子に遭遇した場合、システムは繰り返し検出を避けるために `unknown` をキャッシュしなければならない

#### 対象ファイル

| ファイル | 変更内容 |
|---------|---------|
| `mcp/utils/shared_cache.py` | 新規: 言語検出キャッシュ |
| `mcp/tools/base_tool.py` | キャッシュ利用の追加 |
| `language_detector.py` | キャッシュ対応 |

---

### 要件3: ファイルメトリクス計算の統合 [Phase 1]

**ユーザーストーリー:** 開発者として、ファイルメトリクス計算ロジックを一箇所に統合したい。現在 `server.py` と `analyze_scale_tool.py` に重複実装があり、保守性とパフォーマンスに影響している。

**優先度:** ⭐⭐⭐⭐ (High)
**実装難易度:** 低
**期待効果:** 5-10% 削減
**リスク:** 低

#### 受け入れ基準

1. ファイルメトリクスを算出する場合、システムは単一の統合実装を使用しなければならない
2. 同一ファイルのメトリクスが複数回要求された場合、システムはキャッシュ済み結果を返さなければならない
3. メトリクス算出では、`total_lines` / `code_lines` / `comment_lines` / `blank_lines` / `estimated_tokens` / `file_size_bytes` を必ず含めなければならない
4. ファイル内容が変更された場合、システムはキャッシュされたメトリクスを無効化しなければならない

#### 対象ファイル

| ファイル | 変更内容 |
|---------|---------|
| `mcp/utils/file_metrics.py` | 新規: 統合メトリクス計算 |
| `mcp/server.py` | 既存実装の削除、新モジュール利用 |
| `mcp/tools/analyze_scale_tool.py` | 既存実装の削除、新モジュール利用 |

---

### 要件4: SharedToolCache の実装 [Phase 2]

**ユーザーストーリー:** AI アシスタントとして、ツール間でキャッシュを共有したい。これにより、同一ファイルへの複数回アクセス時のパフォーマンスが大幅に向上する。

**優先度:** ⭐⭐⭐⭐⭐ (Critical)
**実装難易度:** 中
**期待効果:** 20-30% 削減
**リスク:** 低

#### 受け入れ基準

1. いずれかのツールがファイルを処理した場合、システムは全ツールから参照可能な共有キャッシュに結果を保存しなければならない
2. 別ツールが同一ファイルを要求した場合、システムは可能であればキャッシュ済み結果を返さなければならない
3. キャッシュが容量上限に達した場合、システムは LRU ポリシーでエントリを追い出さなければならない
4. ファイルが更新された場合、システムは関連するキャッシュエントリをすべて無効化しなければならない
5. サーバーが再起動された場合、システムは空のキャッシュから開始しなければならない
6. `output_format` が異なる場合でも、形式差だけを理由に別キャッシュエントリを作成してはならない

#### キャッシュカテゴリ

| カテゴリ | キー | 値 | TTL |
|---------|-----|-----|-----|
| ファイルハッシュ | file_path | content_hash | 無期限 |
| セキュリティ検証 | file_path | (is_valid, error_msg) | 5分 |
| 言語検出 | file_path | language | 無期限 |
| パス解決 | original_path | resolved_path | 無期限 |
| 分析結果 | cache_key | AnalysisResult | 10分 |

#### 対象ファイル

| ファイル | 変更内容 |
|---------|---------|
| `mcp/utils/shared_cache.py` | 新規: 共有キャッシュ実装 |
| `mcp/server.py` | キャッシュインスタンスの管理 |
| `mcp/tools/base_tool.py` | キャッシュアクセス追加 |

---

### 要件5: 事前計算マネージャーの実装 [Phase 2]

**ユーザーストーリー:** 開発者として、頻繁に使用される値を事前計算したい。言語検出やセキュリティパターンの事前コンパイルにより、ランタイムオーバーヘッドを削減する。

**優先度:** ⭐⭐⭐⭐ (High)
**実装難易度:** 中
**期待効果:** 15-20% 削減
**リスク:** 低

#### 受け入れ基準

1. サーバー初期化時、システムはセキュリティ検証用の正規表現パターンをすべて事前コンパイルしなければならない
2. 拡張子チェック時、システムは拡張子→言語の事前計算マッピングを使用しなければならない
3. クイックセキュリティチェック実行時、システムはランタイムコンパイルを行わずに事前コンパイル済みパターンを使用しなければならない
4. 新しいパターンが追加された場合、システムは起動時に事前計算キャッシュを更新しなければならない

#### 事前計算データ

| データ | 説明 |
|--------|------|
| EXTENSION_LANGUAGE_MAP | 拡張子→言語のマッピング (20+ エントリ) |
| SECURITY_PATTERNS | コンパイル済み正規表現パターン |
| COMMON_QUERIES | 言語ごとの共通クエリパターン |

#### 対象ファイル

| ファイル | 変更内容 |
|---------|---------|
| `mcp/precompute.py` | 新規: 事前計算マネージャー |
| `security/validator.py` | 事前コンパイルパターンの利用 |
| `language_detector.py` | 事前計算マップの利用 |

---

### 要件6: バッチ分析ツールの実装 [Phase 3]

**ユーザーストーリー:** AI アシスタントとして、複数ファイルを単一のツール呼び出しで分析したい。これにより、ツール呼び出し回数を大幅に削減できる。

**優先度:** ⭐⭐⭐⭐⭐ (Critical)
**実装難易度:** 中
**期待効果:** 50-70% 削減
**リスク:** 中

#### 受け入れ基準

1. 複数の `file_paths` が指定された場合、システムは単一のツール呼び出しで全ファイルを解析しなければならない
2. 並列実行が有効な場合、システムは設定された上限までファイルを並行処理しなければならない
3. いずれかのファイル解析が失敗した場合、システムは残りのファイル解析を継続し、結果にエラー情報を含めなければならない
4. `operations` が指定された場合、システムは指定された操作（scale / structure / query）のみを実行しなければならない
5. 結果を返す場合、システムはファイルごとのステータスを含む構造化形式で集約して返さなければならない

#### ツール定義

```json
{
  "name": "analyze_batch",
  "description": "共有コンテキストを用いて、複数ファイルを単一呼び出しで解析する",
  "inputSchema": {
    "type": "object",
    "properties": {
      "file_paths": {
        "type": "array",
        "items": {"type": "string"},
        "description": "解析対象ファイルパスの一覧"
      },
      "operations": {
        "type": "array",
        "items": {"type": "string", "enum": ["scale", "structure", "query"]},
        "description": "各ファイルに対して実行する操作"
      },
      "parallel": {
        "type": "boolean",
        "default": true,
        "description": "解析を並列実行する"
      },
      "max_workers": {
        "type": "integer",
        "default": 4,
        "description": "並列ワーカーの最大数"
      },
      "output_format": {
        "type": "string",
        "enum": ["json", "toon"],
        "default": "toon"
      }
    },
    "required": ["file_paths"]
  }
}
```

#### 対象ファイル

| ファイル | 変更内容 |
|---------|---------|
| `mcp/tools/batch_tool.py` | 新規: バッチ分析ツール |
| `mcp/tools/batch_processor.py` | 新規: バッチ処理ロジック |
| `mcp/server.py` | ツール登録追加 |

---

### 要件7: 並列実行エグゼキューターの実装 [Phase 3]

**ユーザーストーリー:** 開発者として、複数の独立した操作を並列実行したい。これにより、バッチ処理のスループットが向上する。

**優先度:** ⭐⭐⭐⭐ (High)
**実装難易度:** 中
**期待効果:** 30-50% 削減
**リスク:** 中

#### 受け入れ基準

1. 複数の独立した操作が投入された場合、システムはそれらを並行実行しなければならない
2. `max_workers` の上限に達した場合、システムは残りの操作をキューイングしなければならない
3. ある操作が失敗した場合でも、システムは他の並行操作に影響を与えてはならない
4. すべての操作が完了した場合、システムは入力順を保持したまま結果を返さなければならない
5. タイムアウトが指定された場合、システムはタイムアウトを超過した操作をキャンセルしなければならない

#### 対象ファイル

| ファイル | 変更内容 |
|---------|---------|
| `mcp/tools/parallel_executor.py` | 新規: 並列実行管理 |
| `mcp/tools/batch_tool.py` | 並列実行の利用 |

---

### 要件8: 統一レスポンス構造の実装 [Phase 2]

**ユーザーストーリー:** 開発者として、すべてのツールで統一されたレスポンス構造を使用したい。これにより、クライアント側の処理が簡素化され、一貫性が向上する。

**優先度:** ⭐⭐⭐ (Medium)
**実装難易度:** 中
**期待効果:** 10-15% 削減
**リスク:** 低

#### 受け入れ基準

1. いずれのツールが応答を返す場合でも、システムは統一された `MCPResponse` 構造を使用しなければならない
2. エラーが発生した場合、システムは `error_code` / `message` / `復旧提案` を含めなければならない
3. `output_format` が未指定の場合、システムは既定で TOON 形式の出力を返さなければならない
4. JSON 形式が要求された場合、システムは基礎となる解析/キャッシュ挙動を変えずに JSON へ変換しなければならない
5. メタデータを含める場合、システムは一貫した `meta` フィールド構造を使用しなければならない

#### レスポンス構造

```python
@dataclass
class MCPResponse(Generic[T]):
    success: bool
    data: T | None = None
    error: str | None = None
    error_code: str | None = None
    meta: dict[str, Any] | None = None
    suggestion: str | None = None
```

#### 対象ファイル

| ファイル | 変更内容 |
|---------|---------|
| `mcp/models/response.py` | 新規: 統一レスポンス構造 |
| `mcp/tools/*.py` | レスポンス構造の適用 |

---

### 要件9: find_and_analyze 統合ツールの実装 [Phase 4]

**ユーザーストーリー:** AI アシスタントとして、ファイル検索と分析を単一のツール呼び出しで実行したい。現在の2段階呼び出し（find_and_grep → check_code_scale）を統合する。

**優先度:** ⭐⭐⭐⭐ (High)
**実装難易度:** 中
**期待効果:** 40-60% 削減
**リスク:** 低

#### 受け入れ基準

1. 検索条件と解析オプションが指定された場合、システムは単一呼び出しでファイル探索と解析を実行しなければならない
2. `max_files` が指定された場合、システムは解析対象を上位 N ファイルに制限しなければならない
3. `analyze_options.include_scale` が true の場合、システムは結果にスケール指標を含めなければならない
4. `analyze_options.include_structure` が true の場合、システムは結果に構造情報を含めなければならない
5. ファイルが見つかったが解析が失敗した場合、システムはエラー情報を含む部分結果を返さなければならない

#### ツール定義

```json
{
  "name": "find_and_analyze",
  "description": "ファイル探索と解析を単一操作で実行する",
  "inputSchema": {
    "type": "object",
    "properties": {
      "roots": {"type": "array", "items": {"type": "string"}},
      "pattern": {"type": "string"},
      "extensions": {"type": "array", "items": {"type": "string"}},
      "query": {"type": "string", "description": "内容検索パターン"},
      "analyze_options": {
        "type": "object",
        "properties": {
          "include_scale": {"type": "boolean", "default": true},
          "include_structure": {"type": "boolean", "default": false},
          "max_files": {"type": "integer", "default": 10}
        }
      },
      "output_format": {"type": "string", "enum": ["json", "toon"], "default": "toon"}
    },
    "required": ["roots"]
  }
}
```

#### 対象ファイル

| ファイル | 変更内容 |
|---------|---------|
| `mcp/tools/find_analyze_tool.py` | 新規: 統合ツール |
| `mcp/server.py` | ツール登録追加 |

---

### 要件10: MCP パイプラインの実装 [Phase 4]

**ユーザーストーリー:** 開発者として、ツール実行の前処理・後処理を統一的に管理したい。これにより、共通処理の重複が排除され、一貫した動作が保証される。

**優先度:** ⭐⭐⭐⭐ (High)
**実装難易度:** 高
**期待効果:** 40-60% 削減
**リスク:** 中

#### 受け入れ基準

1. ツール要求を受信した場合、システムは前処理パイプライン（セキュリティ検証 / パス解決 / 言語検出 / キャッシュ参照）を実行しなければならない
2. 前処理が完了した場合、システムは拡張されたコンテキストをツールへ渡さなければならない
3. ツール実行が完了した場合、システムは後処理パイプライン（キャッシュ更新 / 出力形式変換 / メトリクス記録）を実行しなければならない
4. 前処理でキャッシュヒットした場合、システムはツール実行をスキップし、キャッシュ済み結果を返さなければならない
5. パイプラインが失敗した場合、システムは適切なエラー応答を返さなければならない

#### パイプラインフロー

```
クライアント要求
    ↓
┌─────────────────────────────────┐
│ 前処理パイプライン             │
│ 1. Quick Security Check         │
│ 2. Path Resolution              │
│ 3. Language Detection           │
│ 4. Cache Lookup                 │
└─────────────────────────────────┘
    ↓
ツール実行（共有コンテキスト付き）
    ↓
┌─────────────────────────────────┐
│ 後処理パイプライン             │
│ 1. Cache Update                 │
│ 2. Format Output                │
│ 3. Metrics Recording            │
└─────────────────────────────────┘
    ↓
応答
```

#### 対象ファイル

| ファイル | 変更内容 |
|---------|---------|
| `mcp/pipeline.py` | 新規: パイプライン実装 |
| `mcp/server.py` | パイプライン統合 |
| `mcp/tools/base_tool.py` | コンテキスト対応 |

---

### 要件11: ToolContext の実装 [Phase 4]

**ユーザーストーリー:** 開発者として、ツール間で共有されるコンテキストを統一管理したい。これにより、各ツールでの重複初期化が排除される。

**優先度:** ⭐⭐⭐ (Medium)
**実装難易度:** 中
**期待効果:** 15-25% 削減
**リスク:** 低

#### 受け入れ基準

1. ツールコンテキストが作成された場合、システムは共有コンポーネントを一度だけ初期化しなければならない
2. ツールが共有コンポーネントへアクセスする場合、システムは同一インスタンスを返さなければならない
3. プロジェクトパスが変更された場合、システムはコンテキスト内の全コンポーネントを更新しなければならない
4. コンテキストが破棄された場合、システムは全リソースを適切にクリーンアップしなければならない

#### コンテキスト構造

```python
@dataclass
class ToolContext:
    analysis_engine: UnifiedAnalysisEngine
    cache_service: CacheService
    security_validator: SecurityValidator
    path_resolver: PathResolver
    project_root: str | None
    precompute_manager: PrecomputeManager
    shared_cache: SharedToolCache
```

#### 対象ファイル

| ファイル | 変更内容 |
|---------|---------|
| `mcp/tools/tool_context.py` | 新規: コンテキスト管理 |
| `mcp/server.py` | コンテキスト初期化 |
| `mcp/tools/base_tool.py` | コンテキスト利用 |

---

### 要件12: リトライロジックの実装 [Phase 2]

**ユーザーストーリー:** 開発者として、一時的なエラー時に自動リトライしたい。ファイルアクセスエラーやタイムアウトなどの回復可能なエラーに対応する。

**優先度:** ⭐⭐⭐ (Medium)
**実装難易度:** 低
**期待効果:** 5-10% 削減
**リスク:** 低

#### 受け入れ基準

1. リトライ可能なエラーが発生した場合、システムは `max_retries` 回まで操作をリトライしなければならない
2. リトライする場合、システムは試行間に指数バックオフを使用しなければならない
3. すべてのリトライが失敗した場合、システムはリトライ情報を含めて最後のエラーを返さなければならない
4. リトライ不可能なエラーが発生した場合、システムはリトライせずに直ちに失敗しなければならない

#### リトライ対象エラー

| エラータイプ | リトライ | 理由 |
|-------------|---------|------|
| TimeoutError | ✅ | 一時的なリソース競合 |
| IOError | ✅ | ファイルシステムの一時的問題 |
| ConnectionError | ✅ | ネットワークの一時的問題 |
| ValueError | ❌ | 入力エラー、リトライ不要 |
| PermissionError | ❌ | 権限問題、リトライ不要 |

#### 対象ファイル

| ファイル | 変更内容 |
|---------|---------|
| `mcp/utils/retry.py` | 新規: リトライデコレータ |
| `mcp/tools/base_tool.py` | リトライ適用 |

---

### 要件13: 遅延評価システムの実装 [Phase 4]

**ユーザーストーリー:** 開発者として、高コストな計算を必要になるまで遅延したい。詳細分析が不要な場合の無駄な計算を防ぐ。

**優先度:** ⭐⭐⭐ (Medium)
**実装難易度:** 中
**期待効果:** 15-25% 削減
**リスク:** 低

#### 受け入れ基準

1. 基本メトリクスが要求された場合、システムは基本メトリクスのみを計算しなければならない
2. 詳細解析が要求された場合、システムは必要時に詳細解析を計算しなければならない
3. キャッシュ済み結果が存在する場合、システムは再計算せずにそれを返さなければならない
4. 部分結果で十分な場合、システムは残りのフィールドを計算してはならない

#### Lazy Fields

| フィールド | 計算コスト | 遅延評価 |
|-----------|-----------|---------|
| basic_metrics | 低 | ❌ |
| line_count | 低 | ❌ |
| element_summary | 中 | ✅ |
| detailed_elements | 高 | ✅ |
| complexity_analysis | 高 | ✅ |
| structural_overview | 高 | ✅ |

#### Implementation Files

| ファイル | 変更内容 |
|---------|---------|
| `mcp/lazy.py` | 新規: 遅延評価システム |
| `mcp/tools/analyze_scale_tool.py` | 遅延評価適用 |

---

## 成功指標

### 定量的指標

| 指標 | 現状 | Phase 1 目標 | Phase 2 目標 | Phase 3 目標 | Phase 4 目標 |
|------|------|-------------|-------------|-------------|-------------|
| ツール呼び出し回数/タスク | 5-8回 | 4-6回 | 3-5回 | 2-4回 | 2-3回 |
| 平均レスポンス時間 | 500-800ms | 400-700ms | 300-500ms | 200-400ms | 150-350ms |
| キャッシュヒット率 | 20-30% | 30-40% | 50-60% | 60-70% | 70-80% |
| 重複処理率 | 40-50% | 20-30% | 10-15% | 5-10% | <5% |

### 定性的指標

| 指標 | 目標 |
|------|------|
| コード保守性 | 重複コードの排除、単一責任原則の遵守 |
| 拡張性 | 新ツール追加時の共通基盤利用 |
| テスト容易性 | モック可能なコンポーネント分離 |
| ドキュメント | 各コンポーネントの役割と使用方法の明確化 |

### 検証方法

| 検証項目 | 方法 |
|---------|------|
| ツール呼び出し回数 | 実際のワークフローでの計測 |
| レスポンス時間 | PerformanceMonitor による計測 |
| キャッシュヒット率 | CacheService.get_stats() |
| 重複処理率 | コードカバレッジとプロファイリング |

---

## 後方互換性

### 原則

| 原則 | 説明 |
|------|------|
| **既存API維持** | 既存のツール定義は変更しない |
| **デフォルトは TOON** | MCP での既定出力は TOON とし、JSON は互換性/機械処理向けのオプションとして提供する |
| **段階的移行** | 既存コードを段階的に新アーキテクチャに移行 |
| **テスト互換性** | 既存テストがすべてパス |

### 実装要件

1. **既存ツール**: 入出力スキーマは変更しない（既定の出力形式は TOON のまま）
2. **新ツール**: 既存ツールと並行して動作し、既定出力は TOON とする
3. **出力形式の選択**: `output_format` は `"toon"` / `"json"` をサポートし、未指定時は `"toon"` とする
4. **キャッシュキー**: `output_format` に依存しない（同一分析結果を出力形式の違いで二重キャッシュ/二重計算しない）
5. **パイプライン**: 既存の直接呼び出しも引き続きサポート

---

## リスクと対策

### Risk 1: キャッシュ不整合

| 項目 | 内容 |
|------|------|
| **リスク** | ファイル変更時にキャッシュが古い状態のまま残る |
| **対策** | ファイルハッシュによる無効化、TTL 設定、明示的無効化 API |
| **モニタリング** | キャッシュヒット率と不整合検出率の監視 |

### Risk 2: 並列実行時の競合

| 項目 | 内容 |
|------|------|
| **リスク** | 複数スレッドが同時に同じリソースにアクセス |
| **対策** | スレッドセーフなキャッシュ実装、ロック機構 |
| **テスト** | 並行アクセステストの実施 |

### Risk 3: メモリ使用量増加

| 項目 | 内容 |
|------|------|
| **リスク** | キャッシュによるメモリ消費の増加 |
| **対策** | LRU キャッシュサイズの適切な設定、メモリ監視 |
| **目標** | メモリ増加 20% 未満 |

### Risk 4: 後方互換性の破壊

| 項目 | 内容 |
|------|------|
| **リスク** | 既存のクライアントコードが動作しなくなる |
| **対策** | 既存 API の維持、デプリケーション警告、移行ガイド |
| **検証** | 既存テストスイートの完全パス |

### Risk 5: 複雑性の増加

| 項目 | 内容 |
|------|------|
| **リスク** | 新しい抽象化レイヤーによるコード複雑性の増加 |
| **対策** | 明確な責任分離、包括的なドキュメント、コードレビュー |
| **目標** | 各コンポーネント 500 LOC 未満 |

---

## 優先度サマリー

| 優先度 | 要件 | フェーズ | 難易度 | 効果 |
|--------|------|---------|--------|------|
| ⭐⭐⭐⭐⭐ | 要件1: 重複セキュリティ検証排除 | Phase 1 | 低 | 10-15% |
| ⭐⭐⭐⭐⭐ | 要件2: 言語検出キャッシュ | Phase 1 | 低 | 5-10% |
| ⭐⭐⭐⭐ | 要件3: ファイルメトリクス統合 | Phase 1 | 低 | 5-10% |
| ⭐⭐⭐⭐⭐ | 要件4: SharedToolCache | Phase 2 | 中 | 20-30% |
| ⭐⭐⭐⭐ | 要件5: 事前計算マネージャー | Phase 2 | 中 | 15-20% |
| ⭐⭐⭐⭐⭐ | 要件6: バッチ分析ツール | Phase 3 | 中 | 50-70% |
| ⭐⭐⭐⭐ | 要件7: 並列実行エグゼキューター | Phase 3 | 中 | 30-50% |
| ⭐⭐⭐ | 要件8: 統一レスポンス構造 | Phase 2 | 中 | 10-15% |
| ⭐⭐⭐⭐ | 要件9: find_and_analyze 統合 | Phase 4 | 中 | 40-60% |
| ⭐⭐⭐⭐ | 要件10: MCP パイプライン | Phase 4 | 高 | 40-60% |
| ⭐⭐⭐ | 要件11: ToolContext | Phase 4 | 中 | 15-25% |
| ⭐⭐⭐ | 要件12: リトライロジック | Phase 2 | 低 | 5-10% |
| ⭐⭐⭐ | 要件13: 遅延評価システム | Phase 4 | 中 | 15-25% |

---

## アクションプラン

### Phase 1: 即座に実装可能（1-2日）

```
Day 1:
- [ ] 要件1: analyze_scale_tool.py の重複セキュリティ検証を削除
- [ ] 要件2: base_tool.py に言語検出キャッシュを追加

Day 2:
- [ ] 要件3: mcp/utils/file_metrics.py を新規作成
- [ ] 要件3: server.py と analyze_scale_tool.py から重複実装を削除
- [ ] テスト実行と検証
```

### Phase 2: 短期実装（3-5日）

```
Day 3-4:
- [ ] 要件4: mcp/utils/shared_cache.py を新規作成
- [ ] 要件4: 各ツールにキャッシュ利用を追加

Day 5-6:
- [ ] 要件5: mcp/precompute.py を新規作成
- [ ] 要件8: mcp/models/response.py を新規作成

Day 7:
- [ ] 要件12: mcp/utils/retry.py を新規作成
- [ ] テスト実行と検証
```

### Phase 3: 中期実装（1-2週間）

```
Week 1:
- [ ] 要件6: mcp/tools/batch_tool.py を新規作成
- [ ] 要件7: mcp/tools/parallel_executor.py を新規作成
- [ ] server.py にバッチツールを登録

Week 2:
- [ ] 統合テスト
- [ ] パフォーマンス計測
- [ ] ドキュメント作成
```

### Phase 4: 長期実装（2-4週間）

```
Week 3-4:
- [ ] 要件9: mcp/tools/find_analyze_tool.py を新規作成
- [ ] 要件10: mcp/pipeline.py を新規作成
- [ ] 要件11: mcp/tools/tool_context.py を新規作成

Week 5-6:
- [ ] 要件13: mcp/lazy.py を新規作成
- [ ] 全体統合テスト
- [ ] パフォーマンス最終検証
- [ ] ドキュメント完成
```

