slop-cleaner

name: slop-cleaner description: > 自动化代码卫生扫描——识别大文件、死代码、测试与实现混合、架构坏味道等结构性问题， 产出结构化清扫报告和终端摘要。偏自动化批量扫描，非深度 code review。 当用户说"扫一下 slop"、"清理代码卫生"、"检查代码质量"、 "找找死代码"、"哪些文件太大了"、"测试混在源码里"、"架构有没有问题"、"代码有没有坏味道"、 "slop scan"、"clean up codebase"、"find dead code"、"large files"时立即触发。 也适用于："帮我看看有没有技术债"、"代码库健康度怎么样"、"这个模块该不该拆"、 "有没有未使用的代码"等代码卫生评估场景。 只要用户想快速了解代码库的结构性卫生状况，就应使用此 skill。

Slop Cleaner

自动化扫描代码库中的结构性问题——大文件、死代码、测试与实现混合、架构坏味道—— 快速产出可行动的清扫报告。

与 code-review 的定位区别：code-review 偏人工辅助，深度分析具体代码逻辑； slop-cleaner 偏自动化批量扫描，用 Glob/Grep/Bash 快速定位结构性问题，产出可行动的清扫清单。

核心原则

1. 速度优先：用 Glob/Grep/Bash 批量扫描，避免逐文件 Read。只在需要深入分析时才 Read 具体文件。
2. 数据说话：每个发现都要有具体的文件路径、行号、度量数据（行数、调用次数等），不凭感觉。
3. 可行动：报告不只是问题清单，还要给出优先级排序和具体的修复建议。
4. 尊重项目规范：扫描前先读取 CLAUDE.md / 项目文档，按项目已有的约定判断问题，不套用外部模板。
5. 增量感知：对比历史扫描结果，区分新增问题和已知问题，让清扫有可量化的进展。

第一步：项目上下文 + 排除列表（快速）

并行读取，建立最小必要上下文：

Read("CLAUDE.md")                           # 项目规范、约定、已知待办
Glob("src/**/*.rs") 或 Glob("src/**/*.ts")  # 主要源文件列表
Bash("git log --oneline -10")              # 最近改动方向（可选）
Glob("spec/reviews/*.md")                  # 历史扫描报告（用于对比）

从上下文中提取：

• 项目语言和技术栈
• 模块/包的划分方式
• 项目已有的代码规范（如测试分离规则、文件大小上限等）
• 已知待办项：CLAUDE.md 中已记录的问题（如「待迁移文件」表格），扫描时标注为 已记录，避免重复报告
• 排除目录：内置默认排除 + 从 CLAUDE.md 提取的额外排除

默认排除列表（所有扫描命令统一过滤）：

target/ node_modules/ vendor/ .git/ dist/ build/
*.generated.rs *.min.js *.min.css
migrations/ __snapshots/ fixtures/

所有 find / Glob / Grep 命令都必须遵守排除列表。用 Grep 时通过 glob 参数排除，用 find 时通过 -not -path 排除。

第二步：渐进式扫描

不是所有维度都需要每次全量跑。根据仓库规模和用户意图选择策略：

策略 A：快速扫描（默认）

先跑维度 1（大文件）+ 维度 2（死代码），这两个维度最快、结果最确定。

• 如果大文件扫描发现仓库整体很小（最大文件 < 200 行），跳过架构维度
• 如果没有 Rust 项目，跳过测试分离维度（#[cfg(test)] 是 Rust 特有的）
• 用户指定了维度时，只跑指定维度

策略 B：全量扫描

用户明确要求"全面扫描"或仓库规模较大时，四个维度全部并行执行。

策略 C：定向扫描

用户指定了目录或文件（如"扫一下 src/mcp/"），只对该范围执行扫描。

四大维度

维度 1：大文件 / 上帝类

目标：找出职责过重、应拆分的文件和函数。

扫描命令（并行执行）：

# 按文件大小排序（最快，秒级完成，无需逐行读取）
Bash("find <src_dir> -name '*.rs' -not -path '*/target/*' | xargs ls -lhS | head -30")

# 命中文件再用行数精确确认
Bash("find <src_dir> -name '*.rs' -not -path '*/target/*' | xargs wc -l | sort -rn | head -30")

# 超长函数（仅对 top-10 大文件深入检查）
Grep("pub fn |pub async fn ", path="<top10_files>")  # 列出候选函数，Read 确认行数

判定阈值（按项目规范调整，默认值）：

先用 ls -lhS 按文件大小秒级粗筛，命中文件再用 wc -l 精确确认行数。

对每个命中文件：Read 前 50 行 + 后 50 行，判断职责是否可拆分。

维度 2：死代码

目标：找出定义了但从未使用的函数、变量、类型、导入。

扫描命令（并行执行）：

# 编译器级检测（最权威）
Bash("cargo build 2>&1 | grep -i 'unused\\|dead_code\\|never used'")
Bash("cargo clippy 2>&1 | grep -i 'unused\\|dead_code'")  # clippy 覆盖更广

# TODO/FIXME/HACK 注释（判断是否为被遗忘的技术债）
Grep("TODO|FIXME|HACK|XXX|WORKAROUND")

# 注释掉的代码块（连续 3 行以上以 // 开头的代码行）
Bash("grep -rn '^\s*// *[a-zA-Z]' <src_dir> | ... ")  # 提取连续 3+ 行的文件

验证方法：编译器已报告的直接确认，无需二次验证。对注释掉的代码和 TODO，只报告数量，不做逐条验证。

维度 3：测试与实现混合

目标：找出违反测试分离规范的文件。

扫描命令：

# 源文件中内联的 #[cfg(test)] mod tests 块
Grep("#\\[cfg\\(test\\)\\]")  # 找出所有含内联测试的源文件

对每个命中文件，用 Bash 统计 #[cfg(test)] 到对应 } 的行数。

判定规则（参考 CLAUDE.md 中的测试规范）：

• 内联测试 < 30 行：可以接受
• 内联测试 30-100 行：应分离
• 内联测试 > 100 行：必须分离

同时检查：

• tests/ 目录是否存在、是否有内容
• 测试文件命名是否符合项目规范（如 foo_test.rs）

维度 4：架构坏味道

目标：找出违反分层规则、循环依赖、职责混乱的模块。

扫描命令（并行执行）：

# 依赖方向检查（Rust：下层 crate 依赖上层）
# 读取 Cargo.toml 的 [dependencies] 段，对照 CLAUDE.md 中的依赖关系图
Glob("**/Cargo.toml")  # 然后读取每个 crate 的依赖

# 模块内聚度：一个 mod.rs 引入大量不相关的子模块
Glob("*/mod.rs")  # 然后读取每个 mod.rs 的 mod 声明

# pub 接口过多（API 面过大）
Grep("pub fn |pub struct |pub enum |pub trait ")  # 按文件统计 pub 声明数量

判定方法：

• 对照 CLAUDE.md 中描述的架构规则，检查实际依赖是否匹配
• 检查是否存在 utils.rs/common.rs/helpers.rs 等万能模块（什么都往里扔）
• 检查 mod.rs 的子模块数量是否过多（>15 个子模块 = 模块应拆分）

第三步：去重 + 历史对比

扫描完成后、写入报告前：

1. 去重：对比 CLAUDE.md 中已记录的待办项，标注 已记录 或 新增
2. 历史对比：如果 spec/reviews/ 下有历史报告，对比问题数量的变化

第四步：汇总与输出

终端摘要

扫描完成后，立即在终端输出简洁摘要：

🧹 Slop Scan 完成 → spec/reviews/2026-05-12.md

发现问题：2 critical / 5 major / 12 minor（+3 新增 / -2 已修复）

Top 问题：
- [critical] src/handler.rs — 920 行，严重超限，建议拆分为 3-4 个子模块 [新增]
- [critical] src/db/mod.rs — 引入 23 个子模块，内聚度极低 [已记录]
- [major] src/auth.rs — 内联测试 145 行，应分离为 auth_test.rs [新增]
- [major] src/utils.rs — 17 个 pub fn，仅 5 个被引用，12 个疑似死代码 [新增]

Markdown 报告

读取 assets/report-template.md（本 skill 目录下），按模板填充，然后：

1. 确定输出路径：默认写到 spec/reviews/YYYY-MM-DD.md

   • 若用户指定了路径，使用用户指定的路径
   • 若 spec/reviews/ 目录不存在，先用 folder_operations 创建

2. 用 Write 写入文件

报告格式：与 spec/issues/ 保持一致的风格——简洁、数据驱动、可直接转化为 issue 跟踪。

严重程度标签

指定范围扫描

如果用户指定了目录或文件（如"扫一下 src/mcp/"），只对该范围执行扫描，跳过无关模块。

如果用户指定了维度（如"只找死代码"），只执行该维度的扫描。

参考文件

• assets/report-template.md — Slop 报告模板