Back to Details

xcode-project-analyzer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Xcode Project Analyzer

Xcode 项目分析器

Use this skill for project- and target-level build inefficiencies that are unlikely to be solved by source edits alone.
当项目或目标层面存在仅通过修改源代码无法解决的构建效率问题时，可使用此Skill。

Core Rules

核心规则

  • Recommendation-first by default.
  • Require explicit approval before changing project files, schemes, or build settings.
  • Prefer measured findings tied to timing summaries, build logs, or project configuration evidence.
  • Distinguish debug-only pain from release-only pain.
  • 默认以给出优化建议为首要原则。
  • 修改项目文件、Scheme或构建设置前，需获得明确审批。
  • 优先提供有构建时间汇总、构建日志或项目配置证据支撑的量化结论。
  • 区分仅在Debug环境下出现的问题与仅在Release环境下出现的问题。

What To Review

审核范围

  • scheme build order and target dependencies
  • debug vs release build settings against the build settings best practices
  • run script phases and dependency-analysis settings
  • derived-data churn or obviously invalidating custom steps
  • opportunities for parallelization
  • explicit module dependency settings and module-map readiness
  • "Planning Swift module" time in the Build Timing Summary -- if it dominates incremental builds, suspect unexpected input modification or macro-related invalidation
  • asset catalog compilation time, especially in targets with large or numerous catalogs
  • ExtractAppIntentsMetadata
    time in the Build Timing Summary -- if this phase consumes significant time, record it as 
    xcode-behavior
    (report the cost and impact, but do not suggest a repo-local optimization unless there is explicit Apple guidance)
  • zero-change build overhead -- if a no-op rebuild exceeds a few seconds, investigate fixed-cost phases (script execution, codesign, validation, CopySwiftLibs)
  • CocoaPods usage -- if a 
    Podfile
    or 
    Pods.xcodeproj
    exists, CocoaPods is deprecated; recommend migrating to SPM and do not attempt CocoaPods-specific optimizations (see project-audit-checks.md)
  • Task Backtraces (Xcode 16.4+: Scheme Editor > Build > Build Debugging) to diagnose why tasks re-run unexpectedly in incremental builds
  • Scheme的构建顺序与目标依赖关系
  • Debug与Release构建设置与构建设置最佳实践的对比
  • 运行脚本阶段与依赖分析设置
  • Derived Data的频繁更新或明显会导致构建失效的自定义步骤
  • 并行构建的优化机会
  • 显式模块依赖设置与module-map就绪情况
  • 构建时间汇总中的「Planning Swift module」耗时——如果该阶段在增量构建中占比过高，需排查是否存在意外的输入修改或宏相关的构建失效问题
  • 资源目录编译耗时，尤其是包含大量或大型资源目录的目标
  • 构建时间汇总中的
    ExtractAppIntentsMetadata
    耗时——如果该阶段耗时占比较大，记录为
    xcode-behavior
    （需报告其成本与影响，但除非有Apple官方指导，否则不建议在仓库内进行本地优化）
  • 无变更时的构建开销——如果无操作重建耗时超过数秒，需排查固定成本阶段（脚本执行、签名、验证、CopySwiftLibs）
  • CocoaPods使用情况——如果项目中存在
    Podfile
    或
    Pods.xcodeproj
    ，说明仍在使用已被弃用的CocoaPods；建议迁移至SPM，且不尝试针对CocoaPods的特定优化（详见project-audit-checks.md）
  • Task Backtraces（Xcode 16.4+：Scheme编辑器 > 构建 > 构建调试），用于诊断增量构建中任务意外重新运行的原因

Build Settings Best Practices Audit

构建设置最佳实践审核

Every project audit should include a build settings checklist comparing the project's Debug and Release configurations against the recommended values in build-settings-best-practices.md. Present results using checkmark/cross indicators (
[x]
/
[ ]
). The scope is strictly build performance -- do not flag language-migration settings like 
SWIFT_STRICT_CONCURRENCY
or 
SWIFT_UPCOMING_FEATURE_*
.
每个项目审核都应包含一份构建设置检查清单，将项目的Debug和Release配置与build-settings-best-practices.md中的推荐值进行对比。使用勾选/未勾选标识（
[x]
/
[ ]
）展示结果。检查范围严格限定为构建性能相关设置——请勿标记
SWIFT_STRICT_CONCURRENCY
或
SWIFT_UPCOMING_FEATURE_*
等语言迁移类设置。

Apple-Derived Checks

Apple 官方衍生检查项

Review these items in every audit:
  • target dependencies are accurate and not missing or inflated
  • schemes build in 
    Dependency Order
  • run scripts declare inputs and outputs
  • .xcfilelist
    files are used when scripts have many inputs or outputs
  • DEFINES_MODULE
    is enabled where custom frameworks or libraries should expose module maps
  • headers are self-contained enough for module-map use
  • explicit module dependency settings are consistent for targets that should share modules
每次审核都需检查以下内容：
  • 目标依赖关系准确无误，无缺失或冗余
  • Scheme按照「依赖顺序」进行构建
  • 运行脚本声明了输入与输出
  • 当脚本包含大量输入或输出时，使用
    .xcfilelist
    文件
  • 在需要暴露module map的自定义框架或库中启用
    DEFINES_MODULE
  • 头文件具备足够的自包含性，以支持module map的使用
  • 对于应共享模块的目标，其显式模块依赖设置保持一致

Typical Wins

常见优化成果

  • skip debug-time scripts that only matter in release
  • add missing script guards or dependency-analysis metadata
  • remove accidental serial bottlenecks in schemes
  • align build settings that cause unnecessary module variants
  • fix stale project structure that forces broader rebuilds than necessary
  • identify linters or formatters that touch file timestamps without changing content, silently invalidating build inputs and forcing module replanning
  • split large asset catalogs into separate resource bundles across targets to parallelize compilation
  • use Task Backtraces to pinpoint the exact input change that triggers unnecessary incremental work
  • 跳过仅在Release环境下生效的Debug阶段脚本
  • 添加缺失的脚本防护或依赖分析元数据
  • 移除Scheme中意外存在的串行瓶颈
  • 调整构建设置，避免产生不必要的模块变体
  • 修复陈旧的项目结构，避免触发超出必要范围的重建
  • 识别出仅修改文件时间戳但未改变内容的代码检查器或格式化工具，这类工具会无声地使构建输入失效，从而触发模块重规划
  • 将大型资源目录拆分为多个目标下的独立资源包，以并行编译
  • 使用Task Backtraces定位导致不必要增量构建的具体输入变更

Reporting Format

报告格式

For each issue, include:
  • evidence
  • likely scope
  • why it affects clean builds, incremental builds, or both
  • estimated impact
  • approval requirement
If the evidence points to package graph or build plugins, hand off to 
spm-build-analysis
 by reading its SKILL.md and applying its workflow to the same project context.
针对每个问题，需包含以下内容：
  • 问题证据
  • 可能影响的范围
  • 为何会影响全量构建、增量构建，或两者均受影响
  • 预估影响程度
  • 是否需要审批
如果证据指向包依赖图或构建插件，需移交至
spm-build-analysis
，请阅读其SKILL.md并将其工作流应用于相同的项目环境中。

Additional Resources

额外资源

  • For the detailed audit checklist, see references/project-audit-checks.md
  • For build settings best practices, see references/build-settings-best-practices.md
  • For the shared recommendation structure, see references/recommendation-format.md
  • For Apple-aligned source summaries, see references/build-optimization-sources.md
  • 详细审核清单请参考references/project-audit-checks.md
  • 构建设置最佳实践请参考references/build-settings-best-practices.md
  • 统一建议格式请参考references/recommendation-format.md
  • Apple官方构建优化资料请参考references/build-optimization-sources.md