# ギャップ分析プロセス

## 目的
要件と既存コードベースのギャップを分析し、実装戦略の決定に情報を提供する。

## 分析フレームワーク

### 1. 現状調査

- ドメイン関連アセットをスキャン:
  - 主要ファイル/モジュールとディレクトリレイアウト
  - 再利用可能なコンポーネント/サービス/ユーティリティ
  - 支配的なアーキテクチャパターンと制約

- 規約を抽出:
  - 命名、レイヤリング、依存方向
  - インポート/エクスポートパターンと依存ホットスポット
  - テストの配置とアプローチ

- 統合サーフェスを記録:
  - データモデル/スキーマ、APIクライアント、認証メカニズム

### 2. 要件実現可能性分析

- EARS要件から技術的ニーズをリストアップ:
  - データモデル、API/サービス、UI/コンポーネント
  - ビジネスルール/バリデーション
  - 非機能要件: セキュリティ、パフォーマンス、スケーラビリティ、信頼性

- ギャップと制約を特定:
  - 現在のコードベースに欠けている機能
  - 後で調査が必要な未知項目（「要調査」としてマーク）
  - 既存アーキテクチャとパターンからの制約

- 複雑さのシグナルを記録:
  - シンプルなCRUD / アルゴリズムロジック / ワークフロー / 外部統合

### 3. 実装アプローチオプション

#### オプションA: 既存コンポーネントの拡張
**検討する場合**: 機能が既存構造に自然にフィットする

- **拡張するファイル/モジュール**:
  - 変更が必要な具体的ファイルを特定
  - 既存機能への影響を評価
  - 後方互換性の懸念を評価

- **互換性評価**:
  - 拡張が既存インターフェースを尊重しているか確認
  - 消費者への破壊的変更がないか検証
  - テストカバレッジへの影響を評価

- **複雑さと保守性**:
  - 追加機能の認知負荷を評価
  - 単一責任原則が維持されているか確認
  - ファイルサイズが管理可能な範囲か評価

**トレードオフ**:
- ✅ 新規ファイル最小、初期開発が速い
- ✅ 既存パターンとインフラを活用
- ❌ 既存コンポーネントの肥大化リスク
- ❌ 既存ロジックが複雑化する可能性

#### オプションB: 新規コンポーネントの作成
**検討する場合**: 機能が明確な責任を持つ、または既存コンポーネントが既に複雑

- **新規作成の根拠**:
  - 関心の明確な分離が新規ファイルを正当化
  - 既存コンポーネントが既に複雑
  - 機能が異なるライフサイクルや依存関係を持つ

- **統合ポイント**:
  - 新コンポーネントが既存システムにどう接続するか
  - 公開するAPIまたはインターフェース
  - 既存コンポーネントへの依存

- **責任境界**:
  - 新コンポーネントが所有するものの明確な定義
  - 既存コンポーネントとのインターフェース
  - データフローと制御フロー

**トレードオフ**:
- ✅ 関心のクリーンな分離
- ✅ 分離したテストが容易
- ✅ 既存コンポーネントの複雑さを軽減
- ❌ ナビゲートするファイルが増加
- ❌ 慎重なインターフェース設計が必要

#### オプションC: ハイブリッドアプローチ
**検討する場合**: 拡張と新規作成の両方が必要な複雑な機能

- **組み合わせ戦略**:
  - どの部分が既存コンポーネントを拡張するか
  - どの部分が新規コンポーネントを必要とするか
  - 相互作用の方法

- **段階的実装**:
  - 初期フェーズ: 最小限の実行可能な変更
  - 後続フェーズ: リファクタリングまたは新規コンポーネント
  - 必要に応じた移行戦略

- **リスク軽減**:
  - 段階的ロールアウトアプローチ
  - フィーチャーフラグまたは設定
  - ロールバック戦略

**トレードオフ**:
- ✅ 複雑な機能に対するバランスの取れたアプローチ
- ✅ 反復的な改善が可能
- ❌ より複雑な計画が必要
- ❌ 適切に調整されないと不整合の可能性

### 4. ギャップ分析のスコープ外

- 深い調査活動は設計フェーズに延期する
- 未知項目は簡潔な「要調査」項目としてのみ記録

### 5. 実装の複雑さとリスク

  - 工数:
    - B（1〜3日）: 既存パターン、最小限の依存、簡単な統合
    - A（3〜7日）: いくつかの新パターン/統合、中程度の複雑さ
    - S（1〜2週間）: 重要な機能、複数の統合またはワークフロー
    - SS（2週間以上）: アーキテクチャ変更、未知の技術、広範な影響
  - リスク:
    - 高: 未知の技術、複雑な統合、アーキテクチャシフト、不明確なパフォーマンス/セキュリティパス
    - 中: ガイダンス付きの新パターン、管理可能な統合、既知のパフォーマンスソリューション
    - 低: 確立されたパターンの拡張、馴染みのある技術、明確なスコープ、最小限の統合

### 出力チェックリスト

- ギャップがタグ付けされた要件-アセットマップ（欠落 / 未知 / 制約）
- 短い根拠とトレードオフ付きのオプションA/B/C
- 工数（S/M/L/XL）とリスク（高/中/低）、各1行の正当化
- 設計フェーズへの推奨事項:
  - 推奨アプローチと主要な決定事項
  - 引き継ぐ調査項目

## 原則

- **決定より情報**: 分析とオプションを提供し、最終決定はしない
- **複数の実行可能オプション**: 該当する場合、信頼できる代替案を提示
- **明示的なギャップと仮定**: 未知項目と制約を明確にフラグ
- **コンテキスト認識**: 既存パターンとアーキテクチャ制限に合わせる
- **透明な工数とリスク**: ラベルを簡潔に正当化