SuperClaude Framework 的 /sc:cleanup 命令系统性代码清理与项目结构优化的安全实践指南【免费下载链接】SuperClaude_FrameworkA configuration framework that enhances Claude Code with specialized commands, cognitive personas, and development methodologies.项目地址: https://gitcode.com/gh_mirrors/su/SuperClaude_Framework/sc:cleanup是 SuperClaude Framework 提供的 workflow 类斜杠命令用于系统化清理代码、移除死代码并优化项目结构是技术债治理与代码卫生维护的核心入口。本文以 cleanup.md 为骨架结合仓库源码与既有脚本完整讲解其命令语法、行为流程、MCP/Persona 协作机制、安全分级策略与实战用法帮助你在 Claude Code 中安全、可控地执行从保守清理到全面重构的各类清理任务。命令定位与安装方式/sc:cleanup属于 SuperClaude 的 workflow 类命令frontmatter 中category: workflow、complexity: standard其 Markdown 定义文件位于 src/superclaude/commands/cleanup.md同时在 plugins/superclaude/commands/cleanup.md 保留了一份同步副本。依据 commands/README.md两个位置的命令文件必须保持同步编辑时以plugins/下为准、再复制到src/下用于打包分发。该命令与所有 SuperClaude 命令一样通过superclaude install安装到~/.claude/commands/sc/目录并以/sc:命名空间调用。安装逻辑由 src/superclaude/cli/install_commands.py 实现安装器会扫描命令源目录中的全部*.md文件跳过 README逐个复制到目标目录已存在且未加--force的命令会被跳过。命令源目录的解析遵循两级优先级优先取已安装包内的superclaude/commands/其次取仓库根目录下的plugins/superclaude/commands/。CLI 入口src/superclaude/cli/main.py提供了三种常用操作方式superclaude install # 安装全部命令到 ~/.claude/commands/sc superclaude install --list # 列出可用命令与安装状态 superclaude update # 等价于 install --force强制覆盖更新安装完成后需重启 Claude Code 使新命令生效sc.md 中亦有此提示。安装细节可参考 tests/unit/test_cli_install.py 中的单元测试。触发场景文档定义的触发条件覆盖了日常开发中四类典型诉求代码维护与技术债削减请求当代码库积累了历史遗留问题、重复实现或过时逻辑时死代码移除与导入优化需求存在未被引用的函数、类、模块或无用 import 时项目结构改进与组织优化要求目录划分不合理、模块边界模糊、文件归属混乱时代码卫生与质量提升倡议团队级代码质量治理、发布前卫生检查等场景。需要说明的是清理工作往往是主动预防而非被动救火——文档在 frontmatter 中声明该命令可触发 architect、quality、security 三类 persona 的协作即默认将清理视为涉及架构、质量与安全的多维工程活动。命令语法与参数解析/sc:cleanup的完整语法为/sc:cleanup [target] [--type code|imports|files|all] [--safe|--aggressive] [--interactive]各参数含义如下参数取值含义target路径清理目标范围如src/、components/缺省时作用于整个项目--typecode/imports/files/all清理类型代码死逻辑、无用导入、文件结构或全部--safe—保守模式自动安全验证优先任何有使用路径的代码均提示用户--aggressive—彻底模式结合框架特定模式做深度清理配合 Context7--interactive—交互模式复杂决策交由用户确认--preview—预览模式仅分析展示清理项而不实际执行见示例二虽然本文档以行为规范形式定义这些参数命令本质是 Claude Code 的 slash command由 Agent 依据 frontmatter 与正文解释执行但仓库的 FLAGS.md 提供了配套的执行控制标志可进一步细化清理时的运行约束--safe-mode资源占用超过 85%、生产环境或关键操作时自动启用执行最大程度验证与保守策略--validate风险评分 0.7 时前置执行风险评估与验证门禁--scope [file|module|project|system]限定清理分析边界--concurrency [n]控制并行操作数1-15用于大规模多文件清理--delegate [auto|files|folders]超过 7 个目录或 50 个文件时可委派子 Agent 并行处理。FLAGS.md 中的优先级规则同样适用于清理任务--safe-mode优先于--validate优先于各类优化标志用户显式传入的标志优先于自动检测作用域按system project module file递进。五阶段行为流程文档规定的执行流程为 Analyze → Plan → Execute → Validate → Report 五步构成一条完整且可审计的清理闭环Analyze分析在目标范围内评估清理机会与安全考量识别死代码、无用导入、空块、冗余类型标注等清理点Plan规划选择清理策略保守/彻底、交互/自动并按清理类型激活对应 persona 提供领域专业判断Execute执行通过智能死代码检测与依赖校验系统性应用清理操作Validate验证通过测试与安全检查确保功能零损失Report报告生成清理摘要并给出后续维护建议。关键行为还包括三点基于清理类型的多 persona 协调通过 Context7 MCP 获取框架特定清理模式通过 Sequential MCP 对复杂清理操作进行系统性分析。整体秉持安全优先具备备份与回滚能力。MCP 集成与 Persona 协调清理命令在 frontmatter 中声明依赖mcp-servers: [sequential, context7]与personas: [architect, quality, security]对应集成项职责Sequential MCP对复杂多步骤清理进行结构化推理与规划自动激活Context7 MCP提供框架特定的清理模式与最佳实践如框架约定下的依赖处理方式Architect架构师负责结构维度组件边界、依赖关系、模块划分Quality质量工程师负责债务维度覆盖率、回归风险、清理后的质量验证Security安全工程师负责凭据维度清理过程中识别并保护硬编码密钥、敏感配置Persona 定义文件分别为 system-architect.md、quality-engineer.md 与 security-engineer.md位于 src/superclaude/agents/ 目录。例如 system-architect 强调组件边界与依赖管理在结构清理中负责判断文件去留对耦合度的影响quality-engineer 关注超越 happy path 发现隐藏失败模式在清理后验证阶段负责评估功能回归风险。从命令分发机制看这些 persona 通过superclaude install一并安装至~/.claude/agents/在 Claude Code 中可直接调用install_commands.py 的install_agents函数负责此过程。工具协调文档明确规定了清理流程中使用的原生工具组合Read / Grep / Glob代码分析与模式检测用于发现死代码、未引用符号与结构问题Edit / MultiEdit安全地修改代码与优化结构MultiEdit 适合多文件批量修改TodoWrite对复杂多文件清理任务进行进度追踪Task将大规模清理工作流委派给子任务实现系统性协调。这套组合与仓库执行引擎的设计思路一致src/superclaude/execution/下的 parallel、reflection、self_correction 模块见 src/superclaude/execution/为多工具并行与自我修正提供了底层支撑可推断清理任务在复杂场景下同样能受益于并行执行与反思机制。四大核心清理模式文档归纳了清理任务中反复出现的四种模式Dead Code Detection死代码检测使用分析 → 依赖校验 → 安全移除。先通过 Grep/Glob 建立符号引用图确认零引用后再删除Import Optimization导入优化依赖分析 → 无用导入移除与整理。需注意框架约定如某些框架的 index/barrel 文件导出不可轻易删除Structure Cleanup结构清理架构分析 → 文件组织与模块化改进。由 Architect persona 主导边界判定Safety Validation安全验证清理前/中/后三重检查确保整个清理过程功能无损。对应五阶段流程中的 Validate 步骤。实战示例以下四个示例完整继承自原文档覆盖从保守到彻底、从单域到全量的典型用法安全代码清理保守模式/sc:cleanup src/ --type code --safe # Conservative cleanup with automatic safety validation # Removes dead code while preserving all functionality对src/目录执行保守代码清理自动安全验证只移除确定无引用的死代码保证功能完全保留。导入优化预览模式/sc:cleanup --type imports --preview # Analyzes and shows unused import cleanup without execution # Framework-aware optimization via Context7 patterns仅分析并展示无用导入的清理方案不实际执行依赖 Context7 模式实现框架感知的优化建议。预览模式适合先审后改。全面项目清理交互模式/sc:cleanup --type all --interactive # Multi-domain cleanup with user guidance for complex decisions # Activates all personas for comprehensive analysis跨域代码导入文件全面清理复杂决策交由用户确认同时激活全部三类 persona 做综合分析。框架特定深度清理彻底模式/sc:cleanup components/ --aggressive # Thorough cleanup with Context7 framework patterns # Sequential analysis for complex dependency management对components/目录执行彻底清理借助 Context7 的框架模式与 Sequential 的复杂依赖分析适合处理依赖关系密集的模块。边界声明Will会做系统化清理代码、移除死代码、优化项目结构提供包含备份与回滚能力的全面安全验证应用智能清理算法与框架特定模式识别。Will Not不会做未经彻底安全分析与验证即移除代码覆盖项目特定的清理排除项或架构约束执行任何以牺牲功能或引入 bug 为代价的清理操作。自动修复与审批分级安全阈值机制这是/sc:cleanup安全设计的核心文档明确划分了可自动执行与必须人工确认的两类操作Auto-fix自动应用无用导入移除零引用的死代码空块移除冗余类型标注。Approval Required先询问用户存在间接引用的代码可能被外部使用的导出测试夹具fixtures与测试工具函数配置值。安全阈值代码存在任何使用路径 → 提示用户影响公共 API → 提示用户不确定 → 提示用户。这条Any usage path → prompt的兜底原则确保了清理操作的保守底线。从仓库实现看该原则与 FLAGS.md 中--safe-mode、--validate的生产环境与高风险操作自动降速设计一脉相承构成了从命令级到标志级的双层安全护栏。与仓库既有清理脚本的互补除 Agent 驱动的/sc:cleanup外仓库还提供了脚本层面的清理工具 scripts/cleanup.sh二者形成互补脚本针对构建产物与缓存文件__pycache__、*.pyc、build/、dist/、.pytest_cache/、.mypy_cache/、.DS_Store等属于环境卫生层而/sc:cleanup针对源代码本身死代码、无用导入、结构优化属于代码卫生层。生产实践中可以组合使用先用脚本清除机器生成物再用命令治理源码技术债。总结/sc:cleanup以分析-规划-执行-验证-报告五阶段流程为骨架以自动修复/人工审批分级与Any usage path → prompt安全阈值为核心护栏借助 Sequential/Context7 两个 MCP 与 architect/quality/security 三类 persona 实现框架感知、多域协作的清理能力。配合 FLAGS.md 的--safe-mode、--validate、--scope、--concurrency等执行控制标志你可以将清理任务精确控制在保守单文件与彻底全项目之间的任意档位在消除技术债的同时守住功能完整性与代码质量的底线。【免费下载链接】SuperClaude_FrameworkA configuration framework that enhances Claude Code with specialized commands, cognitive personas, and development methodologies.项目地址: https://gitcode.com/gh_mirrors/su/SuperClaude_Framework创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考