compare-gradle-builds

Gradle ビルドを比較する

クイックスタート

通常、2 つのビルド識別子（ID、ダッシュボード URL、またはブランチ名）が提供されます。Tuist MCP ツールを使って、次の手順に従ってください。

1. list_gradle_builds を使って、各ブランチのビルドを見つけます。
2. ベースビルドとヘッドビルドの両方について、get_gradle_build を使います。
3. list_gradle_build_tasks を使って、両方のビルドのタスク単位の詳細を取得します。
4. 実行時間、ステータス、キャッシュヒット率、タスクの結果を比較します。
5. リグレッション、改善点、推奨事項をまとめます。

識別子が 1 つだけ提供された場合は、プロジェクトのデフォルトブランチをベースラインとして使います。

ステップ 1：ビルドを特定する

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

get_gradle_build(build_run_id: "<id>") を使って、それぞれを直接取得します。

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

各ブランチの最近のビルドを一覧表示し、最新のものを選びます。

list_gradle_builds(account_handle: "...", project_handle: "...", git_branch: "<branch>", page_size: 1)

次に、get_gradle_build(build_run_id: "<id>") を使って詳細を取得します。

デフォルト

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

ステップ 2：トップレベルのメトリクスを比較する

両方のビルドを取得した後、次の項目を比較します。

メトリクス	確認事項
duration_ms	ヘッドがベースより 10% 超遅い場合は指摘します
status	ベースが成功し、ヘッドが失敗した場合は指摘します
tasks_local_hit_count	ローカルキャッシュのヒット数を比較します
tasks_remote_hit_count	リモートキャッシュのヒット数を比較します
tasks_executed_count	実行されたタスク数を比較します（数が多いほどキャッシュミスが多いことを意味します）
cacheable_tasks_count	キャッシュ可能なタスク数に変化があったか確認します
cache_hit_rate	(local_hits + remote_hits) / cacheable_tasks_count * 100
requested_tasks	公平に比較できるよう、両方のビルドで同じタスクが実行されたことを確認します
gradle_version / java_version	比較可能性に影響する環境の違いを確認します

キャッシュミスの差分を計算します：base_executed - head_executed。正の値はヘッドでの実行数が少ないこと（改善）を意味します。負の値はリグレッションを意味します。

ステップ 3：タスクを詳しく調べる

両方のビルドで list_gradle_build_tasks を使います。各タスクパスの duration_ms と outcome を比較します。

次の点を確認します。

• local_hit または remote_hit から executed に変わったタスク（キャッシュの無効化）。
• executed から local_hit または remote_hit に変わったタスク（キャッシュの改善）。
• failed に変わったタスク（新たな失敗）。
• ヘッドビルドに新たに現れたタスク。
• 実行時間が大幅に増加したタスク。

絶対時間差で並べ替えて、最も大きなリグレッションを見つけます。

タスクのフィルタリング

outcome フィルターを使って、特定のタスク状態に絞り込みます。

• list_gradle_build_tasks(build_run_id: "<id>", outcome: "executed") で、実行されたタスクのみを表示します。
• list_gradle_build_tasks(build_run_id: "<id>", outcome: "failed") で、失敗したタスクを表示します。
• list_gradle_build_tasks(build_run_id: "<id>", cacheable: true) で、キャッシュ可能なタスクのみを表示します。

ステップ 4：実行時間のリグレッションを調査する

ヘッドビルドが大幅に遅い場合は、次の点を確認します。

1. requested_tasks に違いがあるか確認します（タスクセットが異なる場合、直接比較できません）。
2. キャッシュヒット率が低下していないか確認します。低下していれば、ビルド時間が長くなった理由を説明できる可能性があります。
3. キャッシュヒットから executed に変わったタスクを探します。
4. パフォーマンスに影響する可能性があるため、gradle_version または java_version が変わっていないか確認します。
5. 個々のタスクの実行時間を比較し、影響が最も大きいものを見つけます。

ステップ 5：キャッシュの変更を調査する

タスク単位のキャッシュ動作を比較します。

• ヒット率が低下：依存関係の変更、ビルド設定の変更、またはキャッシュキーを変える Gradle のバージョン更新が原因として考えられます。
• ヒット率が向上：キャッシュの事前ウォームアップが改善されたか、ソースの変更が減ったことが原因と考えられます。
• タスク数が変化：新しいモジュールやタスクが追加または削除されています。
• 結果が変化：タスクが up_to_date、local_hit、remote_hit、executed の間で移動しているかどうかから、キャッシュの有効性が分かります。

ステップ 6：ビルドコンテキストを確認する

環境の詳細を比較します。

• gradle_version と java_version：バージョンが異なると、ビルド時間やキャッシュの有効性に影響することがあります。
• is_ci：CI ビルドとローカルビルドでは、パフォーマンス特性が異なる場合があります。
• git_branch と git_commit_sha：ビルドが想定どおりのコミットから実行されていることを確認します。
• root_project_name：両方のビルドが同じプロジェクト構造で実行されていることを確認します。

まとめの形式

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

1. 全体的な評価：ベースと比べて改善、悪化、または変化なし。
2. 所要時間：duration_ms の絶対値と割合の変化。
3. キャッシュヒット率：ヒット率の変化とその説明。
4. タスクの結果：注目すべき結果の変化（ヒットから実行への変化、新たな失敗など）。
5. ステータス：ステータスの変化（成功から失敗、またはその逆）。
6. 環境：比較に影響する環境の違い。
7. 推奨事項：調査結果に基づく具体的な次の手順。

例：

Build Comparison: base (abc123 on main) vs head (def456 on feature-x)

Duration: 45200ms -> 62800ms (+39%) -- REGRESSION
Cache hit rate: 85% -> 72% (-13%) -- 8 tasks went from cache hit to executed
Status: success -> success

Root cause: Cache hit rate dropped because 8 tasks had invalidated caches.
The :app:compileKotlin task changed from remote_hit to executed,
cascading to 7 downstream tasks.

Recommendations:
- Investigate which source changes invalidated :app:compileKotlin cache
- Consider splitting large modules to reduce cache invalidation cascading

完了チェックリスト

• ベースとヘッドの両方のビルドを解決した
• 所要時間、キャッシュ、ステータスの指標を比較した
• 両方のビルドについてタスクレベルの結果を詳しく調査した
• リグレッションの根本原因を特定した
• 実行可能な推奨事項を提示した