企业官网建设流程全解析

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]

各参数含义如下：

虽然本文档以行为规范形式定义这些参数（命令本质是 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 五步，构成一条完整且可审计的清理闭环：

1. Analyze（分析）：在目标范围内评估清理机会与安全考量，识别死代码、无用导入、空块、冗余类型标注等清理点；
2. Plan（规划）：选择清理策略（保守/彻底、交互/自动），并按清理类型激活对应 persona 提供领域专业判断；
3. Execute（执行）：通过智能死代码检测与依赖校验，系统性应用清理操作；
4. Validate（验证）：通过测试与安全检查确保功能零损失；
5. Report（报告）：生成清理摘要，并给出后续维护建议。

关键行为还包括三点：基于清理类型的多 persona 协调；通过 Context7 MCP 获取框架特定清理模式；通过 Sequential MCP 对复杂清理操作进行系统性分析。整体秉持安全优先，具备备份与回滚能力。

MCP 集成与 Persona 协调

清理命令在 frontmatter 中声明依赖mcp-servers: [sequential, context7]，与personas: [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