xcode-build-orchestrator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Xcode Build Orchestrator

Xcode构建编排器

Use this skill as the recommend-first entrypoint for end-to-end Xcode build optimization work.

将此技能作为端到端Xcode构建优化工作的推荐优先入口。

Non-Negotiable Rules

不可违背的规则

Wall-clock build time (how long the developer waits) is the primary success metric. Every recommendation must state its expected impact on the developer's actual wait time.
Start in recommendation mode.
Benchmark before making changes.
Do not modify project files, source files, packages, or scripts without explicit developer approval.
Preserve the evidence trail for every recommendation.
Re-benchmark after approved changes and report the wall-clock delta.

实际构建耗时（开发者等待的时间）是主要的成功指标。每一条建议都必须说明其对开发者实际等待时间的预期影响。
以建议模式启动。
在进行变更前先执行基准测试。
未经开发者明确批准，不得修改项目文件、源文件、包或脚本。
保留每条建议的证据链。
在已批准的变更完成后重新执行基准测试，并报告实际耗时的变化值。

Two-Phase Workflow

两阶段工作流

The orchestration is designed as two distinct phases separated by developer review.

编排工作流分为两个明确的阶段，中间由开发者审核环节隔开。

Phase 1 -- Analyze (recommend-only)

阶段1——分析（仅提供建议）

Run this phase in agent mode because the agent needs to execute builds, run benchmark scripts, write benchmark artifacts, and generate the optimization report. However, treat Phase 1 as recommend-only: do not modify any project files, source files, packages, or build settings. The only files the agent creates during this phase are benchmark artifacts and the optimization plan inside

.build-benchmark/

Collect the build target context: workspace or project, scheme, configuration, destination, and current pain point. When both
```
.xcworkspace
```
and
```
.xcodeproj
```
exist, prefer
```
.xcodeproj
```
unless the workspace contains sub-projects required for the build. Workspaces that reference external projects may fail if those projects are not checked out.
Run
```
xcode-build-benchmark
```
to establish a baseline if no fresh benchmark exists. The benchmark script auto-detects
```
COMPILATION_CACHING = YES
```
and includes cached clean builds that measure the realistic developer experience (warm cache). If the build fails to compile, check
```
git log
```
for a recent buildable commit. When working in a worktree, cherry-picking a targeted build fix from a feature branch is acceptable to reach a buildable state. If SPM packages reference gitignored directories in their
```
exclude:
```
paths (e.g.,
```
__Snapshots__
```
), create those directories before building -- worktrees do not contain gitignored content and
```
xcodebuild -resolvePackageDependencies
```
will crash otherwise.
Verify the benchmark artifact has non-empty
```
timing_summary_categories
```
. If empty, the timing summary parser may have failed -- re-parse the raw logs or inspect them manually. If
```
COMPILATION_CACHING
```
is enabled, also verify the artifact includes
```
cached_clean
```
runs.
- Benchmark confidence check: For each build type (clean, cached clean, incremental), compare the min and max values. If the spread (max - min) exceeds 20% of the median, flag the benchmark as having high variance and recommend running additional repetitions (5+ runs) before drawing conclusions. High variance makes it difficult to distinguish real improvements from noise. After applying changes, only claim an improvement if the post-change median falls outside the baseline's min-max range.
If incremental builds are the primary pain point and Xcode 16.4+ is available, recommend the developer enable Task Backtraces (Scheme Editor > Build tab > Build Debugging > "Task Backtraces"). This reveals why each task re-ran, which is critical for diagnosing unexpected replanning or input invalidation. Include any Task Backtrace evidence in the analysis.
Determine whether compile tasks are likely blocking wall-clock progress or just consuming parallel CPU time. Compare the sum of all timing-summary category seconds against the wall-clock median: if the sum is 2x+ the median, most work is parallelized and compile hotspot fixes are unlikely to reduce wait time. If
```
SwiftCompile
```
,
```
CompileC
```
,
```
SwiftEmitModule
```
, or
```
Planning Swift module
```
dominate the timing summary and appear likely to be on the critical path, run
```
diagnose_compilation.py
```
to capture type-checking hotspots. If they are parallelized, still run diagnostics but label findings as "parallel efficiency improvements" rather than "build time improvements."
Run the specialist analyses that fit the evidence by reading each skill's SKILL.md and applying its workflow:
- ```
xcode-compilation-analyzer
```
- ```
xcode-project-analyzer
```
- ```
spm-build-analysis
```
Merge findings into a single prioritized improvement plan.
Generate the markdown optimization report using
```
generate_optimization_report.py
```
and save it to
```
.build-benchmark/optimization-plan.md
```
. This report includes the build settings audit, timing analysis, prioritized recommendations, and an approval checklist.
Stop and present the plan to the developer for review.

The developer reviews

.build-benchmark/optimization-plan.md

, checks the approval boxes for the recommendations they want implemented, and then triggers phase 2.

在Agent模式下运行此阶段，因为Agent需要执行构建、运行基准测试脚本、生成基准测试工件，并生成优化报告。但阶段1需严格遵循仅提供建议的原则：不得修改任何项目文件、源文件、包或构建设置。此阶段Agent仅能创建基准测试工件，以及在

.build-benchmark/

目录下生成优化计划。

收集构建目标上下文：工作区或项目、Scheme、配置、目标设备，以及当前的痛点。当
```
.xcworkspace
```
和
```
.xcodeproj
```
同时存在时，优先使用
```
.xcodeproj
```
，除非工作区包含构建所需的子项目。引用外部项目的工作区如果未检出这些项目，可能会构建失败。
如果没有最新的基准测试结果，运行
```
xcode-build-benchmark
```
来建立基线。基准测试脚本会自动检测
```
COMPILATION_CACHING = YES
```
，并包含缓存的clean构建，以此衡量开发者的真实体验（暖缓存）。如果构建编译失败，查看
```
git log
```
获取最近可构建的提交记录。在工作树环境中，可从功能分支 cherry-pick 针对性的构建修复，以达到可构建状态。如果SPM包在其
```
exclude:
```
路径中引用了被git忽略的目录（如
```
__Snapshots__
```
），请在构建前创建这些目录——工作树不包含被git忽略的内容，否则
```
xcodebuild -resolvePackageDependencies
```
会崩溃。
验证基准测试工件中的
```
timing_summary_categories
```
是否非空。如果为空，可能是耗时摘要解析器失败——重新解析原始日志或手动检查。如果启用了
```
COMPILATION_CACHING
```
，还需验证工件是否包含
```
cached_clean
```
运行记录。
- 基准测试可信度检查：对于每种构建类型（clean、缓存clean、增量构建），比较最小值和最大值。如果差值（最大值-最小值）超过中位数的20%，则标记此基准测试存在高方差，并建议在得出结论前额外运行多次（5次以上）。高方差会导致难以区分真实的改进与噪声。在应用变更后，只有当变更后的中位数超出基线的最小值-最大值范围时，才能声称有改进。
如果增量构建是主要痛点，且Xcode 16.4+可用，建议开发者启用任务回溯（Task Backtraces）（Scheme编辑器 > Build标签 > Build调试 > "Task Backtraces"）。这会揭示每个任务重新运行的原因，对于诊断意外的重新规划或输入失效至关重要。将任何任务回溯证据纳入分析中。
判断编译任务是否可能阻塞实际构建耗时，还是仅消耗并行CPU时间。将所有耗时摘要类别的总秒数与实际耗时中位数进行比较：如果总和是中位数的2倍以上，大部分工作已并行化，编译热点修复不太可能减少等待时间。如果
```
SwiftCompile
```
、
```
CompileC
```
、
```
SwiftEmitModule
```
或
```
Planning Swift module
```
在耗时摘要中占主导地位，且看起来处于关键路径上，运行
```
diagnose_compilation.py
```
来捕获类型检查热点。如果它们是并行化的，仍需运行诊断，但需将发现标记为“并行效率改进”而非“构建时间改进”。
根据证据运行适合的专业分析，阅读每个技能的SKILL.md并应用其工作流：
- ```
xcode-compilation-analyzer
```
- ```
xcode-project-analyzer
```
- ```
spm-build-analysis
```
将发现的问题合并为一个单一的优先级改进计划。
使用
```
generate_optimization_report.py
```
生成Markdown格式的优化报告，并保存到
```
.build-benchmark/optimization-plan.md
```
。此报告包含构建设置审计、耗时分析、优先级建议，以及一个批准清单。
停止操作，将计划提交给开发者审核。

开发者审核

.build-benchmark/optimization-plan.md

，勾选他们希望实施的建议，然后触发阶段2。

Phase 2 -- Execute and verify (agent mode)

阶段2——执行与验证（Agent模式）

Run this phase in agent mode after the developer has reviewed and approved recommendations from the plan. Delegate all implementation work to

xcode-build-fixer

by reading its SKILL.md and applying its workflow.

Read
```
.build-benchmark/optimization-plan.md
```
and identify the approved items from the approval checklist.
Hand off to
```
xcode-build-fixer
```
with the approved plan. The fixer applies each approved change, verifies compilation, and re-benchmarks.
Append verification results to the optimization plan: post-change medians, absolute and percentage deltas, and confidence notes.
Report before and after results, plus any remaining follow-up opportunities.

在开发者审核并批准计划中的建议后，在Agent模式下运行此阶段。将所有实施工作委托给

xcode-build-fixer

，阅读其SKILL.md并应用其工作流。

读取
```
.build-benchmark/optimization-plan.md
```
，从批准清单中识别已批准的项。
将已批准的计划交给
```
xcode-build-fixer
```
。修复工具会应用每个已批准的变更，验证编译，并重新执行基准测试。
将验证结果追加到优化计划中：变更后的中位数、绝对和百分比变化值，以及可信度说明。
报告变更前后的结果，以及任何剩余的后续优化机会。

Prioritization Rules

优先级规则

The goal is to reduce how long the developer waits for builds to finish.

Identify the developer's primary pain (clean build, incremental build, or both) and the measured wall-clock median.
Determine what is likely blocking wall-clock progress:
- If the sum of all timing-summary category seconds is 2x+ the wall-clock median, most work is parallelized. Compile hotspot fixes are unlikely to reduce wait time.
- If a single serial category (e.g.
```
PhaseScriptExecution
```
  ,
```
CompileAssetCatalog
```
  ,
```
CodeSign
```
  ) accounts for a large fraction of wall-clock, that is the real bottleneck.
- If
```
Planning Swift module
```
  or
```
SwiftEmitModule
```
  dominates incremental builds, the cause is likely invalidation or module size, not individual file compile speed.
Rank recommendations by likely wall-time savings, not cumulative task reduction.
Source-level compile fixes should not outrank project/graph/configuration fixes unless evidence suggests they are on the critical path.

Prefer changes that are measurable, reversible, and low-risk.

目标是减少开发者等待构建完成的时间。

确定开发者的主要痛点（clean构建、增量构建，或两者皆是），以及测量得到的实际耗时中位数。
确定可能阻塞实际构建耗时的因素：
- 如果所有耗时摘要类别的总秒数是实际耗时中位数的2倍以上，大部分工作已并行化。编译热点修复不太可能减少等待时间。
- 如果单个串行类别（如
```
PhaseScriptExecution
```
  、
```
CompileAssetCatalog
```
  、
```
CodeSign
```
  ）占实际耗时的很大比例，那就是真正的瓶颈。
- 如果
```
Planning Swift module
```
  或
```
SwiftEmitModule
```
  在增量构建中占主导地位，原因可能是失效或模块大小，而非单个文件的编译速度。
根据预期的实际耗时节省量对建议进行排名，而非累计任务时间的减少量。
除非有证据表明源级编译修复处于关键路径上，否则其优先级不应高于项目/依赖图/配置修复。

优先选择可测量、可回滚且低风险的变更。

Recommendation Impact Language

建议影响表述

Every recommendation presented to the developer must include one of these impact statements:

"Expected to reduce your [clean/incremental] build by approximately X seconds."
"Reduces parallel compile work but is unlikely to reduce your build wait time because other tasks take equally long."
"Impact on wait time is uncertain -- re-benchmark after applying to confirm."
"No wait-time improvement expected. The benefit is [deterministic builds / faster branch switching / reduced CI cost]."
For COMPILATION_CACHING specifically: "Measured 5-14% faster clean builds across tested projects. The benefit compounds in real workflows where the cache persists between builds -- branch switching, pulling changes, and CI with persistent DerivedData."

Never quote cumulative task-time savings as the headline impact. If a change reduces 5 seconds of parallel compile work but another equally long task still runs, the developer's wait time does not change.

呈现给开发者的每一条建议都必须包含以下影响声明之一：

“预计将您的[clean/增量]构建时间减少约X秒。”
“减少并行编译工作量，但不太可能减少您的构建等待时间，因为其他任务耗时相同。”
“对等待时间的影响不确定——应用后重新执行基准测试以确认。”
“预计不会改善等待时间。收益为[确定性构建/更快的分支切换/降低CI成本]。”
针对COMPILATION_CACHING的特定表述：“在测试项目中测量到clean构建速度提升5-14%。在缓存可在构建之间持久化的真实工作流中，收益会进一步放大——分支切换、拉取变更，以及使用持久化DerivedData的CI。”

切勿将累计任务时间节省量作为主要影响。如果某项变更减少了5秒的并行编译工作量，但另一个耗时相同的任务仍在运行，开发者的等待时间不会改变。

Approval Gate

批准关卡

Before implementing anything, present a short approval list that includes:

recommendation name
expected wait-time impact (using the impact language above)
evidence summary
affected files or settings
whether the change is low, medium, or high risk

Wait for explicit developer approval.

在实施任何变更前，需呈现一个简短的批准清单，包含：

建议名称
预期的等待时间影响（使用上述影响表述）
证据摘要
受影响的文件或设置
变更的风险等级（低、中、高）

等待开发者的明确批准。

Post-Approval Execution

批准后执行

After approval, delegate to

xcode-build-fixer

the fixer implements only the approved items
changes are applied atomically and kept scoped
any deviations from the original recommendation plan are noted
the fixer re-benchmarks with the same benchmark contract

获得批准后，将任务委托给

xcode-build-fixer

：

修复工具仅实施已批准的项
变更以原子方式应用，并保持范围可控
记录任何与原始建议计划的偏差
修复工具使用相同的基准测试约定重新执行基准测试

Final Report

最终报告

Lead with the wall-clock result in plain language, e.g.: "Your clean build now takes 82s (was 86s) -- 4s faster." Then include:

baseline clean and incremental wall-clock medians
post-change clean and incremental wall-clock medians
absolute and percentage wall-clock deltas
what changed
what was intentionally left unchanged
confidence notes if noise prevents a strong conclusion -- if benchmark variance is high (min-to-max spread exceeds 20% of median), say so explicitly rather than presenting noisy numbers as definitive improvements or regressions
if cumulative task metrics improved but wall-clock did not, say plainly: "Compiler workload decreased but build wait time did not improve. This is expected when Xcode runs these tasks in parallel with other equally long work."
a ready-to-paste community results row and a link to open a PR (see the report template)

以通俗易懂的语言开头，展示实际耗时结果例如：“您的clean构建现在耗时82秒（之前为86秒）——加快了4秒。” 然后包含：

baseline的clean和增量构建实际耗时中位数
变更后的clean和增量构建实际耗时中位数
实际耗时的绝对和百分比变化值
已实施的变更
故意未实施的内容
如果噪声导致无法得出明确结论，需添加可信度说明——如果基准测试方差较高（最小值到最大值的差值超过中位数的20%），需明确说明，而非将噪声数据作为明确的改进或退化结果呈现
如果累计任务指标有所改善，但实际耗时未变，需明确说明：“编译器工作量减少，但构建等待时间未改善。这是因为Xcode在并行运行这些任务的同时，还有其他耗时相同的任务在执行，属于预期情况。”
一个可直接复制的社区结果行，以及一个用于提交PR的链接（请参阅报告模板）

Preferred Command Paths

Additional Resources

额外资源

For the report template, see references/orchestration-report-template.md
For benchmark artifact requirements, see references/benchmark-artifacts.md
For the recommendation format, see references/recommendation-format.md
For build settings best practices, see references/build-settings-best-practices.md

报告模板请参阅references/orchestration-report-template.md
基准测试工件要求请参阅references/benchmark-artifacts.md
建议格式请参阅references/recommendation-format.md
构建设置最佳实践请参阅references/build-settings-best-practices.md