compare-cache-runs

キャッシュ実行を比較する

クイックスタート

通常、2 つのキャッシュ実行 ID が提供されます。次の手順に従ってください。

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

ステップ 1：キャッシュ実行を特定する

base/head がキャッシュ実行 ID またはダッシュボード URL の場合

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

tuist cache-run show <base-id> --json
tuist cache-run show <head-id> --json

base/head がブランチ名の場合

各ブランチの最近のキャッシュ実行を一覧表示します。

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

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

デフォルト

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

ステップ 2：トップレベルの指標を比較する

両方のキャッシュ実行を取得したら、次の項目を比較します。

指標	確認する内容
duration	head が 10％を超えて遅い場合に警告します
status	base が成功し、head が失敗した場合に警告します
cacheable_targets	ターゲット数が変わったかを確認します
local_cache_target_hits	ローカルヒット数を比較します
remote_cache_target_hits	リモートヒット数を比較します
is_ci	片方が CI で、もう片方がローカルかを確認します

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

• Base：(local_hits + remote_hits) / cacheable_targets * 100
• Head：同じ式
• 差分：head_rate - base_rate

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

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

tuist cache でのキャッシュ無効化は、tuist generate と同じように機能します。

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

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

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

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

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

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

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

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

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

tuist cache では、次の点も考慮してください。

• キャッシュウォームアップ戦略：キャッシュ実行は最初からウォームアップしましたか、それとも段階的に行いましたか？
• command_arguments フィールドから、異なるフラグが使われたかどうかを確認できます。

まとめの形式

次の項目を含むまとめを作成します。

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

例：

Cache Run Comparison: base (run-123 on main) vs head (run-456 on feature-x)

Duration: 95.2s -> 142.8s (+50%) -- REGRESSION
Cache hit rate: 88% (44/50) -> 60% (30/50) (-28%) -- REGRESSION
Status: success -> success

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

Cache invalidation breakdown:
- Direct changes: CoreModule (sources changed)
- Cascade: UIKit, Networking, Analytics, + 11 others (dependency hash changed)

Recommendations:
- Consider splitting CoreModule into smaller, more focused modules
- Use interface/implementation module pattern for frequently-changed modules
- Run `tuist cache` on the feature branch after rebasing to warm caches

完了チェックリスト

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