melech-prune

用途

melech-prune 用于在 AI 迭代编码之后审计并移除死代码、AI 残留和不必要的复杂性。经过 5–15 轮 AI 迭代编码后，代码库会积累 AI 残留：早期提示留下的孤立辅助函数、死类型、半迁移状态、推测性配置键和僵尸工作流。功能可能可用、测试可能通过，但工作 diff 中充斥着死路径和未被引用的脚手架。melech-prune 作为证据式垃圾回收器和架构协调器来处理这一问题。

核心哲学：反向举证责任

在常规编码中，开发者假设：“AI 写了这个，所以它大概是需要的。”melech-prune 完全翻转这一假设：每个新增或修改的函数、类型、参数、状态钩子、包装器和导出都被假定有罪（死代码、意外残留或 YAGNI 膨胀），直到用具体证据证明其无罪。如果某个符号无法提供可达性和具体必要性的证明，它就会被列入删除队列。

四项证据证明

要通过清理，被审计 diff 中的每个符号必须满足以下四项测试：

可达性证明：问“运行时执行真的能到达这里吗？”要求从活跃入口点（路由、UI 组件、CLI 命令、导出或事件处理器）追踪直接调用链。失败则视为死代码/僵尸代码，予以清除。
需求证明：问“哪个明确的用户需求要求了这个？”要求指出需要此分支或参数的确切用户故事或 bugfix。如果答案是“以防以后需要”，则失败。失败则视为 YAGNI 膨胀，予以剥离。
非重复证明：问“这段逻辑在代码库中是否已经存在？”要求验证现有辅助函数、工具或标准库方法是否已处理此逻辑。失败则视为意外重复发明，予以合并。
破坏性证明：问“如果现在删除这个，什么测试或行为会失败？”要求模拟移除或检查测试覆盖。如果没有任何失败且行为不变，那它为什么存在？失败则视为幽灵脚手架，予以移除。

如果某个符号看起来像是已知库或工具的手写版本，而不是本地代码，那属于采用问题而非删除问题——记录下来并向用户标记。

工作流程

询问范围（ask_question）→ 2. 构建调用图并运行四项证明 → 3. 向用户展示证据表 → 4. 请求批准（ask_question）→ 5. 清理并验证（测试通过）

步骤 1：提示范围

绝不假设 diff 目标。立即使用 ask_question 提示用户选择审计边界：

问题：“你想清理哪个范围？”

选项：

（推荐）未提交的工作树（已暂存 + 未暂存的 git diff）
当前分支 vs 基线（git diff origin/main...HEAD 或 main...HEAD）
最近 N 次提交（例如 HEAD~3..HEAD）
特定文件或目录（自定义路径）

如果用户在初始提示中传入了特定目标（例如 melech-prune HEAD~2..HEAD 或 melech-prune src/auth/），则直接确认该目标。

步骤 2：用证据证明审计 diff

检查所选范围中每个新增或修改的文件：

提取所有新增/修改的符号：函数、方法和类；类型、接口、DTO 和枚举；导入和导出变量；状态变量、props、钩子和事件处理器；参数、标志和配置键。

追踪调用图：从叶子辅助函数向上追踪以找到其调用者。捕获僵尸链：一个辅助函数不会仅仅因为 WorkflowA 调用它就存活，如果 WorkflowA 本身从应用入口点零调用者。

将发现分类为层级：

🟢 第 1 层：无争议的死残留（零风险）：零引用的本地函数、未使用的导入、孤立类型、不可达的 if/else 分支、死测试夹具。
🟡 第 2 层：僵尸工作流与废弃迭代（中风险）：在第 2 轮创建、第 6 轮方法改变时被废弃但仍连接到幽灵状态的处理器或多步逻辑。
🟠 第 3 层：推测性 / YAGNI 膨胀（设计层面）：未使用的选项、只有一个琐碎调用者的防御性包装器、过度泛化的辅助参数。
🔵 第 4 层：意外重复：迭代期间编写的、重复发明现有代码库工具的自定义辅助函数。

步骤 3：展示发现与通知

在触碰任何代码之前，输出清晰、结构化的证据与清理表，包含层级、文件、符号/块、失败证明与证据、建议操作等列。

步骤 4：请求明确用户批准

绝不在没有人工签字的情况下清理。使用 ask_question 请求用户裁决：

问题：“你希望如何处理这些清理建议？”

选项：

（推荐）清理所有已验证项（第 1、2、3、4 层）
仅清理第 1 层（零风险死代码和未引用符号）
让我指定保留或清理哪些项
取消（保持工作树不变）

如果用户选择选项 3，在继续之前询问他们想保留表中的哪些特定项。

步骤 5：外科手术式清理与验证

一旦批准：

删除死代码：移除已批准的函数、类型、分支和参数。

清理悬空引用：移除删除后遗留的未使用导入和不需要的变量。

尊重注释：保留承重的雷区/WHY 注释，仅当注释所解释的代码被删除时才移除注释。

运行验证：运行测试套件（npm test、pytest、cargo test、go test 等）；运行类型检查（tsc、mypy、cargo check 等）或构建命令。如果任何测试失败，检查是测试在测试已删除的死路径（更新测试）还是触及了意外依赖（回滚并修复）。

总结结果：移除的代码行数、清理的文件数、最终验证/测试状态（例如所有 42 个测试通过）。

该做与不该做

该做：在运行分析前用 ask_question 提示审计范围。不该做：未经确认就猜测 git diff 目标。
该做：为每个标记项提供具体证据（例如“仓库中 0 引用”“唯一调用者是死函数 X”）。不该做：不展示调用图证据就说“这看起来不必要”。
该做：在删除文件或代码块前通过 ask_question 要求明确用户批准。不该做：在幕后静默删除代码。
该做：清理后立即运行测试和类型检查以证明构建保持绿色。不该做：清理后留下损坏的导入或失败的测试套件。

适用场景

适用于使用 AI 进行多轮迭代编码后的代码库清理，尤其是当功能已可用但 diff 中积累了大量死路径、未引用脚手架、废弃工作流和推测性配置时。

限制

该技能依赖用户明确批准后才执行删除；需要可运行的测试套件和类型检查工具来验证清理结果；对于看起来像已知库手写版本的符号，仅标记而不删除。其他具体限制暂未提供。