xcode-project-analyzer

Xcode 项目分析器

使用此技能处理项目级和目标级的构建低效问题，这些问题不太可能仅通过源代码编辑解决。

核心规则

• 默认以建议优先。
• 在更改项目文件、Scheme 或构建设置之前，需要明确的审批。
• 优先选择与时间摘要、构建日志或项目配置证据相关的可测量发现。
• 区分仅调试环境的问题和仅发布环境的问题。

审查内容

• Scheme 构建顺序和目标依赖
• 调试与发布构建设置，对照构建设置最佳实践
• 运行脚本阶段和依赖分析设置
• DerivedData 变动或明显无效的自定义步骤
• 并行化机会
• 显式模块依赖设置和模块映射就绪状态
• 构建时间摘要中的“Planning Swift module”时间——如果它在增量构建中占主导地位，怀疑意外的输入修改或宏相关的失效
• 资源目录编译时间，特别是目标包含大量或众多目录时
• 构建时间摘要中的 ExtractAppIntentsMetadata 时间——如果此阶段消耗大量时间，记录为 xcode-behavior（报告成本和影响，但除非有明确的 Apple 指南，否则不建议进行仓库本地优化）
• 零变更构建开销——如果无操作重建超过几秒，调查固定成本阶段（脚本执行、代码签名、验证、CopySwiftLibs）
• CocoaPods 使用——如果存在 Podfile 或 Pods.xcodeproj，则 CocoaPods 已弃用；建议迁移到 SPM，并且不要尝试 CocoaPods 特定的优化（参见 project-audit-checks.md）
• 任务回溯（Xcode 16.4+：Scheme Editor > Build > Build Debugging）以诊断增量构建中任务意外重新运行的原因

构建设置最佳实践审计

每个项目审计都应包含一个构建设置检查清单，将项目的 Debug 和 Release 配置与 build-settings-best-practices.md 中的推荐值进行比较。使用对勾/叉号指示符（[x]/[ ]）呈现结果。范围严格限于构建性能——不要标记语言迁移设置，如 SWIFT_STRICT_CONCURRENCY 或 SWIFT_UPCOMING_FEATURE_*。

Apple 衍生检查

每次审计中审查以下项目：

• 目标依赖准确，没有缺失或膨胀
• Scheme 按 Dependency Order 构建
• 运行脚本声明输入和输出
• 当脚本有大量输入或输出时使用 .xcfilelist 文件
• 在自定义框架或库应暴露模块映射时启用 DEFINES_MODULE
• 头文件足够自包含以用于模块映射
• 对于应共享模块的目标，显式模块依赖设置一致

典型收益

• 跳过仅在发布环境中重要的调试时脚本
• 添加缺失的脚本保护或依赖分析元数据
• 移除 Scheme 中意外的串行瓶颈
• 对齐导致不必要模块变体的构建设置
• 修复导致比必要更广泛重建的陈旧项目结构
• 识别那些修改文件时间戳但不改变内容的 linter 或格式化工具，静默地使构建输入失效并强制模块重新规划
• 将大型资源目录拆分为跨目标的单独资源包以并行编译
• 使用任务回溯精确定位触发不必要增量工作的确切输入更改

报告格式

对于每个问题，包括：

• 证据
• 可能的影响范围
• 为什么影响干净构建、增量构建或两者
• 估计影响
• 审批要求

如果证据指向包图或构建插件，则通过读取其 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