gap-analysis

ギャップ分析

包括的な比較、分析、ギャップの特定を通じて、文書化された要件、仕様、実際の実装の間にある相違を体系的に特定し、システムの完全性と正確性を高めます。

使用するタイミング

次のような場合に、このスキルを使用します。

• 要件ドキュメントはあるものの、実装状況が不明確な場合
• 仕様が変更されたにもかかわらず、ドキュメントが更新されていない場合
• 対応するドキュメントの更新を伴わずにコードが変更された場合
• 監査、コンプライアンスチェック、品質評価の準備をする場合
• システムを正確に把握する必要がある新しいチームメンバーを受け入れる場合
• リファクタリングやモダナイゼーションの取り組みを計画する場合
• 実装が設計意図と一致しているか検証する場合
• ドキュメント化されていない機能に関する技術的負債を特定する場合
• 文書化されていない動作によるリスクを評価する場合

できること

1. ドキュメント分析

• さまざまなドキュメント形式を解析（Markdown、YAML、JSON、Confluence、Google Docs のエクスポート）
• 構造化テキストと非構造化テキストから要件と仕様を抽出
• 文書化された機能、制約、動作を特定
• 要件を種類別に分類（機能、非機能、ビジネス、技術）
• ドキュメントの品質を評価（完全性、明確さ、一貫性、最新性）

2. 実装分析

• ソースコードを分析して、実装された機能と動作を特定
• API コントラクトとインターフェースを調査して、公開されている機能を確認
• データベーススキーマとデータモデルを確認して、永続化される構造を把握
• 設定ファイルを調査して、システムの動作設定を確認
• デプロイ成果物を分析して、ランタイムの特性を把握

3. ギャップの特定

• 文書化された機能と実装済みの機能を比較して、不一致を特定
• 文書化されていない実装を検出（ドキュメントのない機能）
• 未実装のドキュメントを特定（文書化されているが構築されていない機能）
• 動作の相違を検出（文書化された動作と実際の動作の違い）
• 実装が元の仕様から逸脱した箇所で、仕様の乖離を発見

4. ギャップの分類と優先順位付け

• ギャップを種類別に分類（欠落、不完全、誤り、古い情報）
• ギャップの重大度を評価（重大、高、中、低）
• 各ギャップへの対処に必要な工数を見積もり
• 影響、リスク、工数に基づいてギャップに優先順位を付ける
• 関連するギャップをグループ化して、効率よく解決

5. 推奨事項と修正計画

• 特定した不一致ごとに、ギャップ解消の推奨事項を生成
• 実行可能な手順を含む修正計画を作成
• 実装との整合性を取るためのドキュメント更新を提案
• ドキュメントに合わせるための実装変更を提案
• ギャップの解消を確認する検証戦略を策定

分析手法

ドキュメント解析パターン

document_sources:
  requirements:
    patterns:
      - "As a [role], I want [feature] so that [benefit]"
      - "The system shall [requirement]"
      - "Must support [capability]"
      - "Should be able to [action]"
  
  specifications:
    patterns:
      - "### Feature: [name]"
      - "**Specification:** [details]"
      - "| Parameter | Type | Required | Description |"
      - "API endpoint: [method] [path]"
  
  architecture:
    patterns:
      - "Component: [name]"
      - "Responsibility: [description]"
      - "Interfaces: [list]"
      - "Data flow: [description]"

コード分析のアプローチ

def analyze_implementation(codebase_path):
    """
    Analyze code implementation for features and behaviors.
    """
    features = extract_features_from_code(codebase_path)
    apis = extract_api_endpoints(codebase_path)
    data_models = extract_data_models(codebase_path)
    configs = parse_configuration_files(codebase_path)
    
    return {
        'implemented_features': features,
        'api_endpoints': apis,
        'data_models': data_models,
        'configurations': configs,
        'behavioral_patterns': extract_behavioral_patterns(codebase_path)
    }

ギャップ検出アルゴリズム

class GapAnalyzer:
    def detect_gaps(self, documented, implemented):
        """
        Detect gaps between documented and implemented items.
        """
        gaps = {
            'undocumented_implementations': [],
            'unimplemented_documentation': [],
            'behavioral_mismatches': [],
            'specification_drift': []
        }
        
        # Find undocumented implementations
        for impl_item in implemented:
            if not self.is_documented(impl_item, documented):
                gaps['undocumented_implementations'].append(impl_item)
        
        # Find unimplemented documentation
        for doc_item in documented:
            if not self.is_implemented(doc_item, implemented):
                gaps['unimplemented_documentation'].append(doc_item)
        
        # Find behavioral mismatches
        for doc_item in documented:
            impl_item = self.find_matching_implementation(doc_item, implemented)
            if impl_item and not self.behaviors_match(doc_item, impl_item):
                gaps['behavioral_mismatches'].append({
                    'documented': doc_item,
                    'implemented': impl_item,
                    'differences': self.find_differences(doc_item, impl_item)
                })
        
        return gaps

ギャップの種類

1. ドキュメントの欠落

症状：機能はコードに存在するものの、ドキュメントがありません
影響：知識のサイロ化、保守の困難、新メンバーの受け入れにかかる時間の増加
例：API エンドポイントが実装されているものの、API ドキュメントに記載されていない

2. 実装の欠落

症状：文書化された機能がコード内に見つかりません
影響：期待に応えられない、約束が守られない、顧客の不満
例：「PDF へのエクスポート」が文書化されているものの、実装されていない

3. 動作の不一致

症状：ドキュメントの説明と実装の動作が異なります
影響：バグ、統合の問題、予期しない動作
例：ドキュメントでは「大文字と小文字を区別しない検索」と記載されているものの、実装では大文字と小文字が区別される

4. 古いドキュメント

症状：ドキュメントに非推奨の機能や古いインターフェースが記載されています
影響：混乱、誤った使用、開発時間の浪費
例：ドキュメントでは古い API バージョン 1.0 が示されているものの、実装は 2.0 である

5. 不完全なドキュメント

症状：ドキュメントは存在しますが、重要な詳細が不足しています 影響：理解が不完全になり、推測に頼ることや実装エラーにつながります 例：API は文書化されていますが、エラーレスポンスやレート制限の記載がありません

6. 過剰に詳細なドキュメント

症状：ドキュメントに、実装には反映されていない詳細が記載されています 影響：実装の柔軟性が低下し、保守の負担が増加します 例：ドキュメントには特定のアルゴリズムが記載されていますが、実装では異なる方法が使われています

例

# Analyze gaps between requirements docs and implementation
npm run gap-analysis:analyze -- --requirements requirements.md --code src/ --output gaps.json

# Compare API documentation with actual implementation
npm run gap-analysis:compare -- --api-docs api.md --code src/api/ --output api-gaps.yaml

# Identify undocumented features
npm run gap-analysis:undocumented -- --code src/ --docs docs/ --output undocumented-features.md

# Check for unimplemented requirements
npm run gap-analysis:unimplemented -- --requirements specs/ --code src/ --output missing-features.json

# Generate remediation plan
npm run gap-analysis:remediate -- --gaps gaps.json --output remediation-plan.md

# Continuous gap monitoring
npm run gap-analysis:monitor -- --watch --requirements docs/ --code src/ --alert-on-gap

出力形式

ギャップ分析レポート：

Gap Analysis Report
───────────────────
System: User Management Service
Analysis Date: 2026-02-26
Documents Analyzed: 3 (requirements.md, api-spec.yaml, architecture.md)
Code Analyzed: 42 files, 8,567 lines

Summary:
✅ Documented & Implemented: 28 features (70%)
⚠️  Documented but Not Implemented: 6 features (15%)
⚠️  Implemented but Not Documented: 4 features (10%)
❌ Behavioral Mismatches: 2 features (5%)

Gap Details:

1. CRITICAL: Missing Implementation
   • Feature: "User password reset via email"
   • Location: requirements.md:45
   • Impact: Security feature missing
   • Effort: Medium (3-5 days)
   • Recommendation: Implement password reset flow

2. HIGH: Missing Documentation
   • Feature: "User session invalidation on role change"
   • Location: src/auth/session.js:123
   • Impact: Undocumented security behavior
   • Effort: Low (2 hours)
   • Recommendation: Document in security.md

3. MEDIUM: Behavioral Mismatch
   • Documented: "Search returns max 100 results"
   • Implemented: "Search returns max 50 results"
   • Location: api.md:89 vs src/search.js:45
   • Impact: Performance vs functionality tradeoff
   • Effort: Low (configuration change)
   • Recommendation: Align implementation with docs or update docs

4. LOW: Outdated Documentation
   • Documented: "API version 1.2"
   • Implemented: "API version 2.0"
   • Location: api.md:1 (header)
   • Impact: Confusion for API consumers
   • Effort: Low (documentation update)
   • Recommendation: Update API documentation

Priority Matrix:
┌─────────────┬─────────┬─────────┬──────────────┐
│ Priority    │ Count   │ Effort  │ Risk         │
├─────────────┼─────────┼─────────┼──────────────┤
│ Critical    │ 1       │ 3-5 days│ Security     │
│ High        │ 2       │ 1 day   │ Compliance   │
│ Medium      │ 3       │ 2 days  │ User Experience│
│ Low         │ 6       │ 3 days  │ Maintenance  │
└─────────────┴─────────┴─────────┴──────────────┘

Remediation Plan:
1. Week 1: Address critical security gap (password reset)
2. Week 2: Document undocumented security features
3. Week 3: Align behavioral mismatches
4. Week 4: Update outdated documentation
5. Ongoing: Implement gap monitoring to prevent recurrence

ギャップ分析の JSON 出力：

{
  "analysis": {
    "system": "user-management",
    "timestamp": "2026-02-26T19:00:00Z",
    "documents_analyzed": ["requirements.md", "api-spec.yaml"],
    "code_analyzed": ["src/", "lib/"],
    "summary": {
      "total_features": 40,
      "documented_and_implemented": 28,
      "documented_not_implemented": 6,
      "implemented_not_documented": 4,
      "behavioral_mismatches": 2,
      "gap_percentage": 30
    }
  },
  "gaps": [
    {
      "id": "gap-001",
      "type": "missing_implementation",
      "severity": "critical",
      "description": "User password reset via email not implemented",
      "document_reference": "requirements.md:45",
      "code_reference": null,
      "impact": "Security feature missing, violates compliance requirements",
      "effort_estimate": "3-5 days",
      "recommendation": "Implement password reset flow with email verification",
      "owner": "security-team",
      "due_date": "2026-03-05"
    },
    {
      "id": "gap-002",
      "type": "missing_documentation",
      "severity": "high",
      "description": "User session invalidation on role change not documented",
      "document_reference": null,
      "code_reference": "src/auth/session.js:123",
      "impact": "Undocumented security behavior, audit finding risk",
      "effort_estimate": "2 hours",
      "recommendation": "Add to security documentation and API docs",
      "owner": "documentation-team",
      "due_date": "2026-03-01"
    }
  ],
  "remediation_plan": {
    "phases": [
      {
        "phase": 1,
        "name": "Critical Security Gaps",
        "duration": "1 week",
        "gaps": ["gap-001"],
        "deliverables": ["Password reset implementation", "Security review"]
      },
      {
        "phase": 2,
        "name": "Documentation Cleanup",
        "duration": "1 week",
        "gaps": ["gap-002"],
        "deliverables": ["Updated security docs", "API documentation"]
      }
    ],
    "total_effort": "2 weeks",
    "priority_order": ["gap-001", "gap-002"],
    "success_criteria": ["All critical gaps closed", "Documentation coverage > 90%"]
  }
}

ギャップ監視ダッシュボード：

Gap Monitoring Dashboard
────────────────────────
Status: ACTIVE
Last Analysis: 2026-02-26 19:00:00
Next Analysis: 2026-02-27 07:00:00

Trends:
┌──────────────────────────────────────┐
│ Gap Trend (Last 30 Days)            │
│                                      │
│ 40 ┤                                │
│    │                                │
│ 30 ┤                █               │
│    │               █ █              │
│ 20 ┤              █   █             │
│    │             █     █            │
│ 10 ┤           █       █           │
│    │          █         █          │
│  0 ┼───────────█─────────█─────────│
│     1   5   10   15   20   25   30 │
│              Days                  │
└──────────────────────────────────────┘

Current Gaps by Type:
• Missing Documentation: 4 (33%)
• Missing Implementation: 3 (25%)
• Behavioral Mismatch: 3 (25%)
• Outdated Documentation: 2 (17%)

Gap Age Distribution:
• < 1 week: 6 gaps
• 1-4 weeks: 4 gaps
• 1-3 months: 2 gaps
• > 3 months: 0 gaps

Alert Status:
✅ No critical gaps
⚠️  2 high-priority gaps aging > 2 weeks
✅ Documentation coverage: 85%
✅ Implementation coverage: 90%

Recommended Actions:
1. Address 2 high-priority gaps aging > 2 weeks
2. Improve documentation for 4 undocumented features
3. Schedule review for 3 behavioral mismatches

注記

• ギャップ分析は責任追及の場ではありません — 責任を追及するのではなく、システムの改善に注力してください
• 定期的なギャップ分析で蓄積を防げます — 大規模で頻度の低い分析より、小規模で頻繁な分析が効果的です
• 可能な限り自動化してください — 継続的にギャップを検出することで、問題を早期に発見できます
• 関係者を巻き込んでください — 開発者、プロダクトマネージャー、テクニカルライターが協力してギャップの解消に取り組む必要があります
• 影響に基づいて優先順位を付けてください — すべてのギャップが同じ重要度とは限りません
• ギャップの解消状況を追跡してください — 時間の経過に伴うギャップ削減の進捗を測定してください
• ギャップ分析を先を見越して活用してください — 問題の検出だけでなく、品質の改善にも活用してください
• 開発ワークフローに組み込んでください — ギャップ分析の結果を計画と優先順位付けに反映させてください
• 分析プロセスを文書化してください — 繰り返し実施し、改善できるようにしてください
• ギャップの削減を称えましょう — システムの完全性と正確性の向上を評価してください