drift-analysis

ドリフト分析

プロジェクトの状態を分析し、計画のずれを検出して、優先順位を付けた再構築計画を作成するための知識とパターンです。

アーキテクチャの概要

/drift-detect
        │
        ├─→ collectors.js (pure JavaScript)
        │   ├─ scanGitHubState()
        │   ├─ analyzeDocumentation()
        │   └─ scanCodebase()
        │
        └─→ plan-synthesizer (Opus)
            └─ Deep semantic analysis with full context

データ収集：純粋な JavaScript（LLM によるオーバーヘッドなし） セマンティック分析：完全なコンテキストを用いた Opus の単一呼び出し

ドリフト検出パターン

ドリフトの種類

計画のドリフト：文書化された計画と実際の実装が乖離している状態です

• PLAN.md の項目が長期間未完了のままになっている
• ロードマップのマイルストーンが更新されずに遅れている
• スプリントやフェーズの目標がコードの変更に反映されていない

ドキュメントのドリフト：ドキュメントの更新が実装に追いついていない状態です

• 対応するドキュメントがない新機能が存在する
• README に存在しない機能が記載されている
• API ドキュメントが実際のエンドポイントと一致しない

イシューのドリフト：イシュートラッキングが現状と乖離している状態です

• すでに当てはまらない古いイシュー
• 完了した作業に対応するイシューが未クローズ
• 優先度の高い項目が放置されている

スコープのドリフト：プロジェクトのスコープが当初の計画を超えて拡大している状態です

• 提供可能な数を超える機能が文書化されている
• 完了しないまま継続的に追加されている
• 整理されずに増え続けるバックログ

検出シグナル

HIGH-CONFIDENCE DRIFT INDICATORS:
- Milestone 30+ days overdue with open issues
- PLAN.md < 30% completion after 90 days
- 5+ high-priority issues stale > 60 days
- README features not found in codebase

MEDIUM-CONFIDENCE INDICATORS:
- Documentation files unchanged for 180+ days
- Draft PRs open > 30 days
- Issue themes don't match code activity
- Large gap between documented and implemented features

LOW-CONFIDENCE INDICATORS:
- Many TODOs in codebase
- Stale dependencies
- Old git branches not merged

優先順位付けのフレームワーク

優先度の計算

function calculatePriority(item, weights) {
  let score = 0;

  // Severity base score
  const severityScores = {
    critical: 15,
    high: 10,
    medium: 5,
    low: 2
  };
  score += severityScores[item.severity] || 5;

  // Category multiplier
  const categoryWeights = {
    security: 2.0,    // Security issues get 2x
    bugs: 1.5,        // Bugs get 1.5x
    infrastructure: 1.3,
    features: 1.0,
    documentation: 0.8
  };
  score *= categoryWeights[item.category] || 1.0;

  // Recency boost
  if (item.createdRecently) score *= 1.2;

  // Stale penalty (old items slightly deprioritized)
  if (item.daysStale > 180) score *= 0.9;

  return Math.round(score);
}

期間バケットのしきい値

バケット	条件	最大項目数
即時	severity=critical OR priority >= 15	5
短期	severity=high OR priority >= 10	10
中期	priority >= 5	15
バックログ	その他すべて	20

優先度の重み（デフォルト）

security: 10     # Security issues always top priority
bugs: 8          # Bugs affect users directly
features: 5      # New functionality
documentation: 3 # Important but not urgent
tech-debt: 4     # Keeps codebase healthy

相互参照パターン

ドキュメントとコードの照合

// Fuzzy matching for feature names
function featureMatch(docFeature, codeFeature) {
  const normalize = s => s
    .toLowerCase()
    .replace(/[-_\s]+/g, '')
    .replace(/s$/, ''); // Remove trailing 's'

  const docNorm = normalize(docFeature);
  const codeNorm = normalize(codeFeature);

  return docNorm.includes(codeNorm) ||
         codeNorm.includes(docNorm) ||
         levenshteinDistance(docNorm, codeNorm) < 3;
}

よくある不一致

ドキュメント上の表記	実装上の表記
"ユーザー認証"	auth/, login/, session/
"API エンドポイント"	routes/, api/, handlers/
"データベースモデル"	models/, entities/, schemas/
"キャッシュレイヤー"	cache/, redis/, memcache/
"ロギングシステム"	logger/, logs/, telemetry/

出力テンプレート

ドリフトレポートのセクション

## Drift Analysis

### {drift_type}
**Severity**: {severity}
**Detected In**: {source}

{description}

**Evidence**:
{evidence_items}

**Recommendation**: {recommendation}

ギャップレポートのセクション

## Gap: {gap_title}

**Category**: {category}
**Severity**: {severity}

{description}

**Impact**: {impact_description}

**To Address**:
1. {action_item_1}
2. {action_item_2}

再構築計画のセクション

## Reconstruction Plan

### Immediate Actions (This Week)
{immediate_items_numbered}

### Short-Term (This Month)
{short_term_items_numbered}

### Medium-Term (This Quarter)
{medium_term_items_numbered}

### Backlog
{backlog_items_numbered}

ベストプラクティス

ドリフトを分析する際

1. 内容だけでなくタイムスタンプを比較する

   • ドキュメントの最終更新とコードの最終変更はそれぞれいつですか？
   • マイルストーンの日付は現実的ですか？

2. 個々の項目ではなくパターンを探す

   • 古いイシューが1件あるだけではドリフトではありません。古いイシューが10件あればパターンです
   • ドキュメント化されていない機能が1つあるだけではドリフトではありません。5つあればドリフトです

3. コンテキストを考慮する

   • 開発が活発なプロジェクトでは、ある程度のドリフトは自然に発生します
   • 成熟したプロジェクトでは、ドリフトを最小限に抑えるべきです
   • リリース後のプロジェクトでは、ドキュメントの更新が遅れがちです

4. 影響度に応じて重み付けする

   • ユーザー向けのドリフトは、内部向けのものより重要です
   • 公開 API のドリフトは、実装の詳細より重要です

計画を作成する際

1. 網羅性より実行可能性を重視する

   • 上位50項目ではなく、即時対応が必要な上位5項目を選びます
   • 各項目は妥当な時間内に完了できるものにします

2. 関連項目をグループ化する

   • 「ログインページのドキュメントを更新」と「サインアップのドキュメントを更新」ではなく、「認証ドキュメントを更新」とします

3. 成功基準を含める

   • このドリフト項目が解消されたことを、どのように確認できますか？

4. カテゴリのバランスを取る

   • セキュリティは最優先ですが、それ以外をすべて無視しないでください
   • すぐに成果が出る作業と重要な作業を組み合わせます

データ収集（JavaScript）

collectors.js モジュールは、LLM によるオーバーヘッドなしでデータを抽出します。

GitHub データ

• ラベル別に分類されたオープンイシュー
• ドラフト状態を含むオープン PR
• 期限付きのマイルストーン
• 長期間更新されていない項目（90日以上非アクティブ）
• タイトルからのテーマ分析

ドキュメントデータ

• 解析済みの README、PLAN.md、CLAUDE.md、CHANGELOG.md
• チェックボックスの完了数
• セクション分析
• 機能リスト

コードデータ

• ディレクトリ構造
• フレームワークの検出
• テストフレームワークの有無
• ヘルス指標（CI、リンティング、テスト）

セマンティック分析（Opus）

plan-synthesizer は、収集したすべてのデータを受け取り、以下を実行します。

1. 相互参照：ドキュメントに記載された機能を実装と照合します
2. ドリフトの特定：乖離のパターンを見つけます
3. ギャップ分析：不足しているものを特定します
4. 優先順位付け：コンテキストを考慮して順位付けします
5. レポート生成：実行可能な推奨事項を提示します

入力／出力の例

収集されたデータ（collectors.js から）

{
  "github": {
    "issues": [...],
    "categorized": { "bugs": [...], "features": [...] },
    "stale": [...]
  },
  "docs": {
    "files": { "README.md": {...}, "PLAN.md": {...} },
    "checkboxes": { "total": 15, "checked": 3 }
  },
  "code": {
    "frameworks": ["Express"],
    "health": { "hasTests": true, "hasCi": true }
  }
}

分析結果（plan-synthesizer から）

# Reality Check Report

## Executive Summary
Project has moderate drift: 8 stale priority issues and 20% plan completion.
Strong code health (tests + CI) but documentation lags implementation.

## Drift Analysis
### Priority Neglect
**Severity**: high
8 high-priority issues inactive for 60+ days...

## Prioritized Plan
### Immediate
1. Close #45 (already implemented)
2. Update README API section...