Xcode Build Fixer

このスキルを使用して、承認済みのビルド最適化の変更を実装し、ベンチマークで検証します。

コアルール

• 開発者から明示的に承認された変更のみを適用します。
• 1回に1つの論理的な修正を適用して、変更がレビュー可能で元に戻せるようにします。
• 変更適用後に再ベンチマークを実行して、改善を検証します。
• 何が変わったか、どのファイルに触れたか、測定されたデルタを正確に報告します。
• 変更が改善をもたらさないか、回帰を引き起こす場合は、直ちにフラグを立てます。

入力

フィクサーは以下のいずれかを想定しています：

• 承認チェックボックスがチェックされた .build-benchmark/optimization-plan.md の承認済み最適化計画
• 適用する修正を説明する明示的な開発者指示 (例：「Debug 向けに DEBUG_INFORMATION_FORMAT を dwarf に設定」)

最適化計画から作業する場合は、承認チェックリストを読み、チェックされた項目のみを実装します。

修正カテゴリ

ビルド設定

project.pbxproj の値を build-settings-best-practices.md の推奨に一致するように変更します。

一般的な修正：

• Debug 向けに DEBUG_INFORMATION_FORMAT = dwarf を設定
• Debug 向けに SWIFT_COMPILATION_MODE = singlefile を設定
• COMPILATION_CACHE_ENABLE_CACHING = YES を有効化
• Debug 向けに EAGER_LINKING = YES を有効化
• クロスターゲット設定を調整してモジュールの変異を排除

project.pbxproj を編集するときは、ターゲット名と設定名を一致させることで正しい buildSettings ブロックを見つけます。適用後、xcodebuild -showBuildSettings で変更を検証します。

スクリプトフェーズ

インクリメンタルビルドまたはデバッグビルド中に時間を浪費するスクリプトフェーズを修正します。

一般的な修正：

• 入力および出力ファイル宣言を追加して、Xcode が変更されていないスクリプトをスキップできるようにします。
• 設定ガードを追加：リリースのみのスクリプトの場合は [[ "$CONFIGURATION" != "Release" ]] && exit 0
• リストが長い場合は、入力/出力リストを .xcfilelist ファイルに移動します。
• 入力と出力が宣言されている場合は、「Based on dependency analysis」を有効化します。

ソースレベルのコンパイル修正

型チェッカーとコンパイラのオーバーヘッドを削減するコード変更を適用します。references/fix-patterns.md で修正パターンの前後を参照してください。

一般的な修正：

• 複雑な式に明示的な型アノテーションを追加
• 長いチェーンされたネストされた式を中間の型付き変数に分割
• サブクラス化されていないクラスに final マークを付ける
• 内部専用シンボルのアクセス制御（private/fileprivate）を厳格化
• モノリシックな SwiftUI body プロパティを小さい構成サブビューに抽出
• 深くネストされた結果ビルダーコードを別の型付きヘルパーに置き換える
• ジェネリック関数に渡されるクロージャーに明示的な戻り型を追加

SPM リストラクチャリング

Swift パッケージを再構成して、ビルドの並列化を改善し、リビルドスコープを削減します。

一般的な修正：

• 循環または上方向の依存関係を排除するために、共有型を下層モジュールに移動
• 機能領域ごとに巨大なモジュール（200ファイル以上）を分割
• プロトコル定義を軽量なインターフェースモジュールに抽出
• 不要な @_exported import の使用を削除
• 同じパッケージをインポートするターゲット間でビルドオプションを調整して、モジュールの変異の重複を防止
• ブランチ追跡依存関係をタグ付きバージョンまたはコミットハッシュにピンして、決定論的な解決を実現

バージョンピン変更を適用する前に：

• git ls-remote --tags <url> を実行してタグが存在することを確認します。アップストリームにタグがない場合は、代わりに特定のリビジョンハッシュにピンします。
• xcodebuild -resolvePackageDependencies でピンされたバージョンが正常に解決されることを確認してから進めます。

実行ワークフロー

1. 承認された最適化計画または開発者指示を読みます。
2. 承認された各項目について、変更する正確なファイルと場所を特定します。
3. 変更を適用します。
4. 変更がコンパイルされることを検証します：クイック xcodebuild build を実行してエラーが導入されていないことを確認します。
5. 承認されたすべての変更を適用した後、元のベースラインと同じ入力を使用して再ベンチマークします：

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

6. 変更後の中央値とベースラインを比較してデルタを報告します。

回帰の評価

遅い数値がすべて真の回帰とは限りません。フィクサーは推奨する前に全体像を評価する必要があります。

コンパイルキャッシングのトレードオフ

COMPILATION_CACHE_ENABLE_CACHING = YES のような変更は、標準的なクリーンビルドをわずかに遅くすることもありますが（キャッシュ生成オーバーヘッド）、キャッシュされたクリーンビルドを大幅に高速化します。キャッシュされたクリーンビルドは現実的な開発者ワークフロー（ブランチ切り替え、変更のプル、ウォームキャッシュを使用したクリーンビルドフォルダ）を反映しているため、標準的なクリーンビルドが遅い場合でもキャッシュされたクリーンビルドが速い場合は回帰ではなく純改善です。同じロジックが、初回コストが高いが後続ビルドが利益を得る変更にも適用されます。

すべてのビルドタイプを比較

標準クリーン、キャッシュされたクリーン（利用可能な場合）、インクリメンタルビルドを一緒に評価します。変更は、開発者の日常的なワークフロー関連のメトリクスを悪化させた場合のみ明確な回帰です。コールドスタートクリーンビルドのみが遅い場合でも、開発者が真の冷たいビルドをめったにしない場合は、受け入れ可能な場合があります。

変更ごとか累積か

単一の変更は単独では回帰する可能性がありますが、より大きな累積改善を実現する場合は保持する価値があります。（例：コンパイルキャッシングの有効化は1つのビルドタイプを遅くしますが、他のすべてのキャッシュ利点をアンロック）

ベストプラクティス設定は復帰の候補ではありません

一部のビルド設定は Apple の推奨される最新のデフォルトです。これらは、直後のベンチマークが測定可能な改善を示しているかどうかに関わらず、適用および保持する必要があります。これらは推測的な最適化ではありません -- プロジェクトを Apple のツールチェーンの方向に合わせており、将来の Xcode リリースで値が複合されます。フィクサーは単一のベンチマーク結果に基づいてこれらの設定の復帰を推奨してはいけません。

適用後に常に保持する必要があるベストプラクティス設定：

• COMPILATION_CACHE_ENABLE_CACHING = YES -- Apple はこれに積極的に投資しており、キャッシュは Xcode リリースごとに改善され、実際のワークフロー間で複合します
• EAGER_LINKING = YES (Debug) -- リンカーがコンパイルと重複することを可能にします
• SWIFT_USE_INTEGRATED_DRIVER = YES -- プロセス間スケジューリングオーバーヘッドを排除
• DEBUG_INFORMATION_FORMAT = dwarf (Debug) -- 不要な dSYM 生成を回避
• SWIFT_COMPILATION_MODE = singlefile (Debug) -- インクリメンタル再コンパイル
• ONLY_ACTIVE_ARCH = YES (Debug) -- ローカルですべてのアーキテクチャをビルドする理由はありません

これらの設定について報告するときは、次のような言語を使用します：「推奨ビルド設定を適用。直後のベンチマーク改善は測定されませんでしたが、これは Apple の推奨構成に合わせており、将来の Xcode 改善の基盤となります。」

復帰を推奨するタイミング（推測的な変更のみ）

ベストプラクティス設定ではない変更（ソースリファクタリング、リンケージ実験、スクリプトフェーズの変更、依存関係リストラクチャリング）の場合：

• 累積パスが測定されたすべてのビルドタイプ（標準クリーン、キャッシュされたクリーン、インクリメンタル）全体でウォールクロック回帰を示している場合は、開発者が非パフォーマンスの理由で特定の項目を保持するよう明示的に求めない限り、すべての推測的な変更の復帰を推奨します。
• 個別の推測的な変更ごと：中央値改善が見られず、キャッシュされた/インクリメンタル利点もない場合は、Recommend revert と測定されたデルタでフラグを立てます。
• 「外れ値削減のみ」（最悪の場合は改善されたが中央値ではない）と「中央値改善」（改善された一般的な開発者待機時間）を区別します。
• 変更が1つのビルドタイプをトレードオフする場合（標準クリーンは遅いがキャッシュされたクリーンは速い）、両方の数値を明確に提示して開発者が決定できるようにします。フレーミング：「標準クリーンビルドは X.Xs 遅くなりますが、キャッシュされたクリーンビルド（現実的な日常的ワークフロー）は Y.Ys 高速化されます。」

報告

プレーンな言語でウォールクロック結果をリードします：

「クリーンビルドは X.Xs（Y.Ys でした）-- Z.Zs 高速化」 「インクリメンタルビルドは X.Xs（Y.Ys でした）-- Z.Zs 高速化」

次に以下を含めます：

• 変更後のクリーンビルドウォールクロック中央値
• 変更後のインクリメンタルビルドウォールクロック中央値
• 両方の絶対値およびパーセンテージウォールクロックデルタ
• ベンチマークノイズが高い場合は信頼度ノート
• 修正ごとに変更されたファイルのリスト
• 元の推奨からの逸脱

累積タスクメトリクスが改善されたがウォールクロックが改善されなかった場合は、プレーンに述べます：「コンパイラワークロードは減少しましたが、ビルド待機時間は改善されませんでした。これは Xcode がこれらのタスクを他の同等の長さの作業と並列に実行する場合に予想されます。」

修正が測定可能なウォールタイム改善をもたらさない場合は、No measurable wall-time improvement と注記し、保持するか（コード品質のため）復帰するかを提案します。

非ベンチマーク理由で価値のある変更（決定論的なパッケージ解決、ブランチ切り替えキャッシング）については、ラベル：「この変更からウォイト時間改善は期待されません。メリットは [決定論的ビルド / ブランチ切り替え高速化 / CI コスト削減] です。」

注：COMPILATION_CACHE_ENABLE_CACHING はテスト対象のプロジェクト（87～1,991 Swift ファイル）全体で 5～14% の高速クリーンビルドで測定されています。キャッシュがビルド間で保持される実際の開発者ワークフロー（ブランチ切り替え、変更のプル、永続的な DerivedData を使用した CI）で利点が複合されます。ベンチマークスクリプトはこの設定を自動検出し、検証用のキャッシュされたクリーンフェーズを実行します。

実行レポート

最適化パスが完了したら、構造化された実行レポートを作成します。これは開発者に試みたこと、何が機能したか、最終的な状態の明確なサマリーを提供します。

構造：

## Execution Report

### Baseline
- Clean build median: X.Xs
- Cached clean build median: X.Xs (if applicable)
- Incremental build median: X.Xs

### Changes Applied

| # | Change | Actionability | Measured Result | Status |
|---|--------|---------------|-----------------|--------|
| 1 | Description | repo-local | Clean: X.Xs→Y.Ys, Incr: X.Xs→Y.Ys | Kept / Reverted / Blocked |
| 2 | ... | ... | ... | ... |

### Final Cumulative Result
- Clean build median: X.Xs (was Y.Ys) -- Z.Zs faster/slower
- Cached clean build median: X.Xs (was Y.Ys) -- Z.Zs faster/slower
- Incremental build median: X.Xs (was Y.Ys) -- Z.Zs faster/slower
- **Net result:** Faster / Slower / Unchanged

### Blocked or Non-Actionable Findings
- Finding: reason it could not be addressed from the repo

ステータス値：

• Kept -- 変更がビルド時間を改善または維持し、保持されました。
• Kept (best practice) -- 推奨ビルド設定; 直後のベンチマーク結果に関わらず保持されました。
• Reverted -- 変更がビルド時間を回帰させ、復帰されました。
• Blocked -- プロジェクト構造、Xcode の動作、または外部制約により変更を適用できませんでした。
• No improvement -- 変更はコンパイルされましたが、測定可能なウォールタイム利点を示しませんでした。保持されたか（非パフォーマンス理由のため）復帰されたかを含めます。

エスカレーション

実装中にこのスキルのスコープ外の問題を発見した場合：

• プロジェクトレベルの分析ギャップ：xcode-project-analyzer にハンドオフ
• コンパイルホットスポット分析：xcode-compilation-analyzer にハンドオフ
• パッケージグラフの問題：spm-build-analysis にハンドオフ

追加リソース

• 具体的な修正パターンの前後については、references/fix-patterns.md を参照
• ビルド設定のベストプラクティスについては、references/build-settings-best-practices.md を参照
• 推奨フォーマットについては、references/recommendation-format.md を参照