该技能用于协调通过 destructiveChanges 清单从 Salesforce 组织删除元数据,流程分为三阶段:范围界定 → 验证 → 执行,生产环境有更严格防护。
范围界定阶段:先向用户确认或推断要删除的组件,记录元数据类型(如 CustomObject、CustomField、ApexClass、Flow、PermissionSet)和 API 名称。随后对 force-app/ 做本地依赖扫描(grep -rn "<componentApiName>" force-app/ --include='.cls' --include='.trigger' --include='.xml' --include='.js' --include='*.html'),若发现引用则列出并建议先更新引用或一并删除,不得静默继续。接着生成 destructiveChanges.xml 写到 manifest/destructiveChangesPre.xml 或 destructiveChangesPost.xml,按元数据类型分组,版本使用 sfdx-project.json 的 sourceApiVersion;命名空间字段用 Object.Field 写法。
验证阶段:执行前必须验证,例如 sf project deploy validate --pre-destructive-changes manifest/destructiveChangesPre.xml --manifest manifest/package.xml --target-org <alias> --test-level RunLocalTests --json。若缺 package.xml 需创建空描述文件。验证失败须报错并停止,常见原因包括仍被 Apex/Flow/Layout 引用、许可证依赖、权限不足。
执行阶段:先确认目标是否为生产环境,可用 "${CLAUDE_PLUGIN_ROOT}/scripts/sf-deploy-gate" bucket <alias> 检查,返回 production|sandbox|scratch|trial|unknown。生产环境需显示破坏性确认横幅、列出所有将删除组件、要求明确输入确认,且 PreToolUse 钩子会拦截针对生产的裸破坏性命令。沙箱/Scratch 执行示例:sf project deploy start --pre-destructive-changes manifest/destructiveChangesPre.xml --manifest manifest/package.xml --target-org <alias> --json --wait 30;仅当用户明确要求永久删除时才加 --purge-on-delete。
删除后建议清理本地源文件(rm -rf force-app/main/default/<path-to-component>),提醒字段数据会丢失或暂存回收站,并建议运行测试确认无运行时回归。规则包括:始终先验证、始终扫描本地引用、生产必须显式确认、不得擅自加 --purge-on-delete、破坏性部署不得用 --ignore-errors、使用 sfdx-project.json 的 API 版本;删除 required="true" 或用于 RecordType 选项列表值的字段时,须先说明级联影响。