mirror of
https://github.com/AvdLee/Xcode-Build-Optimization-Agent-Skill.git
synced 2026-09-14 13:59:59 +08:00
Merge pull request #5 from AvdLee/optimize-readme-structure
Restructure README for developer onboarding and add OPTIMIZATION-CHECKS.md
This commit is contained in:
Antoine van der Lee
@@ -32,3 +32,10 @@ This is a multi-skill Xcode build optimization repository.
|
||||
## Handoff Between Skills
|
||||
|
||||
When one skill identifies an issue outside its scope, read the target skill's `SKILL.md` under `skills/` and apply its workflow to the same project context. Pass along any benchmark artifacts or timing evidence already collected.
|
||||
|
||||
## Documentation Sync
|
||||
|
||||
- When a skill adds, removes, or changes an optimization check, update the matching row in the "What It Checks" table in `README.md` and the corresponding section in `OPTIMIZATION-CHECKS.md`.
|
||||
- When a new external reference (Apple doc, WWDC session, article) is used by a check, add it to the relevant section in `OPTIMIZATION-CHECKS.md` and to `references/build-optimization-sources.md`.
|
||||
- When a skill is added or removed, update the "Included Skills" table in `README.md`, the Skills table in this file, and the Skill Structure tree (between the `<!-- BEGIN SKILL STRUCTURE -->` / `<!-- END SKILL STRUCTURE -->` markers in `README.md`).
|
||||
- `OPTIMIZATION-CHECKS.md` is the single source of truth for what the agent checks and why. Skill-internal reference docs (under `skills/*/references/`) contain implementation detail; `OPTIMIZATION-CHECKS.md` is the developer-facing summary. Keep both layers consistent but do not duplicate implementation detail into `OPTIMIZATION-CHECKS.md`.
|
||||
|
||||
@@ -0,0 +1,231 @@
|
||||
# Optimization Checks
|
||||
|
||||
This document describes every optimization check the agent skills perform, why each check matters for build time, and where to learn more. It is the developer-facing reference; implementation details live in the skill-level docs under `skills/*/references/`.
|
||||
|
||||
## Build Settings Audit
|
||||
|
||||
The `xcode-project-analyzer` audits project-level and target-level build settings against a curated best-practices checklist. Misconfigured settings are one of the most common causes of unnecessarily slow builds, especially in projects that have been migrated across Xcode versions.
|
||||
|
||||
**Debug configuration checks:**
|
||||
|
||||
| Setting | Key | Recommended | Why |
|
||||
|---------|-----|-------------|-----|
|
||||
| Compilation Mode | `SWIFT_COMPILATION_MODE` | `singlefile` | Recompiles only changed files instead of the entire target |
|
||||
| Swift Optimization | `SWIFT_OPTIMIZATION_LEVEL` | `-Onone` | Optimization passes add compile time with no debug benefit |
|
||||
| C/ObjC Optimization | `GCC_OPTIMIZATION_LEVEL` | `0` | Same rationale for C-family sources |
|
||||
| Active Arch Only | `ONLY_ACTIVE_ARCH` | `YES` | Building all architectures doubles or triples compile and link time |
|
||||
| Debug Info Format | `DEBUG_INFORMATION_FORMAT` | `dwarf` | `dwarf-with-dsym` generates a separate dSYM bundle, adding overhead |
|
||||
| Testability | `ENABLE_TESTABILITY` | `YES` | Required for `@testable import`; minor overhead is expected |
|
||||
| Compilation Conditions | `SWIFT_ACTIVE_COMPILATION_CONDITIONS` | includes `DEBUG` | Guards `#if DEBUG` code paths |
|
||||
| Eager Linking | `EAGER_LINKING` | `YES` | Starts linking before all compilation finishes, reducing wall-clock time |
|
||||
|
||||
**Release configuration checks:**
|
||||
|
||||
| Setting | Key | Recommended | Why |
|
||||
|---------|-----|-------------|-----|
|
||||
| Compilation Mode | `SWIFT_COMPILATION_MODE` | `wholemodule` | Produces optimized runtime code |
|
||||
| Swift Optimization | `SWIFT_OPTIMIZATION_LEVEL` | `-O` or `-Osize` | Optimized binaries for distribution |
|
||||
| C/ObjC Optimization | `GCC_OPTIMIZATION_LEVEL` | `s` | Optimizes for size |
|
||||
| Active Arch Only | `ONLY_ACTIVE_ARCH` | `NO` | Release must include all supported architectures |
|
||||
| Debug Info Format | `DEBUG_INFORMATION_FORMAT` | `dwarf-with-dsym` | Required for crash symbolication |
|
||||
| Testability | `ENABLE_TESTABILITY` | `NO` | Removes internal-symbol export overhead |
|
||||
|
||||
**General (all configurations) checks:**
|
||||
|
||||
| Setting | Key | Recommended | Why |
|
||||
|---------|-----|-------------|-----|
|
||||
| Compilation Caching | `COMPILATION_CACHING` | `YES` | Caches Swift and C-family compilation results; biggest wins on branch switching and clean builds |
|
||||
| Integrated Swift Driver | `SWIFT_USE_INTEGRATED_DRIVER` | `YES` | Eliminates inter-process overhead for compilation scheduling |
|
||||
| Clang Modules | `CLANG_ENABLE_MODULES` | `YES` | Caches module maps on disk instead of reprocessing headers |
|
||||
| Explicit Modules | `SWIFT_ENABLE_EXPLICIT_MODULES` | Evaluate per-project | Improves parallelism but may regress due to scanning overhead; benchmark before and after |
|
||||
|
||||
**References:**
|
||||
- [Improving the speed of incremental builds](https://developer.apple.com/documentation/xcode/improving-the-speed-of-incremental-builds) -- Apple Documentation
|
||||
- [SwiftLee: Build performance analysis for speeding up Xcode builds](https://www.avanderlee.com/optimization/analysing-build-performance-xcode/)
|
||||
- [Xcode Release Notes: Compilation Caching](https://developer.apple.com/documentation/xcode-release-notes/) (feature ID 149700201)
|
||||
- [Bitrise: Xcode Compilation Cache FAQ](https://docs.bitrise.io/en/bitrise-build-cache/build-cache-for-xcode/xcode-compilation-cache-faq.html)
|
||||
|
||||
## Script Phase Analysis
|
||||
|
||||
The `xcode-project-analyzer` inspects every Run Script phase in the project for missing metadata and unnecessary execution.
|
||||
|
||||
**What the agent checks:**
|
||||
|
||||
- Scripts without declared input and output files run on every build regardless of changes. The agent flags these and recommends adding declarations or `.xcfilelist` files.
|
||||
- Scripts that always run (`alwaysOutOfDate = 1`) are flagged with a recommendation to make them conditional.
|
||||
- Debug/simulator guards: scripts that upload symbols, run release-only tools, or perform network calls should be skipped in Debug or Simulator builds.
|
||||
- Timestamp-touching tools: linters or formatters that modify file timestamps without changing content silently invalidate build inputs and force replanning of every Swift module.
|
||||
- Parallelization: scripts with correctly declared dependencies can run in parallel with compilation instead of blocking it.
|
||||
|
||||
**References:**
|
||||
- [Improving the speed of incremental builds](https://developer.apple.com/documentation/xcode/improving-the-speed-of-incremental-builds) -- Apple Documentation (script input/output declarations, `.xcfilelist`)
|
||||
- [Swift Forums: Slow incremental builds because of "Planning Swift module"](https://forums.swift.org/t/slow-incremental-builds-because-of-planning-swift-module/84803) -- timestamp invalidation case study
|
||||
|
||||
## Compile Hotspot Detection
|
||||
|
||||
The `xcode-compilation-analyzer` identifies Swift source files and expressions that take disproportionately long to type-check.
|
||||
|
||||
**What the agent checks:**
|
||||
|
||||
- Build Timing Summary categories to find targets where `CompileSwiftSources` dominates.
|
||||
- Compiler diagnostic flags (`-warn-long-function-bodies`, `-warn-long-expression-type-checking`) to surface specific slow expressions.
|
||||
- Optional deep diagnostics: `-debug-time-compilation` (per-file ranking), `-debug-time-function-bodies` (per-function timing), `-stats-output-dir` (compiler statistics as JSON).
|
||||
- Patterns that commonly cause slow type-checking:
|
||||
- Complex chained or nested expressions without intermediate type annotations
|
||||
- Nested ternaries or overloaded generic chains
|
||||
- Long method chains (`.map().flatMap().filter().reduce()`) without typed intermediates
|
||||
- Closures passed to generic functions without explicit return types
|
||||
|
||||
**References:**
|
||||
- [Improving build efficiency with good coding practices](https://developer.apple.com/documentation/xcode/improving-build-efficiency-with-good-coding-practices) -- Apple Documentation
|
||||
- [SwiftLee: Build performance analysis for speeding up Xcode builds](https://www.avanderlee.com/optimization/analysing-build-performance-xcode/) -- compiler diagnostic flags
|
||||
|
||||
## Zero-Change Build Overhead
|
||||
|
||||
The `xcode-project-analyzer` measures and diagnoses the fixed cost of rebuilding when nothing has changed.
|
||||
|
||||
**What the agent checks:**
|
||||
|
||||
Even with no source edits, incremental builds incur fixed overhead. The agent measures zero-change build time and investigates these categories from the Build Timing Summary:
|
||||
|
||||
| Category | What it does | Why it matters |
|
||||
|----------|-------------|----------------|
|
||||
| `PhaseScriptExecution` | Script phases with `alwaysOutOfDate` or missing I/O | Runs on every build regardless of changes |
|
||||
| `CodeSign` | Signs the app and embedded frameworks | Runs unconditionally; scales with signed binary count |
|
||||
| `ValidateEmbeddedBinary` | Validates against provisioning profile | Runs unconditionally |
|
||||
| `CopySwiftLibs` | Copies Swift standard libraries | Runs even when nothing changed |
|
||||
| `RegisterWithLaunchServices` | Registers the built app | Fast but always present |
|
||||
| `ProcessInfoPlistFile` | Re-processes Info.plist files | Scales with target count |
|
||||
| `ExtractAppIntentsMetadata` | Extracts App Intents metadata | Unnecessary overhead if the project does not use App Intents |
|
||||
|
||||
A zero-change build above 5 seconds on Apple Silicon typically indicates script phase overhead or excessive codesigning.
|
||||
|
||||
**References:**
|
||||
- [Improving the speed of incremental builds](https://developer.apple.com/documentation/xcode/improving-the-speed-of-incremental-builds) -- Apple Documentation
|
||||
- [Swift Forums: Slow incremental builds because of "Planning Swift module"](https://forums.swift.org/t/slow-incremental-builds-because-of-planning-swift-module/84803) -- zero-change overhead breakdown
|
||||
|
||||
## Target Dependency Review
|
||||
|
||||
The `xcode-project-analyzer` audits target dependencies and scheme configuration for correctness and parallelism.
|
||||
|
||||
**What the agent checks:**
|
||||
|
||||
- Target dependencies are explicit and accurate. Missing dependencies cause build failures; inflated dependencies block parallel work.
|
||||
- Removed or stale dependencies that no longer reflect real build requirements.
|
||||
- Scheme builds targets in `Dependency Order` (not manual order).
|
||||
- Oversized monolithic targets that serialize compilation when the work could be split across parallel targets.
|
||||
- `DEFINES_MODULE` is enabled for custom frameworks that should benefit from module maps.
|
||||
- Public headers are self-contained enough to compile as a module.
|
||||
|
||||
**References:**
|
||||
- [Improving the speed of incremental builds](https://developer.apple.com/documentation/xcode/improving-the-speed-of-incremental-builds) -- Apple Documentation (target dependencies, module maps)
|
||||
|
||||
## Module Variant Detection
|
||||
|
||||
The `xcode-project-analyzer` and `spm-build-analysis` skills check for configuration drift that causes the same module to be built multiple times with different options.
|
||||
|
||||
**What the agent checks:**
|
||||
|
||||
- Targets that import the same SPM package but compile with different Swift compiler options produce separate module variants, inflating `SwiftEmitModule` task counts.
|
||||
- Drift in `SWIFT_OPTIMIZATION_LEVEL`, `SWIFT_COMPILATION_MODE`, `OTHER_SWIFT_FLAGS`, and target-level overrides.
|
||||
- Project-level vs target-level build setting overrides: settings should be at the project level unless a target has a specific reason to override.
|
||||
- Preprocessor macros or other build options that differ across sibling targets importing the same modules.
|
||||
|
||||
**References:**
|
||||
- [Building your project with explicit module dependencies](https://developer.apple.com/documentation/xcode/building-your-project-with-explicit-module-dependencies) -- Apple Documentation
|
||||
- [WWDC24: Demystify explicitly built modules](https://developer.apple.com/videos/play/wwdc2024/10171/)
|
||||
- [Bitrise: Demystifying Explicitly Built Modules for Xcode](https://bitrise.io/blog/post/demystifying-explicitly-built-modules-for-xcode)
|
||||
|
||||
## SPM Graph Analysis
|
||||
|
||||
The `spm-build-analysis` skill inspects Swift Package Manager dependencies for graph structure issues, plugin overhead, and dependency hygiene.
|
||||
|
||||
**What the agent checks:**
|
||||
|
||||
- Large umbrella packages that trigger widespread rebuilds.
|
||||
- Dependency layering violations: features depending on features instead of flowing inward (Common/Core → Services → Features/UI).
|
||||
- Circular dependencies (target-level cycles must be refactored; extract shared contracts into a separate module).
|
||||
- Build-tool and command plugins that run during incremental builds even when no input changed.
|
||||
- Branch-pinned packages (`branch:`) that force network checks on every fresh resolve; recommends pinning to tags or `revision:` hashes.
|
||||
- Package reference verification: confirms packages listed in recommendations actually appear in `project.pbxproj` as linked dependencies.
|
||||
- Transitive dependency minimization: flags `@_exported import` umbrella modules that create hidden rebuild chains.
|
||||
- Interface/implementation separation opportunities for modules with heavy dependencies.
|
||||
- Test target isolation: test targets should depend on the module under test, not the entire app target.
|
||||
|
||||
**References:**
|
||||
- [Improving the speed of incremental builds](https://developer.apple.com/documentation/xcode/improving-the-speed-of-incremental-builds) -- Apple Documentation
|
||||
- [Building your project with explicit module dependencies](https://developer.apple.com/documentation/xcode/building-your-project-with-explicit-module-dependencies) -- Apple Documentation
|
||||
|
||||
## Swift Macro Impact
|
||||
|
||||
The `spm-build-analysis` skill checks for incremental build cascading caused by heavy Swift macro usage.
|
||||
|
||||
**What the agent checks:**
|
||||
|
||||
- Projects using macro-heavy libraries (e.g., TCA, swift-syntax-based tools) are susceptible to cascading where a trivial change rebuilds most of the app.
|
||||
- Macro expansion can invalidate downstream modules even when the expanded output has not changed.
|
||||
- `swift-syntax` building universally (all architectures) when no prebuilt binary is available adds significant overhead to clean builds and CI.
|
||||
- Recommends isolating macro-using code into fewer, more stable modules to limit the invalidation blast radius.
|
||||
|
||||
**References:**
|
||||
- [Swift Forums: Slow incremental builds because of "Planning Swift module"](https://forums.swift.org/t/slow-incremental-builds-because-of-planning-swift-module/84803) -- macro cascading, swift-syntax overhead
|
||||
|
||||
## SwiftUI View Decomposition
|
||||
|
||||
The `xcode-compilation-analyzer` checks for SwiftUI view bodies that are expensive to type-check.
|
||||
|
||||
**What the agent checks:**
|
||||
|
||||
- Monolithic `body` properties (roughly 50+ lines) that force the type-checker to resolve a single large result-builder expression.
|
||||
- `@ViewBuilder` helper properties instead of separate `struct View` types -- separate structs reduce the type-checker scope per `body`.
|
||||
- Deeply nested `Group`/`VStack`/`HStack` hierarchies within a single body.
|
||||
- Recommends extracting subviews into dedicated `struct View` types.
|
||||
|
||||
**References:**
|
||||
- [Improving build efficiency with good coding practices](https://developer.apple.com/documentation/xcode/improving-build-efficiency-with-good-coding-practices) -- Apple Documentation
|
||||
|
||||
## Asset Catalog Parallelism
|
||||
|
||||
The `xcode-project-analyzer` checks asset catalog compilation for single-threaded bottlenecks.
|
||||
|
||||
**What the agent checks:**
|
||||
|
||||
- `CompileAssetCatalog` is single-threaded per target. Multiple catalogs within the same target compile sequentially in a single process.
|
||||
- If asset catalog compilation appears as a significant timing category, recommends splitting assets into separate resource bundles across separate targets for parallel compilation.
|
||||
- Asset catalog compilation is not cacheable by the Xcode compilation cache (`CompileAssetCatalogVariant` is non-cacheable).
|
||||
- Checks whether asset catalogs rebuild during incremental builds even when no assets changed.
|
||||
|
||||
**References:**
|
||||
- [Swift Forums: Slow incremental builds because of "Planning Swift module"](https://forums.swift.org/t/slow-incremental-builds-because-of-planning-swift-module/84803) -- asset catalog single-threaded compilation
|
||||
- [Bitrise: Xcode Compilation Cache FAQ](https://docs.bitrise.io/en/bitrise-build-cache/build-cache-for-xcode/xcode-compilation-cache-faq.html) -- non-cacheable task types
|
||||
|
||||
## Access Control Optimization
|
||||
|
||||
The `xcode-compilation-analyzer` checks for access control patterns that inflate compiler work.
|
||||
|
||||
**What the agent checks:**
|
||||
|
||||
- Classes not intended for subclassing should be marked `final`. This eliminates virtual dispatch overhead and lets the compiler de-virtualize method calls.
|
||||
- Properties and methods not used outside their declaration or file should use `private` or `fileprivate`. Narrower visibility reduces the compiler's symbol search space.
|
||||
- `internal` (the default) is preferred over `public` unless the symbol genuinely crosses module boundaries.
|
||||
- `struct` and `enum` are preferred over `class` when reference semantics are not needed. Value types are simpler for the compiler to reason about.
|
||||
- Objective-C bridging surfaces should be kept narrow. Swift members marked `private` do not need Objective-C visibility.
|
||||
|
||||
**References:**
|
||||
- [Improving build efficiency with good coding practices](https://developer.apple.com/documentation/xcode/improving-build-efficiency-with-good-coding-practices) -- Apple Documentation
|
||||
|
||||
## Incremental Build Diagnostics
|
||||
|
||||
The `xcode-compilation-analyzer` and `xcode-project-analyzer` investigate categories that disproportionately inflate incremental builds.
|
||||
|
||||
**What the agent checks:**
|
||||
|
||||
- **Planning Swift module**: Can dominate incremental builds (up to 30s per module), sometimes exceeding clean build time. If modules are replanned but no compiles are scheduled, build inputs are being invalidated unexpectedly.
|
||||
- **SwiftEmitModule**: Can take 60s+ after a single-line change in large modules. If it exceeds compile time for the same target, the module's public API surface may be unnecessarily wide.
|
||||
- **Task Backtraces** (Xcode 16.4+): Enable via Scheme Editor > Build > Build Debugging to see why each task re-ran. The agent recommends enabling this when incremental build overhead is unexplained.
|
||||
- **Multi-platform build multiplication**: Adding a secondary platform (e.g., watchOS) can cause shared SPM packages to build multiple times per platform/architecture combination.
|
||||
|
||||
**References:**
|
||||
- [Swift Forums: Slow incremental builds because of "Planning Swift module"](https://forums.swift.org/t/slow-incremental-builds-because-of-planning-swift-module/84803)
|
||||
- [Building your project with explicit module dependencies](https://developer.apple.com/documentation/xcode/building-your-project-with-explicit-module-dependencies) -- Apple Documentation
|
||||
- [WWDC24: Demystify explicitly built modules](https://developer.apple.com/videos/play/wwdc2024/10171/)
|
||||
@@ -4,10 +4,10 @@ Open-source Agent Skills for benchmarking and optimizing Xcode build performance
|
||||
|
||||
## Quick Start
|
||||
|
||||
Install the orchestrator skill:
|
||||
Install all six skills (the orchestrator needs the specialist skills to work):
|
||||
|
||||
```bash
|
||||
npx skills add https://github.com/avdlee/xcode-build-optimization-agent-skill --skill xcode-build-orchestrator
|
||||
npx skills add https://github.com/avdlee/xcode-build-optimization-agent-skill
|
||||
```
|
||||
|
||||
Then open your Xcode project in your AI coding tool and say:
|
||||
@@ -16,16 +16,73 @@ Then open your Xcode project in your AI coding tool and say:
|
||||
|
||||
The agent will benchmark your clean and incremental builds, audit build settings, find compile hotspots, and produce an optimization plan at `.build-benchmark/optimization-plan.md`. No project files are modified until you explicitly approve changes.
|
||||
|
||||
[See results of projects that used this skill →](#community-results)
|
||||
|
||||
For long-term monitoring across days, machines, Xcode versions, and teams, use [RocketSim Build Insights](https://www.rocketsim.app/docs/features/build-insights/build-insights/) and [Team Build Insights](https://www.rocketsim.app/docs/features/build-insights/team-build-insights/).
|
||||
|
||||
## See Also My Other Skills
|
||||
## Every Second Counts
|
||||
|
||||
- [Swift Concurrency Expert](https://github.com/AvdLee/Swift-Concurrency-Agent-Skill)
|
||||
- [SwiftUI Expert](https://github.com/AvdLee/SwiftUI-Agent-Skill)
|
||||
- [Core Data Expert](https://github.com/AvdLee/Core-Data-Agent-Skill)
|
||||
- [Swift Testing Expert](https://github.com/AvdLee/Swift-Testing-Agent-Skill)
|
||||
A 1-second improvement on a 30-second incremental build sounds small. At 50 builds a day, that adds up to **3.5 hours per developer per year** -- or **35 hours across a team of ten**.
|
||||
|
||||
Most projects have several seconds of easy wins hiding in build settings, script phases, and compiler flags. This skill finds them.
|
||||
|
||||
## How It Works
|
||||
|
||||
The orchestrator coordinates five specialist skills in a recommend-first workflow. Nothing is modified until you approve.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Orchestrator --> Benchmark["Benchmark\n(clean + incremental)"]
|
||||
Benchmark --> Compilation["Compilation\nAnalyzer"]
|
||||
Benchmark --> Project["Project\nAnalyzer"]
|
||||
Benchmark --> SPM["SPM\nAnalyzer"]
|
||||
Compilation --> Plan["Optimization\nPlan"]
|
||||
Project --> Plan
|
||||
SPM --> Plan
|
||||
Plan --> You{{"You review\n& approve"}}
|
||||
You --> Fixer["Build\nFixer"]
|
||||
Fixer --> ReBenchmark["Re-benchmark\n& verify"]
|
||||
```
|
||||
|
||||
**Phase 1 -- Analyze.** The orchestrator benchmarks your project, runs the three specialist analyzers, and produces a prioritized optimization plan at `.build-benchmark/optimization-plan.md`. No project files are modified.
|
||||
|
||||
> Use the Xcode build orchestrator to analyze build performance and come up with a plan for improvements.
|
||||
|
||||
**Phase 2 -- Fix.** Review the plan, check the approval boxes for the items you want, and ask the agent to apply them. The fixer implements only approved changes and re-benchmarks to verify.
|
||||
|
||||
> Implement the approved items from the optimization plan at .build-benchmark/optimization-plan.md, then re-benchmark to verify the improvements.
|
||||
|
||||
The plan file is your evidence trail -- shareable with teammates, reviewable in PRs, and diffable over time.
|
||||
|
||||
## What It Checks
|
||||
|
||||
The agent runs [over 40 individual checks](OPTIMIZATION-CHECKS.md) across build settings, project configuration, source code, and package dependencies.
|
||||
|
||||
| Check | What the agent looks for | |
|
||||
|-------|--------------------------|---|
|
||||
| Build settings audit | Debug/Release/General settings against best practices (compilation mode, optimization level, eager linking, compilation caching) | [Details](OPTIMIZATION-CHECKS.md#build-settings-audit) |
|
||||
| Script phase analysis | Missing input/output declarations, scripts running unnecessarily, debug/simulator guards | [Details](OPTIMIZATION-CHECKS.md#script-phase-analysis) |
|
||||
| Compile hotspot detection | Long type-checks, complex expressions, compiler diagnostic flags | [Details](OPTIMIZATION-CHECKS.md#compile-hotspot-detection) |
|
||||
| Zero-change build overhead | Fixed-cost phases (codesign, validation, scripts) inflating incremental builds | [Details](OPTIMIZATION-CHECKS.md#zero-change-build-overhead) |
|
||||
| Target dependency review | Accuracy, parallelism blockers, monolithic targets | [Details](OPTIMIZATION-CHECKS.md#target-dependency-review) |
|
||||
| Module variant detection | Config drift across targets causing duplicate module builds | [Details](OPTIMIZATION-CHECKS.md#module-variant-detection) |
|
||||
| SPM graph analysis | Plugin overhead, branch pins, package layering, circular dependencies | [Details](OPTIMIZATION-CHECKS.md#spm-graph-analysis) |
|
||||
| Swift macro impact | Cascading rebuilds, swift-syntax universal builds | [Details](OPTIMIZATION-CHECKS.md#swift-macro-impact) |
|
||||
| SwiftUI view decomposition | Monolithic body properties, result builder complexity | [Details](OPTIMIZATION-CHECKS.md#swiftui-view-decomposition) |
|
||||
| Asset catalog parallelism | Single-threaded compilation bottleneck, splitting for parallel builds | [Details](OPTIMIZATION-CHECKS.md#asset-catalog-parallelism) |
|
||||
| Access control optimization | Missing `final`, overly broad visibility inflating compiler work | [Details](OPTIMIZATION-CHECKS.md#access-control-optimization) |
|
||||
| Incremental build diagnostics | Planning Swift module, SwiftEmitModule, Task Backtraces | [Details](OPTIMIZATION-CHECKS.md#incremental-build-diagnostics) |
|
||||
|
||||
## Community Results
|
||||
|
||||
Real-world improvements reported by developers who used these skills. Add your own by opening a pull request.
|
||||
|
||||
The `xcode-build-orchestrator` generates your table row at the end of every optimization run, so contributing is a single copy-paste.
|
||||
|
||||
| App | Clean Build | Incremental Build |
|
||||
|-----|------------|-------------------|
|
||||
| [Stock Analyzer](https://www.stock-analyzer.app) | 41.5s → 33.2s (-8.3s / 20% faster) | 5.3s → 3.6s (-1.7s / 32% faster) |
|
||||
| [Enchanted](https://github.com/gluonfield/enchanted/pull/216) | 19.4s → 16.6s (-2.8s / 14% faster) | 2.5s → 2.2s (-0.3s / 12% faster) |
|
||||
| [Wikipedia iOS](https://github.com/wikimedia/wikipedia-ios/pull/5740) | 48.7s → 46.5s (-2.2s / 5% faster) | 12.9s → 12.2s (-0.7s / 5% faster) |
|
||||
| [Kickstarter iOS](https://github.com/kickstarter/ios-oss/pull/2808) | 83.4s → 83.5s (~0s / within noise) | 10.9s → 10.6s (-0.3s / 3% faster) |
|
||||
|
||||
## Who This Is For
|
||||
|
||||
@@ -45,19 +102,25 @@ For long-term monitoring across days, machines, Xcode versions, and teams, use [
|
||||
| `spm-build-analysis` | Package graph, plugin overhead, and module variant review |
|
||||
| `xcode-build-fixer` | Apply approved optimization changes and verify with benchmarks |
|
||||
|
||||
The orchestrator is the recommended starting point -- it coordinates the other five skills automatically.
|
||||
The orchestrator is the recommended starting point -- it coordinates the other five skills automatically. Install all six skills so the orchestrator can access each specialist.
|
||||
|
||||
## Installation Options
|
||||
|
||||
### Option A: Using skills.sh
|
||||
|
||||
Install a single skill:
|
||||
Install all six skills (required -- the orchestrator depends on the specialist skills):
|
||||
|
||||
```bash
|
||||
npx skills add https://github.com/avdlee/xcode-build-optimization-agent-skill --skill xcode-build-orchestrator
|
||||
npx skills add https://github.com/avdlee/xcode-build-optimization-agent-skill
|
||||
```
|
||||
|
||||
Or install any of the six skills individually: `xcode-build-benchmark`, `xcode-compilation-analyzer`, `xcode-project-analyzer`, `spm-build-analysis`, `xcode-build-orchestrator`, `xcode-build-fixer`.
|
||||
To install a single skill for standalone use, add the `--skill` flag:
|
||||
|
||||
```bash
|
||||
npx skills add https://github.com/avdlee/xcode-build-optimization-agent-skill --skill xcode-project-analyzer
|
||||
```
|
||||
|
||||
Available individual skills: `xcode-build-benchmark`, `xcode-compilation-analyzer`, `xcode-project-analyzer`, `spm-build-analysis`, `xcode-build-orchestrator`, `xcode-build-fixer`. Note that the orchestrator requires all other skills to be installed.
|
||||
|
||||
### Option B: Claude Code Plugin
|
||||
|
||||
@@ -99,20 +162,6 @@ To enable for everyone in a repository, add to your project configuration:
|
||||
|
||||
Useful docs: [Codex Skills](https://developers.openai.com/codex/skills/#where-to-save-skills) | [Claude Code Agent Skills](https://code.claude.com/en/skills) | [Cursor Skills](https://cursor.com/docs/context/skills#enabling-skills)
|
||||
|
||||
## How It Works
|
||||
|
||||
The orchestrator uses a two-phase recommend-first workflow that separates analysis from implementation.
|
||||
|
||||
**Phase 1 -- Analyze.** The agent benchmarks your project, runs all specialist analyses, and produces a markdown optimization plan at `.build-benchmark/optimization-plan.md`. The plan includes baseline benchmarks, a build settings audit, compilation diagnostics, and prioritized recommendations with an approval checklist. No project files are modified.
|
||||
|
||||
> Use the Xcode build orchestrator to analyze build performance and come up with a plan for improvements.
|
||||
|
||||
**Phase 2 -- Fix.** After reviewing the plan, check the approval boxes for the recommendations you want and ask the agent to implement them. It applies only the approved changes, re-benchmarks, and reports the measured improvement.
|
||||
|
||||
> Implement the approved items from the optimization plan at .build-benchmark/optimization-plan.md, then re-benchmark to verify the improvements.
|
||||
|
||||
The plan file becomes the evidence trail -- shareable with teammates, reviewable in pull requests, and diffable over time.
|
||||
|
||||
## Why Clean And Incremental Builds Both Matter
|
||||
|
||||
Clean builds expose:
|
||||
@@ -130,6 +179,13 @@ Incremental builds expose:
|
||||
|
||||
That distinction is central to this repo and follows both Apple's Xcode guidance and the SwiftLee workflow in [Build performance analysis for speeding up Xcode builds](https://www.avanderlee.com/optimization/analysing-build-performance-xcode/).
|
||||
|
||||
## See Also My Other Skills
|
||||
|
||||
- [Swift Concurrency Expert](https://github.com/AvdLee/Swift-Concurrency-Agent-Skill)
|
||||
- [SwiftUI Expert](https://github.com/AvdLee/SwiftUI-Agent-Skill)
|
||||
- [Core Data Expert](https://github.com/AvdLee/Core-Data-Agent-Skill)
|
||||
- [Swift Testing Expert](https://github.com/AvdLee/Swift-Testing-Agent-Skill)
|
||||
|
||||
## Shared Support Layer
|
||||
|
||||
The skills share:
|
||||
@@ -190,12 +246,7 @@ xcode-build-optimization-agent-skill/
|
||||
|
||||
## Research Basis
|
||||
|
||||
This repo deliberately aligns with:
|
||||
|
||||
- Apple's incremental-build guidance: accurate target dependencies, script input/output declarations, module maps, and parallel-friendly project structure
|
||||
- Apple's compile-efficiency guidance: explicit type information, simpler expressions, narrower bridging surfaces, and framework-qualified imports
|
||||
- Apple's explicit module dependency guidance: reducing duplicate module variants caused by configuration drift
|
||||
- the SwiftLee workflow for measuring with Build Timeline, Build Timing Summary, and Swift frontend diagnostics
|
||||
All checks are grounded in Apple documentation, WWDC sessions, and proven community practices. See [OPTIMIZATION-CHECKS.md](OPTIMIZATION-CHECKS.md) for the full list of checks with references to each source.
|
||||
|
||||
The stored reference summaries live in `references/build-optimization-sources.md`.
|
||||
|
||||
@@ -212,19 +263,6 @@ RocketSim complements it by monitoring build performance over time:
|
||||
|
||||
If you want to catch regressions earlier and see whether your build times are improving over weeks or months, use [RocketSim Build Insights](https://www.rocketsim.app/docs/features/build-insights/build-insights/) after you apply the improvements from this repo.
|
||||
|
||||
## Community Results
|
||||
|
||||
Real-world improvements reported by developers who used these skills. Add your own by opening a pull request.
|
||||
|
||||
The `xcode-build-orchestrator` generates your table row at the end of every optimization run, so contributing is a single copy-paste.
|
||||
|
||||
| App | Clean Build | Incremental Build |
|
||||
|-----|------------|-------------------|
|
||||
| [Stock Analyzer](https://www.stock-analyzer.app) | 41.5s → 33.2s (-8.3s / 20% faster) | 5.3s → 3.6s (-1.7s / 32% faster) |
|
||||
| [Enchanted](https://github.com/gluonfield/enchanted/pull/216) | 19.4s → 16.6s (-2.8s / 14% faster) | 2.5s → 2.2s (-0.3s / 12% faster) |
|
||||
| [Wikipedia iOS](https://github.com/wikimedia/wikipedia-ios/pull/5740) | 48.7s → 46.5s (-2.2s / 5% faster) | 12.9s → 12.2s (-0.7s / 5% faster) |
|
||||
| [Kickstarter iOS](https://github.com/kickstarter/ios-oss/pull/2808) | 83.4s → 83.5s (~0s / within noise) | 10.9s → 10.6s (-0.3s / 3% faster) |
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome when they keep the repo focused on Xcode build optimization and Agent Skills format quality.
|
||||
|
||||
Reference in New Issue
Block a user