xcode-build-orchestrator

Xcode ビルドオーケストレーター

エンドツーエンドの Xcode ビルド最適化に取り組む際は、このスキルを推奨される最初のエントリーポイントとして使用してください。

絶対遵守のルール

• 主な成功指標は、実際のビルド所要時間（開発者が待つ時間）です。提案にはすべて、開発者の実際の待ち時間への予想される影響を明記してください。
• まず提案モードで開始してください。
• 変更を加える前にベンチマークを実施してください。
• 開発者から明示的な承認を得ずに、プロジェクトファイル、ソースファイル、パッケージ、スクリプトを変更しないでください。
• すべての提案について、根拠となる記録を保持してください。
• 承認された変更を適用した後に再度ベンチマークを実施し、実際の所要時間の差を報告してください。

2 フェーズのワークフロー

このオーケストレーションは、開発者によるレビューを挟んだ 2 つの明確なフェーズで構成されています。

フェーズ 1 -- 分析（提案のみ）

このフェーズはエージェントモードで実行してください。エージェントはビルドの実行、ベンチマークスクリプトの実行、ベンチマーク成果物の作成、最適化レポートの生成を行う必要があるためです。ただし、フェーズ 1 は提案のみとして扱い、プロジェクトファイル、ソースファイル、パッケージ、ビルド設定は変更しないでください。このフェーズでエージェントが作成するファイルは、.build-benchmark/ 内のベンチマーク成果物と最適化計画のみです。

1. ビルド対象のコンテキストを収集します：ワークスペースまたはプロジェクト、スキーム、構成、デスティネーション、現在の問題点です。.xcworkspace と .xcodeproj の両方が存在する場合、ビルドに必要なサブプロジェクトがワークスペースに含まれていない限り、.xcodeproj を優先します。外部プロジェクトを参照するワークスペースは、それらのプロジェクトがチェックアウトされていないと失敗する場合があります。
2. 最新のベンチマークが存在しない場合は、xcode-build-benchmark を実行してベースラインを確立します。ベンチマークスクリプトは COMPILATION_CACHE_ENABLE_CACHING = YES を自動検出し、現実的な開発者エクスペリエンス（ウォームキャッシュ）を測定するキャッシュ済みクリーンビルドを含めます。ビルドのコンパイルに失敗する場合は、git log で最近のビルド可能なコミットを確認します。ワークツリーで作業している場合、ビルド可能な状態にするために、フィーチャーブランチから対象を絞ったビルド修正を cherry-pick してもかまいません。SPM パッケージが exclude: パスで gitignore 対象のディレクトリ（例：__Snapshots__）を参照している場合は、ビルド前にそのディレクトリを作成してください。ワークツリーには gitignore 対象のコンテンツが含まれず、そうしないと xcodebuild -resolvePackageDependencies がクラッシュします。
3. ベンチマーク成果物に空でない timing_summary_categories があることを確認します。空の場合、タイミングサマリーのパーサーが失敗した可能性があります。生ログを再解析するか、手動で確認してください。COMPILATION_CACHE_ENABLE_CACHING が有効な場合は、成果物に cached_clean の実行も含まれていることを確認します。
   • ベンチマークの信頼性チェック：各ビルドタイプ（クリーン、キャッシュ済みクリーン、インクリメンタル）について、最小値と最大値を比較します。範囲（最大値 - 最小値）が中央値の20％を超える場合、ベンチマークのばらつきが大きいと判断し、結論を出す前に追加の反復（5回以上）を実行するよう推奨します。ばらつきが大きいと、実際の改善とノイズを区別するのが困難になります。変更を適用した後は、変更後の中央値がベースラインの最小値〜最大値の範囲外にある場合に限り、改善があったと判断してください。
4. インクリメンタルビルドが主な問題点で、Xcode 16.4 以降が利用可能な場合は、開発者に Task Backtraces の有効化を推奨します（Scheme Editor > Build タブ > Build Debugging > "Task Backtraces"）。これにより各タスクが再実行された理由が明らかになり、予期しない再計画や入力の無効化を診断するうえで重要です。分析には Task Backtrace の証拠を含めてください。
5. コンパイルタスクが実時間での進行を妨げている可能性が高いのか、それとも並列 CPU 時間を消費しているだけなのかを判断します。タイミングサマリーのすべてのカテゴリの秒数の合計と、実時間の中央値を比較します。合計が中央値の2倍以上の場合、作業の大部分は並列化されており、コンパイルのホットスポット修正で待ち時間が短縮される可能性は低いです。SwiftCompile、CompileC、SwiftEmitModule、または Planning Swift module がタイミングサマリーの大部分を占め、かつクリティカルパス上にある可能性が高い場合は、diagnose_compilation.py を実行して型チェックのホットスポットを特定します。並列化されている場合も診断を実行しますが、調査結果には「ビルド時間の改善」ではなく「並列効率の改善」と記載してください。
6. 証拠に合った専門的な分析を、各スキルの SKILL.md を読み、そのワークフローを適用して実行します：
   • xcode-compilation-analyzer
   • xcode-project-analyzer
   • spm-build-analysis
7. 調査結果を、優先順位を付けた単一の改善計画にまとめます。
8. generate_optimization_report.py を使用して Markdown の最適化レポートを生成し、.build-benchmark/optimization-plan.md に保存します。このレポートには、ビルド設定の監査、タイミング分析、優先順位を付けた推奨事項、承認チェックリストが含まれます。
9. 作業を停止し、計画を開発者に提示してレビューを依頼します。

開発者は .build-benchmark/optimization-plan.md をレビューし、実施を希望する推奨事項の承認チェックボックスにチェックを入れてから、フェーズ2を開始します。

フェーズ 2 -- 実行と検証（エージェントモード）

開発者が計画の推奨事項を確認して承認した後、エージェントモードでこのフェーズを実行します。xcode-build-fixer の SKILL.md を読み、そのワークフローを適用して、すべての実装作業を委任してください。

10. .build-benchmark/optimization-plan.md を読み、承認チェックリストから承認済みの項目を特定します。
11. 承認済みの計画を添えて xcode-build-fixer に引き継ぎます。フィクサーは承認された変更をそれぞれ適用し、コンパイルを検証して、再度ベンチマークを行います。
12. 最適化計画に検証結果を追記します。変更後の中央値、絶対値とパーセンテージの差、および信頼性に関する注記を記載します。
13. 変更前後の結果と、残っている改善機会を報告します。

優先順位付けのルール

開発者がビルド完了を待つ時間を短縮することが目標です。

1. 開発者にとっての主な課題（クリーンビルド、インクリメンタルビルド、またはその両方）と、測定した実時間の中央値を特定します。
2. 実時間の進行を妨げている可能性が高い要因を判断します。
   • タイミングサマリーの全カテゴリの秒数の合計が実時間の中央値の 2 倍以上なら、作業の大部分は並列化されています。コンパイルのホットスポットを修正しても、待ち時間は短縮されない可能性が高いです。
   • 直列実行されるカテゴリ（例：PhaseScriptExecution、CompileAssetCatalog、CodeSign）のいずれかが実時間の大きな割合を占める場合、それが実際のボトルネックです。
   • Planning Swift module または SwiftEmitModule がインクリメンタルビルドの大部分を占める場合、原因は個々のファイルのコンパイル速度ではなく、無効化またはモジュールサイズである可能性が高いです。
3. 累積タスク削減量ではなく、実時間の短縮が見込める量に基づいて推奨事項を順位付けします。
4. ソースレベルのコンパイル修正は、証拠からクリティカルパス上にあると判断できる場合を除き、プロジェクト／グラフ／設定の修正より上位にしないでください。

測定可能で、元に戻せる、リスクの低い変更を優先します。

推奨事項の影響に関する表現

開発者に提示するすべての推奨事項には、以下の影響に関する表現のいずれかを含める必要があります。

• 「クリーン／インクリメンタルビルドを約 X 秒短縮できる見込みです。」
• 「並列コンパイルの作業量は減りますが、他のタスクにも同程度の時間がかかるため、ビルドの待ち時間は短縮されない可能性が高いです。」
• 「待ち時間への影響は不確実です。適用後に再度ベンチマークして確認してください。」
• 「待ち時間の短縮は見込めません。メリットは [決定論的なビルド／ブランチ切り替えの高速化／CI コストの削減] です。」
• COMPILATION_CACHE_ENABLE_CACHING については、必ず次の文言を使用してください。「テストしたプロジェクトでは、クリーンビルドが 5～14% 高速化することを測定しました。キャッシュがビルド間で維持される実際のワークフローでは、ブランチ切り替え、変更の取り込み、DerivedData を保持する CI などで、このメリットが積み重なります。」

累積タスク時間の削減量を、影響の主な説明として使用しないでください。変更によって並列コンパイルの作業が 5 秒分減っても、別の同程度の時間がかかるタスクが残るなら、開発者の待ち時間は変わりません。

承認ゲート

何かを実装する前に、以下を含む簡潔な承認リストを提示します。

• 推奨事項の名称
• 予想される待ち時間への影響（上記の影響に関する表現を使用）
• 根拠の要約
• 影響を受けるファイルまたは設定
• リスクが低、中、高のいずれか

開発者から明示的な承認が得られるまで待ちます。

承認後の実行

承認後、xcode-build-fixer に委任します。

• フィクサーは承認された項目のみを実装します。
• 変更は一括して適用し、対象範囲を限定します。
• 元の推奨計画から逸脱した場合は、その内容を記録します。
• 同じベンチマーク条件でフィクサーが再ベンチマークを行います。

最終レポート

まず、実時間の結果を平易な言葉で示します。例：「クリーンビルドが 86 秒から 82 秒になり、4 秒短縮されました。」その後、次の内容を記載します。

• ベースラインのクリーンビルドとインクリメンタルビルドの実時間中央値
• 変更後のクリーンビルドとインクリメンタルビルドの実時間中央値
• 実時間の絶対差と変化率
• 変更した内容
• 意図的に変更しなかった内容
• ノイズのため明確な結論を出せない場合の信頼度に関する注記。ベンチマークのばらつきが大きい場合（最小値から最大値までの幅が中央値の 20％を超える場合）は、ノイズのある数値を確定的な改善または悪化として提示せず、その旨を明記してください
• 累積タスク指標は改善したものの、実時間が改善しなかった場合は、次のように明記します：「コンパイラーの作業量は減りましたが、ビルドの待ち時間は改善していません。Xcode がこれらのタスクを、同程度の所要時間を要する他の作業と並行して実行する場合、これは想定どおりです。」
• コミュニティの結果報告にそのまま貼り付けられる行と、PR を作成するためのリンク（レポートテンプレートを参照）

推奨コマンドパス

python3 scripts/benchmark_builds.py \
  --project App.xcodeproj \
  --scheme MyApp \
  --configuration Debug \
  --destination "platform=iOS Simulator,name=iPhone 16" \
  --output-dir .build-benchmark

macOS アプリでは --destination "platform=macOS" を使用します。watchOS では --destination "platform=watchOS Simulator,name=Apple Watch Series 10" を使用します。tvOS では --destination "platform=tvOS Simulator,name=Apple TV" を使用します。スキームのデフォルトを使用する場合は、--destination を省略します。

変更のないビルドではなく、実際のインクリメンタルビルド（ファイルに変更を加えて再ビルド）を測定するには、--touch-file path/to/SomeFile.swift を追加します。

コンパイル診断

python3 scripts/diagnose_compilation.py \
  --project App.xcodeproj \
  --scheme MyApp \
  --configuration Debug \
  --destination "platform=iOS Simulator,name=iPhone 16" \
  --threshold 100 \
  --output-dir .build-benchmark

最適化レポート

python3 scripts/generate_optimization_report.py \
  --benchmark .build-benchmark/<artifact>.json \
  --project-path App.xcodeproj \
  --diagnostics .build-benchmark/<diagnostics>.json \
  --output .build-benchmark/optimization-plan.md

追加リソース

• レポートテンプレートについては、references/orchestration-report-template.md を参照してください
• ベンチマーク成果物の要件については、references/benchmark-artifacts.md を参照してください
• 推奨事項の形式については、references/recommendation-format.md を参照してください
• ビルド設定のベストプラクティスについては、references/build-settings-best-practices.md を参照してください