compare-generations

世代を比較する

クイックスタート

通常、2 つの世代 ID が提供されます。以下の手順に従ってください。

1. tuist generate list --json を実行して、各ブランチの世代を確認します。
2. ベース世代とヘッド世代の両方について、tuist generate show <id> --json を実行します。
3. 所要時間、ステータス、キャッシュヒット率を比較します。
4. 根本原因を分析し、キャッシュの変化を要約します。

ステップ 1：世代を特定する

ベース／ヘッドが世代 ID またはダッシュボード URL の場合

それぞれを直接取得します。

tuist generate show <base-id> --json
tuist generate show <head-id> --json

ベース／ヘッドがブランチ名の場合

各ブランチの最近の世代を一覧表示します。

tuist generate list --git-branch <base-branch> --json --page-size 1
tuist generate list --git-branch <head-branch> --json --page-size 1

次に、tuist generate show <id> --json で詳細を取得します。

デフォルト

• ベースが指定されていない場合は、プロジェクトのデフォルトブランチ（通常は main）を使用します。
• ヘッドが指定されていない場合は、現在の Git ブランチを検出します。

ステップ 2：最上位のメトリクスを比較する

両方の世代を取得したら、次の項目を比較します。

メトリクス	確認する内容
duration	ヘッドが 10％を超えて遅い場合にフラグを付けます
status	ベースが成功し、ヘッドが失敗した場合にフラグを付けます
cacheable_targets	ターゲット数が変化したか確認します
local_cache_target_hits	ローカルヒット数を比較します
remote_cache_target_hits	リモートヒット数を比較します
is_ci	どちらかが CI で、もう一方がローカルか確認します

キャッシュヒット率を計算します。

• ベース：(local_hits + remote_hits) / cacheable_targets * 100
• ヘッド：同じ計算式
• 差分：head_rate - base_rate

ステップ 3：キャッシュ無効化を分析する

キャッシュヒット率が低下した場合、重要なのはどのターゲットが無効化の連鎖を引き起こしたかです。

キャッシュ無効化は通常、次のように発生します。

1. 「根本原因」となるターゲットに直接変更が加えられます（ソースファイルの変更、ビルド設定の変更など）。
2. 根本原因となるターゲットに依存するすべてのターゲットも、dependencies ハッシュが変化するため無効化されます。
3. この連鎖により、1 つの根本的な変更から多くのターゲットが無効化されることがあります。

根本原因となるターゲットの特定

モジュールキャッシュのターゲット詳細エンドポイント（MCP 経由で利用可能）がない場合は、次のヒューリスティックを使用します。

1. ベースコミットとヘッドコミットの間で git diff を確認し、変更されたファイルを特定します。
2. 変更されたファイルを Tuist のターゲット／モジュールに対応付けます。
3. ソースに直接変更があったターゲットが、根本原因である可能性が高いです。
4. 依存関係ハッシュの連鎖によってのみ変更されたターゲットは、二次的な無効化です。

キャッシュ無効化の一般的な根本原因

原因	説明
ソースの変更	ターゲットのソースディレクトリ内のファイルが変更されました
リソースの変更	アセット、XIB、ストーリーボード、またはその他のリソースが変更されました
ビルド設定	ターゲットまたはプロジェクトのビルド設定が変更されました
依存関係の変更	外部依存関係のバージョンが変更されました
Info.plist の変更	ターゲットの Info.plist が変更されました
Entitlements の変更	Entitlements ファイルが変更されました
デプロイメントターゲット	最小デプロイメントターゲットが変更されました
ヘッダー	パブリックヘッダーまたはプロジェクトヘッダーが変更されました
プロジェクト設定	プロジェクトレベルの共有設定が変更されました

ステップ 4：影響を評価する

キャッシュの無効化を分類します。

• 想定内：ソースファイルが意図的に変更され、想定どおりキャッシュミスが発生しました。
• 想定外：ソースの変更がないのにキャッシュが無効化されました（ビルド設定、Xcode のバージョンなど）。
• 連鎖：小さな変更によって、多数の下流ターゲットが無効化されました。

要約の形式

次の項目を含む要約を作成します。

1. 全体的な評価：キャッシュヒット率が改善、悪化、または安定したか。
2. キャッシュヒット率：ベースの率とヘッドの率、および差分。
3. 所要時間：絶対値と変化率。
4. 根本原因となるターゲット：直接変更されたターゲット。
5. 連鎖の影響：依存関係の連鎖によって無効化されたターゲットの数。
6. 推奨事項：キャッシュ無効化を最小限に抑える方法。

例：

Generation Comparison: base (gen-123 on main) vs head (gen-456 on feature-x)

Duration: 12.5s -> 28.3s (+126%) -- REGRESSION
Cache hit rate: 92% (46/50) -> 64% (32/50) (-28%) -- REGRESSION
Status: success -> success

Root cause: FoundationModule had source changes (3 files modified).
This cascaded to 14 downstream targets that depend on FoundationModule.

Cache invalidation breakdown:
- Direct changes: FoundationModule (sources changed)
- Cascade: NetworkModule, AuthModule, UIModule, + 11 others (dependency hash changed)

Recommendations:
- Consider splitting FoundationModule into smaller modules to reduce cascade impact
- The 14 cascaded targets could benefit from more granular dependency declarations
- If FoundationModule changes frequently, consider interface/implementation module splitting

完了チェックリスト

• ベース世代とヘッド世代の両方を特定した
• 所要時間とキャッシュヒット率を比較した
• キャッシュ無効化の根本原因となるターゲットを特定した
• 連鎖の影響を分析した
• キャッシュミスを減らすための実行可能な推奨事項を提示した