xcode-project-analyzer

Xcode 專案分析器

當建置效率問題屬於專案或目標層級，且不太可能僅靠原始碼編輯解決時，使用此技能。

核心規則

• 預設以建議為優先。
• 在變更專案檔案、Scheme 或建置設定前，需取得明確核准。
• 偏好以實測結果為依據，並搭配時間摘要、建置記錄或專案設定證據。
• 區分僅在 Debug 模式出現的問題與僅在 Release 模式出現的問題。

應審查項目

• Scheme 建置順序與目標相依性
• Debug 與 Release 建置設定是否符合建置設定最佳實務
• Run Script Phase 與相依性分析設定
• Derived Data 頻繁變動或明顯導致失效的自訂步驟
• 平行化機會
• 明確的模組相依性設定與模組對應就緒狀態
• 建置時間摘要中的「Planning Swift module」時間——若在增量建置中佔主導，懷疑非預期的輸入修改或巨集相關失效
• Asset Catalog 編譯時間，特別是目標包含大量或大型目錄時
• 建置時間摘要中的 ExtractAppIntentsMetadata 時間——若此階段耗時顯著，記錄為 xcode-behavior（回報成本與影響，但除非有明確的 Apple 指引，否則不建議在儲存庫內進行最佳化）
• 零變更建置的開銷——若無操作重建超過數秒，調查固定成本階段（Script 執行、Code Sign、驗證、CopySwiftLibs）
• CocoaPods 使用情況——若存在 Podfile 或 Pods.xcodeproj，表示 CocoaPods 已棄用；建議遷移至 SPM，且不要嘗試 CocoaPods 特定的最佳化（參見 project-audit-checks.md）
• Task Backtraces（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」建置
• Run Script 宣告輸入與輸出
• 當 Script 有大量輸入或輸出時，使用 .xcfilelist 檔案
• 在自訂 Framework 或 Library 應暴露模組對應時啟用 DEFINES_MODULE
• Header 足夠自包含以支援模組對應使用
• 對於應共享模組的目標，明確的模組相依性設定保持一致

典型改善項目

• 跳過僅在 Release 有意義的 Debug 階段 Script
• 新增遺漏的 Script 防護或相依性分析中繼資料
• 移除 Scheme 中意外的序列瓶頸
• 對齊導致不必要模組變體的建置設定
• 修正迫使比必要範圍更廣重建的過時專案結構
• 識別會修改檔案時間戳記但未變更內容的 Linter 或 Formatter，無聲地使建置輸入失效並強制模組重新規劃
• 將大型 Asset Catalog 拆分為跨目標的獨立資源 Bundle，以平行化編譯
• 使用 Task Backtraces 精確定位觸發非必要增量工作的輸入變更

回報格式

針對每個問題，包含：

• 證據
• 可能影響範圍
• 為何影響乾淨建置、增量建置或兩者
• 預估影響
• 核准要求

若證據指向 Package Graph 或建置 Plugin，請閱讀 spm-build-analysis 的 SKILL.md，並將其工作流程套用至相同專案上下文，然後移交處理。

其他資源

• 詳細稽核檢查清單請參見 references/project-audit-checks.md
• 建置設定最佳實務請參見 references/build-settings-best-practices.md
• 共用建議結構請參見 references/recommendation-format.md
• Apple 對齊的來源摘要請參見 references/build-optimization-sources.md