xcode-build-fixer

Xcode Build Fixer

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

基本ルール

• 開発者から明示的に承認された変更のみを適用してください。
• 変更をレビュー可能かつ元に戻せるよう、論理的な修正を一度に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 のような変更は、標準のクリーンビルドをわずかに遅くする可能性があります（キャッシュの初期生成によるオーバーヘッド）。一方で、キャッシュを利用するクリーンビルドは大幅に高速化されます。キャッシュを利用するクリーンビルドは、現実的な開発者のワークフロー（ブランチの切り替え、変更の取得、キャッシュが温まった状態での「Clean Build Folder」）を反映しているため、標準のクリーンビルドが遅くなっても、キャッシュ利用時のクリーンビルドが速くなれば、全体としては改善であり、リグレッションではありません。同じ考え方は、初回のコストが高くても、その後のビルドで効果が得られる変更すべてに当てはまります。

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

標準のクリーンビルド、キャッシュ利用時のクリーンビルド（利用可能な場合）、増分ビルドをまとめて評価します。開発者の日常的なワークフローで重要なメトリクスが悪化した場合にのみ、明確なリグレッションと判断します。コールドスタートのクリーンビルドだけが遅くなり、開発者が真のコールドビルドをほとんど行わないのであれば、許容できる場合があります。

個別の変更と累積効果

単独ではリグレッションを引き起こす変更でも、より大きな累積的な改善を可能にするなら、維持する価値がある場合があります（たとえば、コンパイルキャッシュを有効にすると、あるビルドタイプは遅くなる一方で、ほかのすべてのビルドでキャッシュの効果を得られるようになります）。

ベストプラクティスの設定は元に戻す対象ではありません

一部のビルド設定は、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 の改善に備えられます。」のような表現を使用します。

revert を推奨するタイミング（推測に基づく変更のみ）

ベストプラクティスの設定ではない変更（ソースコードのリファクタリング、リンク方式の実験、スクリプトフェーズの変更、依存関係の再構成など）については、次のようにします。

• 累積パスで、測定したすべてのビルドタイプ（標準のクリーンビルド、キャッシュ済みクリーンビルド、インクリメンタルビルド）において実時間が低下した場合、開発者がパフォーマンス以外の理由で特定の項目を維持するよう明示的に求めていない限り、推測に基づく変更をすべて元に戻すことを推奨します。
• 推測に基づく変更は個別に評価します。中央値の改善がなく、キャッシュ済みビルドやインクリメンタルビルドにも効果がない場合は、測定した差分とともに Recommend revert と記載します。
• 「外れ値の低減のみ」（最悪ケースは改善したが、中央値は改善していない）と「中央値の改善」（開発者の通常の待ち時間が改善した）を区別します。
• あるビルドタイプと引き換えに別のビルドタイプが改善する変更（例：標準のクリーンビルドは遅くなるが、キャッシュ済みクリーンビルドは速くなる）の場合は、両方の数値を明確に示し、開発者が判断できるようにします。次のように記載します。「標準のクリーンビルドは X.X 秒遅くなりますが、キャッシュ済みクリーンビルド（実際の日常的なワークフロー）では Y.Y 秒速くなります。」

報告

実時間の結果を、平易な表現で冒頭に記載します。

「クリーンビルドは X.X 秒で完了するようになりました（変更前は Y.Y 秒）――Z.Z 秒短縮されました。」 「インクリメンタルビルドは X.X 秒で完了するようになりました（変更前は Y.Y 秒）――Z.Z 秒短縮されました。」

続けて、次の内容を記載します。

• 変更後のクリーンビルドの実時間中央値
• 変更後のインクリメンタルビルドの実時間中央値
• 両方の絶対値および割合での実時間の差分
• ベンチマークのノイズが大きい場合は、信頼性に関する注記
• 修正ごとに変更したファイルの一覧
• 当初の推奨からの逸脱

累積タスク指標は改善したものの実時間が改善しなかった場合は、「コンパイラーの処理量は減少しましたが、ビルドの待ち時間は改善していません。Xcode がこれらのタスクを、同程度に時間のかかる他の処理と並行して実行する場合、これは想定どおりです。」と明記します。

修正によって測定可能な実時間の改善が得られなかった場合は、No measurable wall-time improvement と記載し、（コード品質などの理由で）維持するか、元に戻すかを提案します。

パフォーマンス測定以外の理由で価値がある変更には、「この変更による待ち時間の改善は期待できません。メリットは[再現性の高いビルド／ブランチ切り替えの高速化／CI コストの削減]です。」と記載します。

注：COMPILATION_CACHE_ENABLE_CACHING は、テスト済みのプロジェクト（Swift ファイル数 87～1,991）で、クリーンビルドが 5～14% 高速化することが測定されています。キャッシュがビルド間で保持される実際の開発ワークフローでは、ブランチ切り替え、変更の pull、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 を参照してください