analytics-flow

analytics-flow

説明：プロジェクト指標、ドキュメント分析、進捗追跡、傾向分析

カテゴリー：データ分析とレポート

複雑さ：中（データ集計＋可視化）

---

目的

プロジェクトの進捗、ドキュメントの品質、要件のカバレッジ、開発速度を可視化します。SDD 成果物から実用的なインサイトを生成し、ボトルネックを特定してワークフローを最適化します。

---

機能

1. ドキュメントカバレッジ指標

• 種類ごとのドキュメント総数（BRD、PRD、REQ、BDD など）
• トークン数の分布
• ドキュメントの完成度
• 古くなったドキュメントの特定
• ドキュメント負債の追跡

2. 要件の追跡

• カテゴリーごとの要件総数
• 要件のステータス（ドラフト、承認済み、実装済み、テスト済み）
• 要件カバレッジ（REQ → BDD → TASK のマッピング）
• 孤立した要件
• 要件の経過期間と陳腐化

3. トレーサビリティ分析

• 完全なトレーサビリティチェーン（BRD → ... → コード）
• 破損したトレーサビリティリンク
• トレーサビリティカバレッジ
• ギャップの特定
• 循環依存関係の検出

4. 実装の進捗

• 完了したタスク数と総タスク数
• 実装フェーズの進捗
• ブロック中のタスクと進行中のタスク
• スケジュールの遵守状況
• マイルストーンの追跡

5. 速度の追跡

• スプリント／週ごとに完了した要件数
• 実装速度
• ドキュメント作成速度
• テストカバレッジの伸び
• 時系列での傾向分析

6. 品質指標

• コードレビューのスコア推移
• テストカバレッジの傾向
• セキュリティ脆弱性の傾向
• コードの複雑さの傾向
• ドキュメント品質スコア

7. ボトルネックの特定

• 停滞している要件（進捗なし）
• ブロック中のタスク
• リソースの制約
• 進捗を妨げている依存関係チェーン
• レビューのボトルネック

8. カスタムレポートの生成

• エグゼクティブサマリー
• スプリント／週次レポート
• マイルストーンレポート
• チームパフォーマンスレポート
• リスク評価レポート

---

分析ワークフロー

graph TD
    A[SDD Artifacts] --> B[Data Collection]
    B --> C[Parse Documents]
    C --> D[Extract Metadata]

    D --> E[Requirement Analysis]
    D --> F[Traceability Analysis]
    D --> G[Progress Analysis]
    D --> H[Quality Analysis]

    E --> I[Requirement Metrics]
    F --> J[Traceability Matrix]
    G --> K[Progress Dashboard]
    H --> L[Quality Dashboard]

    I --> M[Aggregate Data]
    J --> M
    K --> M
    L --> M

    M --> N[Calculate KPIs]
    N --> O[Identify Trends]
    O --> P[Detect Anomalies]
    P --> Q[Generate Insights]

    Q --> R{Report Type}
    R -->|Executive| S[Executive Summary]
    R -->|Technical| T[Technical Report]
    R -->|Sprint| U[Sprint Report]

    S --> V[Distribute Reports]
    T --> V
    U --> V

---

使用方法

プロジェクトダッシュボードの生成

analytics-flow dashboard --output reports/dashboard.html

生成されるダッシュボードのセクション：

Project Overview Dashboard
==========================

Overall Health: 78/100 (Good)

Documentation Coverage:
├─ BRD Documents: 3/3 (100%) ✓
├─ PRD Documents: 2/3 (67%) ⚠️
├─ Requirements: 146/150 (97%) ✓
├─ BDD Scenarios: 89/146 (61%) ⚠️
├─ ADR Documents: 12/12 (100%) ✓
├─ SPEC Documents: 5/8 (63%) ⚠️
└─ TASK Documents: 45/89 (51%) ❌

Implementation Progress:
├─ Phase 1: 100% (Completed) ✓
├─ Phase 2: 75% (In Progress) →
├─ Phase 3: 0% (Not Started) ○
└─ Overall: 58% complete

Traceability Coverage:
├─ Forward Traceability: 94% ✓
├─ Backward Traceability: 91% ✓
└─ Complete Chains: 87% ✓

Quality Metrics:
├─ Code Coverage: 87% ✓
├─ Code Review Score: 82/100 ✓
├─ Security Issues: 3 (1 Critical) ⚠️
└─ Documentation Quality: 89% ✓

Velocity (Last 4 Weeks):
├─ Requirements: 12/week (avg)
├─ Implementation: 8 tasks/week
├─ Tests Written: 45 tests/week
└─ Trend: ↗ Improving

Bottlenecks Identified:
├─ REQ-AUTH-015: Stuck for 3 weeks
├─ BDD Scenarios: 39% gap vs requirements
└─ Phase 2 Dependency: Blocked by external API

要件レポートの生成

analytics-flow requirements --format json --output reports/requirements.json

出力：

{
  "summary": {
    "total_requirements": 146,
    "by_priority": {
      "MUST": 130,
      "SHOULD": 12,
      "MAY": 4
    },
    "by_status": {
      "draft": 5,
      "approved": 85,
      "implemented": 45,
      "tested": 38,
      "deployed": 30
    },
    "by_category": {
      "authentication": 15,
      "authorization": 12,
      "data_processing": 45,
      "api": 38,
      "ml_models": 32,
      "infrastructure": 4
    }
  },
  "coverage": {
    "with_bdd_scenarios": 89,
    "with_tasks": 78,
    "with_tests": 67,
    "complete_traceability": 127
  },
  "age_analysis": {
    "average_age_days": 45,
    "oldest_requirement": {
      "id": "REQ-AUTH-01",
      "age_days": 120,
      "status": "implemented"
    },
    "stale_requirements": [
      {"id": "REQ-ML-015", "age_days": 90, "status": "draft"}
    ]
  },
  "orphaned_requirements": [
    "REQ-AUTH-015",
    "REQ-DATA-023"
  ]
}

トレーサビリティマトリクスの生成

analytics-flow traceability --format mermaid --output reports/traceability.mmd

生成される Mermaid 図：

graph LR
    BRD001[BRD-SYSTEM-001] --> PRD001[PRD-FEATURES-001]
    PRD001 --> REQ001[REQ-AUTH-01]
    PRD001 --> REQ002[REQ-AUTH-002]

    REQ001 --> BDD001[BDD-LOGIN-001]
    REQ001 --> BDD002[BDD-LOGIN-002]
    REQ002 --> BDD003[BDD-LOGOUT-001]

    BDD001 --> TASK001[TASK-AUTH-001]
    BDD002 --> TASK002[TASK-AUTH-002]
    BDD003 --> TASK003[TASK-AUTH-003]

    TASK001 --> CODE001[auth/login.py]
    TASK002 --> CODE001
    TASK003 --> CODE002[auth/logout.py]

    CODE001 --> TEST001[test_login.py]
    CODE002 --> TEST002[test_logout.py]

    style BRD001 fill:#e1f5ff
    style PRD001 fill:#e8f5e9
    style REQ001 fill:#fff3e0
    style REQ002 fill:#fff3e0
    style BDD001 fill:#f3e5f5
    style BDD002 fill:#f3e5f5
    style BDD003 fill:#f3e5f5

スプリントレポートの生成

analytics-flow sprint \
  --start-date 2025-01-01 \
  --end-date 2025-01-14 \
  --output reports/sprint-report.md

生成されるレポート：

# Sprint Report: Jan 1-14, 2025

## Sprint Summary
- Duration: 2 weeks
- Team Size: 5 developers
- Sprint Goal: Complete Phase 2 authentication features

## Accomplishments
✓ Completed: 12 requirements
✓ Implemented: 18 tasks
✓ Tests Written: 67 tests
✓ Code Coverage: 87% → 91% (+4%)

## Requirements Completed
1. REQ-AUTH-01: User login with JWT ✓
2. REQ-AUTH-002: User logout ✓
3. REQ-AUTH-003: Password reset ✓
4. REQ-AUTH-004: Email verification ✓
... (8 more)

## Velocity Metrics
- Requirements: 6/week (target: 5/week) ↗
- Tasks: 9/week (target: 8/week) ↗
- Tests: 33.5/week (target: 25/week) ↗

## Quality Metrics
- Code Review Score: 85/100 (+3 from last sprint)
- Security Issues: 2 (down from 5)
- Test Coverage: 91% (up from 87%)

## Blockers Resolved
1. External API integration (blocked 5 days) → Resolved
2. Database migration issue → Resolved

## Current Blockers
1. Waiting for design review on user profile page (2 days)

## Risks
⚠️ Phase 3 dependency on external service (mitigation: mock implementation)

## Next Sprint Goals
- Complete remaining 8 authentication requirements
- Begin authorization framework
- Improve test coverage to 93%

速度の傾向を追跡

analytics-flow velocity --weeks 12 --output reports/velocity.json

傾向分析を含む出力：

{
  "period": "12 weeks",
  "metrics": [
    {
      "week": "2025-W01",
      "requirements_completed": 8,
      "tasks_completed": 15,
      "tests_written": 42,
      "code_coverage": 85
    },
    {
      "week": "2025-W02",
      "requirements_completed": 12,
      "tasks_completed": 18,
      "tests_written": 67,
      "code_coverage": 91
    }
  ],
  "trends": {
    "requirements": {
      "average": 10,
      "trend": "increasing",
      "velocity_change": "+15%"
    },
    "tasks": {
      "average": 16.5,
      "trend": "stable",
      "velocity_change": "+2%"
    },
    "tests": {
      "average": 54.5,
      "trend": "increasing",
      "velocity_change": "+25%"
    }
  },
  "forecast": {
    "next_sprint_requirements": 13,
    "completion_date_phase_2": "2025-02-15",
    "confidence": "high"
  }
}

---

主要業績評価指標（KPI）

ドキュメント KPI

1. ドキュメントカバレッジ

   Coverage = (Completed Documents / Total Required Documents) × 100%
   Target: ≥95%
   

2. ドキュメント負債

   Debt = Outdated Documents + Missing Documents
   Target: <5% of total documents
   

3. ドキュメントの平均経過期間

   Age = Days since last update
   Target: <30 days for active documents
   

要件 KPI

1. 要件カバレッジ

   Coverage = (Requirements with Tests / Total Requirements) × 100%
   Target: 100% for MUST requirements
   

2. 要件のサイクルタイム

   Cycle Time = Days from draft to deployed
   Target: <14 days (2 sprints)
   

3. 孤立した要件

   Orphaned = Requirements without forward/backward links
   Target: 0
   

実装 KPI

1. 実装速度

   Velocity = Tasks completed / Time period
   Track: Weekly, calculate 4-week moving average
   

2. タスク完了率

   Completion = (Completed Tasks / Total Tasks) × 100%
   Target: ≥90% per sprint
   

3. ブロック中のタスクの割合

   Blocked % = (Blocked Tasks / Active Tasks) × 100%
   Target: <10%
   

トレーサビリティ KPI

1. 前方トレーサビリティ

   Forward = (Requirements with downstream links / Total Requirements) × 100%
   Target: 100%
   

2. 後方トレーサビリティ

   Backward = (Tasks with upstream links / Total Tasks) × 100%
   Target: 100%
   

3. 完全なトレーサビリティチェーン

   Complete = (Requirements with full BRD→Code chain / Total) × 100%
   Target: ≥95%
   

品質 KPI

1. コードカバレッジの傾向

   Track: Weekly, target: ≥90%
   Alert: If drops >5% week-over-week
   

2. コードレビューのスコア

   Track: Per PR, target: ≥80/100
   Alert: If average <70 for 2 consecutive weeks
   

3. セキュリティ脆弱性密度

   Density = Critical vulnerabilities / KLOC
   Target: 0 critical vulnerabilities
   

---

レポートテンプレート

エグゼクティブサマリーのテンプレート

# Executive Project Summary
Date: {date}
Period: {period}

## Overall Status: {status_indicator}

### Progress
- Phase Completion: {phase_progress}%
- On Schedule: {schedule_status}
- Budget Status: {budget_status}

### Key Achievements
1. {achievement_1}
2. {achievement_2}
3. {achievement_3}

### Risks & Mitigation
| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| {risk_1} | {impact} | {prob} | {mitigation} |

### Next Milestone
- {milestone_name}: {milestone_date}
- {deliverables}

### Resource Requirements
- {resource_needs}

技術レポートのテンプレート

# Technical Project Report
Date: {date}

## Architecture
- ADRs Approved: {adr_count}
- Major Decisions: {decisions_summary}

## Implementation
- Requirements Completed: {req_completed}/{req_total}
- Code Coverage: {coverage}%
- Technical Debt: {tech_debt_score}

## Quality Metrics
- Code Review Score: {review_score}/100
- Security Issues: {security_count}
- Performance Benchmarks: {performance_data}

## Infrastructure
- Environments: {env_status}
- Deployments: {deployment_count}
- Uptime: {uptime}%

## Traceability
- Forward Coverage: {forward_trace}%
- Backward Coverage: {backward_trace}%
- Gaps: {gap_count}

---

データソース

主なソース

• すべての SDD 成果物ファイル（BRD、PRD、REQ、BDD、ADR、SPEC、TASK、CTR）
• Git のコミット履歴
• テスト実行結果
• コードカバレッジレポート
• セキュリティスキャン結果
• CI/CD パイプラインのログ

派生指標

• 速度の計算
• 傾向分析
• 予測
• 異常検知

---

可視化オプション

グラフの種類

1. バーンダウンチャート：スプリント／プロジェクトの進捗
2. 速度チャート：週ごとの実装速度
3. カバレッジの傾向：時間の経過に伴うテストカバレッジ
4. トレーサビリティマトリクス：要件とコードの対応付け
5. 依存関係グラフ：タスクの依存関係
6. リスクヒートマップ：リスクの発生確率と影響度
7. 品質ダッシュボード：複数の指標の可視化

エクスポート形式

• HTML ダッシュボード（インタラクティブ）
• PDF レポート（静的）
• JSON データ（連携用）
• Markdown レポート（Git 用）
• Mermaid 図（ドキュメント用）
• CSV データ（スプレッドシート用）

---

ツールアクセス

必須ツール：

• Read：すべての SDD アーティファクトを読み取ります
• Glob：すべてのドキュメントを検索します
• Grep：パターンと ID を検索します
• Bash：分析スクリプトを実行します

必須ライブラリ：

• pandas：データ分析
• matplotlib/plotly：可視化
• jinja2：レポートのテンプレート化
• pyyaml：YAML の解析

---

連携ポイント

doc-flow との連携

• 生成されたドキュメントからメタデータを抽出します
• ドキュメントのワークフローの進捗を追跡します
• ドキュメントの不足箇所を特定します

test-automation との連携

• テストカバレッジデータを集約します
• テスト実行の傾向を追跡します
• テストと要件を関連付けます

code-review との連携

• コード品質の傾向を追跡します
• レビューのスコアを集約します
• 品質パターンを特定します

project-mngt との連携

• スケジュールの遵守状況を検証します
• マイルストーンの進捗を追跡します
• リソース利用状況を分析します

---

ベストプラクティス

1. 更新頻度：毎日自動で収集し、週次レポートを作成します
2. ベースラインの設定：プロジェクト開始時にベースライン指標を設定します
3. 傾向分析：絶対値ではなく、傾向に注目します
4. 実行可能なインサイト：すべての指標が意思決定に役立つようにします
5. 異常検知：通常とは異なるパターンを検知したら通知します
6. 履歴データ：6 か月以上の履歴を保持します
7. ステークホルダーとの調整：対象者に応じてレポートをカスタマイズします
8. 継続的改善：フィードバックに基づいて指標を改善します

---

制限事項

1. SDD アーティファクトの構造に一貫性が必要です
2. 履歴分析の範囲は、利用可能なデータに限られます
3. 予測精度はデータ品質に依存します
4. 主観的な品質要因は測定できません
5. 精度を確保するには、定期的なデータ収集が必要です

---

成功基準

• ダッシュボードをリアルタイムで利用できること
• レポートの生成時間が 5 分未満であること
• データ精度が 100% であること
• すべての KPI が自動で追跡されること
• 予測精度 90% の傾向分析ができること
• 手動でのデータ収集が一切不要であること
• ステークホルダー満足度が 4/5 以上であること

---

注記

• レポートは reports/analytics/ に保存されます
• 履歴データは metrics/history.json に保存されます
• ダッシュボードは 15 分ごとに自動更新されます
• KPI のしきい値超過に対するアラートが設定されています
• カスタム指標は .analytics.yml で設定できます