Xcode Build Orchestrator

このスキルを、Xcode ビルド最適化の全体的なエンドツーエンドワークフローのための推奨優先的なエントリーポイントとして使用します。

譲歩できないルール

• 実際のビルド時間（開発者が待つ時間）が主要な成功指標です。すべての推奨事項は、開発者の実際の待機時間に対する予想される影響を明記する必要があります。
• 推奨モードで開始します。
• 変更を加える前にベンチマークを実行します。
• 開発者の明示的な承認なしに、プロジェクトファイル、ソースファイル、パッケージ、またはスクリプトを修正しません。
• すべての推奨事項に対して証拠の追跡を保存します。
• 承認された変更の後に再度ベンチマークを実行し、実際のビルド時間の差分を報告します。

2フェーズワークフロー

オーケストレーションは、開発者のレビューによって分離された 2 つの異なるフェーズとして設計されています。

フェーズ 1 -- 分析（推奨のみ）

エージェントはビルドを実行し、ベンチマークスクリプトを実行し、ベンチマークアーティファクトを書き込み、最適化レポートを生成する必要があるため、このフェーズをエージェントモードで実行します。ただし、フェーズ 1 を推奨のみとして扱います。プロジェクトファイル、ソースファイル、パッケージ、またはビルド設定を修正しません。このフェーズ中にエージェントが作成する唯一のファイルは、ベンチマークアーティファクトと .build-benchmark/ 内の最適化計画です。

1. ビルドターゲットコンテキストを収集します。ワークスペースまたはプロジェクト、スキーム、設定、デスティネーション、および現在の課題。.xcworkspace と .xcodeproj の両方が存在する場合は、ワークスペースが必須のサブプロジェクトを含まない限り .xcodeproj を優先します。外部プロジェクトを参照するワークスペースは、それらのプロジェクトがチェックアウトされていない場合は失敗する可能性があります。
2. 新しいベンチマークがない場合は、xcode-build-benchmark を実行してベースラインを確立します。ベンチマークスクリプトは COMPILATION_CACHE_ENABLE_CACHING = YES を自動検出し、キャッシュされたクリーンビルドを含みます。これは現実的な開発者体験（ウォームキャッシュ）を測定します。ビルドがコンパイルに失敗する場合は、git log で最近のビルド可能なコミットを確認します。ワークツリーで作業している場合は、フィーチャーブランチから対象となるビルド修正をチェリーピックして、ビルド可能な状態に到達することは許容可能です。SPM パッケージが exclude: パスで gitignored ディレクトリを参照している場合（例：__Snapshots__）は、ビルド前にそれらのディレクトリを作成します。ワークツリーは gitignored コンテンツを含まず、xcodebuild -resolvePackageDependencies がそれ以外の場合はクラッシュします。
3. ベンチマークアーティファクトに空でない timing_summary_categories があることを確認します。空の場合は、タイミングサマリーパーサーが失敗している可能性があります。生ログを再解析するか、手動で確認します。COMPILATION_CACHE_ENABLE_CACHING が有効になっている場合は、アーティファクトに cached_clean 実行が含まれていることも確認します。
   • ベンチマーク信頼度チェック：各ビルドタイプ（クリーン、キャッシュクリーン、増分）について、最小値と最大値を比較します。スプレッド（最大値 - 最小値）が中央値の 20% を超える場合は、ベンチマークを高分散としてフラグを付けて、結論を引き出す前に追加の繰り返し（5 回以上）を実行することを推奨します。高分散では、実際の改善をノイズから区別することが困難になります。変更を適用した後、ポスト変更の中央値がベースラインの最小値～最大値の範囲外に該当する場合のみ改善を主張します。
4. 増分ビルドが主要な課題で Xcode 16.4 以上が利用可能な場合は、開発者にタスクバックトレースを有効にすることをお勧めします（スキームエディタ > ビルドタブ > ビルドデバッグ > 「タスクバックトレース」）。これは各タスクが再実行された理由を明らかにします。これは予期しない再計画または入力無効化の診断に重要です。分析にタスクバックトレース証拠を含めます。
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 を使用してマークダウン最適化レポートを生成し、.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 に委譲します：

• 修正プログラムは承認された項目のみを実装します。
• 変更は原子的に適用され、スコープを保たれます。
• 元の推奨事項計画からの偏差は注記されます。
• 修正プログラムは同じベンチマーク契約で再度ベンチマークを実行します。

最終レポート

実際のビルド時間の結果をわかりやすい言語で始めます。例：「クリーンビルドは現在 82 秒かかります（86 秒でした）。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 を参照してください。