在优化 Xcode 构建速度前，用可复现的…

当开发者想测量 Xcode 构建耗时、建立基线或对比改动前后构建快慢时，用统一输入和带时间戳的产物做可复现基准测试。

适用场景

解决思路

1. 先测量再建议改动，不要在没有基线的情况下推荐优化。
2. 分别捕获 clean build 和 incremental build 的数据。
3. 跨多次运行保持命令、destination、configuration、scheme 和 warm-up 规则一致。
4. 将带时间戳的 JSON 产物写入 `.build-benchmark/`。
5. 基准测试过程中不要修改项目文件。
6. 确认或推断以下输入：workspace 或 project 路径、scheme、configuration、destination、用户想要模拟器还是真机数据、是否需要自定义 `DerivedData` 路径。
7. 如果项目同时存在 clean build 和 incremental build 的痛点，两者都测，这是默认做法。
8. 在 git worktree 中做基准测试时，若 SPM 包的 `exclude:` 路径引用了被 gitignore 的目录（如 `__Snapshots__`），会导致 `xcodebuild -resolvePackageDependencies` 崩溃；在运行任何构建前先创建这些缺失目录。
9. 规范化构建命令，并记录所有影响缓存或模块复用的 flag。
10. 如有需要，先跑一次 warm-up build 验证命令能成功执行。
11. 运行 3 次 clean build。
12. 如果检测到 `COMPILATION_CACHE_ENABLE_CACHING = YES`，运行 3 次 cached clean build：先构建一次预热缓存，然后在每次测量前删除 DerivedData（但不删除 compilation cache）；这衡量的是分支切换、拉取改动或 Clean Build Folder 时的真实场景；传 `--no-cached-clean` 可跳过。
13. 运行 3 次 zero-change build（在一次成功构建后不做任何编辑立即再构建），衡量固定开销下限：依赖计算、项目描述传输、构建描述创建、脚本阶段、签名和校验；若 zero-change build 超过几秒，说明存在可避免的每次构建开销；使用默认的 `benchmark_builds.py` 调用（不加 `--touch-file` flag）。
14. 可选：运行 3 次带文件 touch 的 incremental build，衡量真实的编辑-重建循环；用 `--touch-file path/to/SomeFile.swift` 在每次构建前 touch 一个有代表性的源文件。
15. 将原始结果和摘要保存到 `.build-benchmark/`。
16. 报告 median 和 spread，而不只是最快的一次运行。
17. 尽量使用共享 helper：`python3 scripts/benchmark_builds.py --workspace App.xcworkspace --scheme MyApp --configuration Debug --destination "platform=iOS Simulator,name=iPhone 16" --output-dir .build-benchmark`。
18. 如果无法使用 helper 脚本，用等价的 `xcodebuild` 命令并加 `-showBuildTimingSummary`，保留原始输出。
19. 返回：clean build 的 median/min/max；cached clean build 的 median/min/max（当启用 COMPILATION_CACHE_ENABLE_CACHING 时）；zero-change build 的 median/min/max（固定开销下限）；incremental build 的 median/min/max（若用了 `--touch-file`）；最大的 timing-summary 类别；可能影响对比的环境细节；保存产物的路径。
20. 如果结果噪声较大，明确说明并建议在更稳定的条件下重跑。
21. 如果用户只要求基准测试，测量完就停止；若需要优化指导，读取相关 specialist 的 SKILL.md 并在同一项目上下文应用其工作流：`xcode-compilation-analyzer`、`xcode-project-analyzer`、`spm-build-analysis`，或用 `xcode-build-orchestrator` 做完整编排。
22. 参考资源：benchmark 契约见 `references/benchmarking-workflow.md`，共享产物格式见 `references/benchmark-artifacts.md`，JSON schema 见 `schemas/build-benchmark.schema.json`。

适用边界 · 注意事项

• 用户只想要优化建议而不需要测量基线时，不应只做基准测试而不交付优化指导。
• 在 git worktree 中未先创建被 gitignore 的 `exclude:` 目录时，不要运行构建，否则 `xcodebuild -resolvePackageDependencies` 会崩溃。
• 基准测试过程中不要修改项目文件，否则会破坏可复现性。