# Xcode Build Tuner

> Implement approved Xcode build-speed fixes after strategist approval or explicit requests covering build settings, script phases, Swift compilation, or SwiftPM graphs; re-benchmark results.

- Skill: `xopoko/xcode-build-tuner` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add xopoko/xcode-build-tuner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xopoko/xcode-build-tuner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Xopoko (https://skillmd.com/u/xopoko)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xopoko/xcode-build-tuner

---


# Xcode Build Tuner

Before invoking Apple-only binaries, confirm the execution context is macOS. From Windows or Linux, run those steps in a Mac SSH project or through an already configured remote transport; do not retry missing Apple binaries locally.

Bundled commands use `$PLUGIN_ROOT` for the plugin root. Use the host's plugin-root variable when defined; otherwise set it to the absolute path of this plugin before running a helper from the app repository.

Implement only approved build optimization changes, verify compilation, and prove the result with the same benchmark contract.

## Rules

- Require either checked items in `.build-benchmark/optimization-plan.md` or an explicit user instruction.
- Apply one logical fix at a time; keep edits reviewable and reversible.
- Re-benchmark after changes and report wall-clock deltas.
- If a speculative change regresses or shows no useful benefit, flag it and recommend revert when appropriate.
- Do not revert recommended build settings only because one noisy benchmark failed to improve.

## Fix Types

- Build settings: `DEBUG_INFORMATION_FORMAT=dwarf` for Debug, `SWIFT_COMPILATION_MODE=singlefile`, `COMPILATION_CACHE_ENABLE_CACHING=YES`, `EAGER_LINKING=YES`, `SWIFT_USE_INTEGRATED_DRIVER=YES`, `ONLY_ACTIVE_ARCH=YES`, and cross-target setting alignment. Verify with `xcodebuild -showBuildSettings`.
- Script phases: declare inputs/outputs, add configuration guards, move long lists to `.xcfilelist`, and enable dependency analysis when possible.
- Source compilation: add types, break generic/chained expressions, mark non-subclassed classes `final`, tighten access control, extract huge SwiftUI builders, and add explicit closure return types. Read `references/fix-patterns.md` for examples.
- SwiftPM graph: split oversized modules, remove upward/circular dependencies, extract interface modules, remove unnecessary `@_exported import`, align options, and pin branch dependencies to tags or revisions. Confirm tags with `git ls-remote --tags`; verify with `xcodebuild -resolvePackageDependencies`.

## Workflow

1. Read the approved plan or user instruction.
2. Identify exact files/settings for each approved item.
3. Apply the change.
4. Run a quick build to catch compiler/linker errors.
5. Re-run the original baseline command, usually:
   ```bash
   python3 "$PLUGIN_ROOT/shared/build-optimization/scripts/benchmark_builds.py" \
     --project App.xcodeproj --scheme MyApp --configuration Debug \
     --destination "platform=iOS Simulator,name=<latest available iPhone simulator>,OS=latest" \
     --output-dir .build-benchmark
   ```
6. Compare clean, cached clean when present, and incremental medians.

## Regression Policy

- Evaluate wall-clock time first; cumulative task time is supporting evidence.
- A slower standard clean build can still be acceptable when cached clean or incremental builds improve.
- Keep best-practice settings even without immediate measurable improvement; they align with current Xcode direction and may compound later.
- For speculative source/script/graph changes, recommend revert if all measured build types regress or if there is no median/cached/incremental benefit.
- Distinguish "outlier reduction only" from true median improvement.

## Report

Lead with plain wall-clock impact:

```text
Clean build: X.Xs (was Y.Ys) - Z.Zs faster/slower.
Incremental build: X.Xs (was Y.Ys) - Z.Zs faster/slower.
```

Then include files changed, status per fix (`Kept`, `Kept (best practice)`, `Reverted`, `Blocked`, `No improvement`), confidence/noise notes, and any deviation from the approved plan. If task work decreased but wall-clock did not, say that parallel Xcode work hid the improvement.

## References

- `references/fix-patterns.md`
- `../../shared/build-optimization/references/build-settings-best-practices.md`
- `../../shared/build-optimization/references/recommendation-format.md`