xcode-project-analyzer

Xcode 项目分析器

当仅靠修改源代码不太可能解决项目和目标级构建低效问题时，使用此技能。

核心规则

• 默认优先提供建议。
• 更改项目文件、方案或构建设置前，必须获得明确批准。
• 优先提供与计时摘要、构建日志或项目配置证据相关的实测发现。
• 区分仅影响调试版的问题和仅影响发布版的问题。

审查内容

• 方案构建顺序和目标依赖项
• 调试版与发布版构建设置是否符合构建设置最佳实践
• 运行脚本阶段和依赖项分析设置
• 派生数据反复变动，或明显会导致失效的自定义步骤
• 并行化机会
• 显式模块依赖项设置和模块映射就绪情况
• 构建计时摘要中的“Planning Swift module”耗时——如果它在增量构建中占主导，应怀疑是否有意外的输入修改或宏相关失效
• 资源目录编译耗时，尤其是包含大量或多个目录的目标
• 构建计时摘要中的 ExtractAppIntentsMetadata 耗时——如果此阶段耗时显著，应将其记录为 xcode-behavior（报告耗时和影响，但除非有明确的 Apple 指引，否则不要建议在仓库本地进行优化）
• 零变更构建开销——如果无操作重建耗时超过几秒，应调查固定开销阶段（脚本执行、代码签名、验证、CopySwiftLibs）
• CocoaPods 用法——如果存在 Podfile 或 Pods.xcodeproj，则 CocoaPods 已弃用；建议迁移到 SPM，不要尝试进行 CocoaPods 专属优化（参见 project-audit-checks.md）
• 任务回溯（Xcode 16.4+：方案编辑器 > 构建 > 构建调试），用于诊断增量构建中任务意外重新运行的原因

构建设置最佳实践审计

每次项目审计都应包含构建设置检查清单，将项目的调试版和发布版配置与 build-settings-best-practices.md 中的建议值进行比较。使用勾选/叉号标记（[x]/[ ]）呈现结果。审查范围严格限于构建性能——不要标记 SWIFT_STRICT_CONCURRENCY 或 SWIFT_UPCOMING_FEATURE_* 等语言迁移设置。

基于 Apple 指引的检查项

每次审计都应审查以下项目：

• 目标依赖项准确无误，既无缺失也无冗余
• 方案按 Dependency Order 构建
• 运行脚本声明了输入和输出
• 脚本有大量输入或输出时使用 .xcfilelist 文件
• 自定义框架或库需要公开模块映射时，启用 DEFINES_MODULE
• 头文件足够独立，可用于模块映射
• 需要共享模块的目标，其显式模块依赖项设置保持一致

常见收益

• 跳过仅对发布版有意义的调试时脚本
• 添加缺失的脚本保护条件或依赖项分析元数据
• 消除方案中意外的串行瓶颈
• 调整会造成不必要模块变体的构建设置
• 修复过时的项目结构，避免不必要的广泛重建
• 找出不会更改内容、却会触碰文件时间戳的代码检查工具或格式化工具；它们会悄然使构建输入失效并迫使模块重新规划
• 将大型资源目录拆分到不同目标的独立资源包中，以并行编译
• 使用任务回溯找出触发不必要增量工作的确切输入变更

报告格式

针对每个问题，包含：

• 证据
• 可能的影响范围
• 对干净构建、增量构建或两者造成影响的原因
• 预估影响
• 是否需要批准

如果证据指向包依赖图或构建插件，请阅读其 SKILL.md，并按照 spm-build-analysis 的工作流，在同一项目上下文中继续分析。

其他资源

• 详细的审计清单请参阅 references/project-audit-checks.md
• 构建设置最佳实践请参阅 references/build-settings-best-practices.md
• 共享的建议结构请参阅 references/recommendation-format.md
• 与 Apple 指南一致的源代码摘要请参阅 references/build-optimization-sources.md