swiftfindrefs

SwiftFindRefs 是一个专为 Swift 代码库重构与维护设计的辅助技能，通过调用 swiftfindrefs CLI 工具查询 Xcode 的 IndexStoreDB（DerivedData），精准定位跨模块的符号引用关系，弥补传统文本搜索的不足。

核心用法方面，该技能强制要求在使用 grep、rg 或 IDE 搜索之前，先通过命令行工具查询索引数据库。用户需提供项目名称、符号名称及类型（类、结构体、枚举、协议、函数或变量），工具将返回所有引用该符号的绝对文件路径列表。该流程特别适用于"查找引用"、"修复缺失导入"和"跨模块重构"三大场景，确保不会遗漏任何隐性依赖。输出结果可直接用于管道处理，方便集成到自动化脚本中。

显著优点在于其精准性与可靠性。不同于文本搜索可能带来的大量误报或上下文遗漏，该工具直接读取 Xcode 构建时生成的语义索引数据，能够准确识别真正的符号引用关系，包括跨模块的复杂依赖。对于大型 Swift 项目，这能有效防止因重构不彻底导致的编译错误或运行时异常，是执行删除、重命名或移动符号前的必要审计手段。

潜在缺点与局限性主要包括严格的平台限制和前置条件。首先，该工具仅支持 macOS 且必须安装 Xcode，无法在其他操作系统或纯 Swift Package Manager 无 Xcode 环境中使用。其次，项目必须至少完成一次构建以生成 DerivedData，否则索引数据库不存在。此外，工具输出仅提供文件路径列表而不包含具体的行号或列号信息，对于需要精确定位的场景可能需要配合其他工具二次处理。来源方面，该工具由个人开发者维护，长期维护稳定性存在不确定性。

适合的目标群体主要是从事中大型 Swift 项目开发的工程师，特别是需要进行 API 迁移、模块重构、代码清理或负责维护遗留代码库的开发者。对于频繁进行跨模块重命名、删除公有 API 或调整模块边界的团队，该技能能显著降低回归风险，确保重构的完整性。

使用风险方面，虽然该技能本身仅为纯文档型资产，无代码执行风险，但其依赖的外部 CLI 工具通过 Homebrew 从个人 GitHub 仓库分发（T3 来源）。建议在生产环境大规模使用前审查该开源工具的源码安全性。此外，该工具仅读取索引数据不会直接修改源码，但基于其结果进行的人工编辑操作仍需谨慎，建议配合单元测试验证重构结果。性能方面，查询大型项目的索引可能存在短暂的 I/O 延迟。