deslop

Deslop

针对 AI 生成代码的全代码库激进清理。包含 8 个专用阶段，每个阶段都由一个全新的子 Agent 负责，任务范围明确。基于 Shaw（@shawmakesmagic）提出的模式。

功能简介（8 个阶段）

1. DRY / 去重 — 合并重复代码，降低复杂度
2. 整合共享类型 — 统一本应共享的类型定义
3. 移除死代码 — 使用适合当前技术栈的工具查找未被引用的代码
4. 理清循环依赖 — 找出并打破循环依赖
5. 移除弱类型 — 将 any/unknown/T.untyped/interface{} 替换为实际类型
6. 移除防御性 try/catch — 删除那些没有实际用途、会吞掉或隐藏错误的错误处理器
7. 移除旧版/已弃用/回退代码 — 整合为唯一的当前代码路径
8. 移除 AI 水文注释 — 删除过程性旁白、存根、装腔作势的内容，以及显而易见的代码注释

适用场景

• 完成一轮密集的 AI 编码之后（快速生成了大量代码）
• 合并长期运行的功能分支之前
• 接手来自另一轮 AI 会话或其他开发者的代码库时
• 定期进行深度清理（每季度或每个版本发布前）
• 在流水线中的位置：heavy AI coding → /deslop → /simplify → /adversarial-review → /finalize → commit

不适用场景

• 微不足道的更改或最近的编辑 — 改用 /simplify
• 没有时间仔细审查的代码库 — 此工具会移动文件并删除代码
• 功能开发过程中 — 先完成该功能
• Git 工作区不干净时（见下文“安全须知”）

安全须知 — 不容妥协

此技能会删除代码。开始前：

1. 确认 Git 工作区干净 — git status 必须显示工作区干净。否则拒绝继续。如果存在未提交的更改，请告知用户先暂存或提交。
2. 创建专用分支 — 在任何阶段写入更改之前，先运行 git checkout -b deslop/YYYY-MM-DD。绝不能在 main/master 上运行。
3. 每个阶段结束后提交 — 每个阶段都单独提交，这样可以单独撤销某个阶段，而不必重做其余工作。
4. 仅实施高置信度更改 — 每个子 Agent 只实施自己确信的更改。存疑之处应写入报告供人工审查，不要直接改动代码。
5. 安装工具。 如果某个阶段的规范工具尚未安装，请安装它 — 不要在有专用工具的阶段改用 grep/ripgrep/手动扫描。此技能的核心就是使用合适的分析器；grep 无法识别动态引用、进行可达性分析或检测循环依赖。详见下文“工具安装政策”。

工具安装政策

每个阶段针对其技术栈都有一个规范工具（见 references/passes.md 和各语言参考文档）。子 Agent 开始某个阶段时，必须确保工具可用；如果尚未安装，则必须安装。

JavaScript / TypeScript — 使用 npx，无需安装

所有规范的 JS/TS 工具均可通过 npx --yes 运行，不会修改 package.json：

npx --yes knip        # dead code
npx --yes madge --circular src/   # circular deps

首次运行时，npx 会将工具下载到全局 npm 缓存。不更改项目。单次 deslop 运行默认使用此方式 — 不要为了临时使用而将任何内容添加到 package.json。

Ruby — 安装到用户 gems 目录

gem install debride
bundle exec srb tc     # only if sorbet/config exists in the project

安装到用户的 gem 路径。不要为了单次 deslop 运行而将其添加到项目的 Gemfile。

Go — 使用 go install 安装到 $GOPATH/bin

go install honnef.co/go/tools/cmd/staticcheck@latest
go install golang.org/x/tools/cmd/deadcode@latest

在 $(go env GOPATH)/bin 中安装二进制文件。这是标准 Go 工具实践。

如果安装失败（例如没有网络、不支持当前 Go 版本等）：报告失败并指出工具名称，然后跳过该阶段。不要改用 grep。跳过某个阶段是诚实的结果；基于 grep 的结果则会误导用户 — 它看似经过分析，实际却会漏掉专用工具能够发现的大多数问题。

如果某个阶段确实没有可用工具（例如 Ruby 中没有 packwerk 时无法检查循环依赖，或没有类型系统时无法整合类型）：请在阶段报告中明确说明。“已跳过 — 未使用类型系统”是合理的结果。“已跳过 — 改用 grep 扫描”则不是。

输入解析

解析 $ARGUMENTS：

• 无参数 → 在仓库根目录运行全部 8 轮检查
• 路径（例如 app/services 或 src/）→ 将所有轮次的范围限定为该路径
• --dry-run → 对每轮检查运行研究阶段，输出一份批判性评估，但不进行任何代码更改
• --passes 1,3,8 → 仅运行指定的轮次（以逗号分隔）
• --stack js|ruby|go → 强制指定技术栈（跳过自动检测）

第 1 步：检测技术栈

在目标路径中查找锁文件（如果未指定路径，则在仓库根目录中查找）：

文件	技术栈
package.json + tsconfig.json	typescript
package.json（无 TS 配置）	javascript
Gemfile	ruby（检查是否包含 rails gem → rails）
go.mod	go

一个仓库可能包含多个技术栈（例如，带有 Vue 前端的 Rails 应用）。记录找到的所有技术栈。分派每轮检查时，告知子 Agent 其将修改的文件涉及哪些技术栈。对于嵌套的前端（例如 app/frontend/），第 3 和第 4 轮应为该子树分派了解 JS/TS 的子 Agent，其余部分则分派了解 Ruby 的子 Agent。

如果指定了 --stack，则跳过检测并使用强制指定的技术栈。

关于特定技术栈的工具详情（命令、安装、注意事项），仅在即将运行使用该工具的轮次时，才读取相关参考文件：

• references/javascript.md — knip、madge、TypeScript 类型检查
• references/ruby.md — debride、packwerk、Sorbet 说明
• references/go.md — staticcheck、go mod graph、deadcode

第 2 步：研究阶段（并行，只读）

对于所有适用的轮次（未被 --passes 跳过），在同一轮中分派子 Agent，以便 8 项研究任务并行运行。

使用 Agent 工具，并设置 subagent_type: general-purpose。每个研究子 Agent 都应：

• 仅阅读代码，不做任何编辑
• 运行只读分析工具（linters、knip --dry-run、madge --circular 等）
• 提供批判性评估：问题是什么、位于何处、置信度如何、如何修复
• 将每项发现归类为高置信度（可安全自动应用）或需要审核
• 返回结构化报告

研究子 Agent 提示模板（填写 {pass_name}、{pass_instructions}、{stack_info}、{scope_path}）：

You are a senior engineer performing a cold read of this codebase. You are
scoped to a single concern: {pass_name}.

## Stack Info
{stack_info}

## Scope
Target path: {scope_path}

## Your Mandate
{pass_instructions}

## Output Format

Return two sections:

### Critical Assessment
A prose summary of the state of the code for your concern. What patterns do
you see? How pervasive is the problem? Any notable surprises?

### Findings
A list of concrete, actionable findings. For each finding, provide:

- **Location:** file path(s) and line range(s)
- **Issue:** what's wrong
- **Fix:** specific, concrete change
- **Confidence:** high | needs-review
- **Rationale:** why this is safe (for high-confidence) or what the risk is (for needs-review)

Be honest about confidence. If you can't verify a symbol is unused across the
whole codebase, it's needs-review. If removing a try/catch might swallow a real
error condition, it's needs-review. When in doubt, err toward needs-review.

## Do Not
- Make any file edits
- Run stateful commands (git commits, migrations, package installs)
- Go beyond your concern's scope

每轮检查的完整说明、适配技术栈的工具调用，以及每轮中高置信度与需要审核的判定标准，参见 references/passes.md。

第 3 步：应用阶段（顺序执行，每轮提交一次）

如果指定了 --dry-run，则跳过此步骤并转到报告阶段。

按以下顺序处理有高置信度发现的轮次：

1. 先处理死代码（第 3 轮） — 删除未使用的代码可缩小后续轮次的处理范围
2. AI 味注释（第 8 轮） — 注释风险较低
3. 遗留／已弃用内容（第 7 轮）
4. 防御性 try/catch（第 6 轮）
5. 弱类型（第 5 轮）
6. 合并共享类型（第 2 轮）
7. DRY／去重（第 1 轮） — 影响最大，在其他轮次清理完代码后再执行
8. 循环依赖（第 4 轮） — 结构性改动，最后执行

每轮按以下步骤操作：

1. 分派一个应用子 Agent。向其提供对应研究轮次的发现，并指示它只实现高置信度项目。重新提供最新的文件内容（不要依赖研究阶段缓存的状态）。
2. 子 Agent 返回后，如果有可用的类型检查器／linter／测试套件，则运行项目对应工具，并记录通过／失败
3. 使用提交信息 deslop: <pass_name> 提交（例如 deslop: remove dead code）
4. 如果测试或类型检查失败，不要继续下一轮。报告失败并交还给用户。

应用子 Agent 提示模板：

You are implementing a single cleanup pass: {pass_name}.

## Stack Info
{stack_info}

## Findings to Apply
{high_confidence_findings}

## Rules
- Implement ONLY the findings above. Do not expand scope.
- If a finding looks wrong on closer inspection, skip it and note why in your
  report. Safety over completeness.
- Make minimal edits. Don't reformat, rename, or touch surrounding code.
- If a finding would break a public API, skip it and flag it.

## Output
Return a summary:
- Applied: N findings
- Skipped: N findings (with brief reason for each)
- Files touched: list

第 4 步：报告

完成所有轮次（或 --dry-run 研究）后，生成一份报告：

## Deslop Report

**Stack:** <detected stacks>
**Scope:** <path>
**Mode:** <full | dry-run | --passes 1,3,8>
**Branch:** deslop/YYYY-MM-DD (or "no changes — dry-run")

### Pass Summary
| Pass | Findings | High-Conf | Applied | Needs-Review | Skipped |
|------|----------|-----------|---------|--------------|---------|
| 1. DRY/dedupe | ... | ... | ... | ... | ... |
| 2. Shared types | ... | ... | ... | ... | ... |
| 3. Dead code | ... | ... | ... | ... | ... |
| 4. Circular deps | ... | ... | ... | ... | ... |
| 5. Weak types | ... | ... | ... | ... | ... |
| 6. Defensive try/catch | ... | ... | ... | ... | ... |
| 7. Legacy code | ... | ... | ... | ... | ... |
| 8. AI slop comments | ... | ... | ... | ... | ... |

### Needs-Review Items
Grouped by pass. Each item includes location, issue, suggested fix, and why
it was deferred. Review these manually.

### Commits
List of commits created on the branch.

### Next Steps
- Review needs-review items
- Run the full test suite
- Run `/simplify` + `/adversarial-review` before merging

常见错误

• 在未清理的工作树上运行。 各轮之间提交的核心目的，是确保可以干净地还原。如果跳过干净工作树检查，错误的处理可能会与用户正在进行的工作混在一起，之后很难理清。
• 跳过研究阶段。 直接开始编辑只会得到浅尝辄止、依赖模式匹配的修改。先研究并提交发现，再应用修改。
• 应用需要审核的项目。 如果子 Agent 没有把握，应用阶段也不该贸然处理。请在报告中列出这些项目，由用户决定。
• 在第 3 轮（死代码）之前运行第 1 轮（重复代码）。 你会浪费精力去合并即将删除的代码。
• 在应用阶段并行运行所有轮次。 各轮之间可能会冲突（例如，类型整理可能会移动死代码轮次想要删除的类型）。研究时并行，应用时依次进行。
• 将安装失败视为阻塞问题。 如果某轮所需工具无法安装（网络不可用、版本不受支持），该轮会报告“已跳过 — <工具> 安装失败”，其余流程继续运行。

参考资料

• Shaw 的原始提示词：https://x.com/shawmakesmagic/status/2044269097647779990
• references/passes.md — 各轮的完整说明
• references/javascript.md — JS/TS 工具（knip、madge）
• references/ruby.md — Ruby/Rails 工具（debride、packwerk）
• references/go.md — Go 工具（staticcheck、go mod graph）