melech-tidy

Tidy

你刚刚用 AI Agent 完成了编码。功能可以正常运行，测试也可能通过，但 git status 显示差异杂乱不堪：早期提示词遗留下来的孤立辅助函数、无用类型、臃肿的提示词指令、掩盖真实改动的纯外观变动，或处理几乎不会发生的情况时增加的重试和特殊分支。

melech-tidy 是通用、自适应的差异精简引擎。

melech-tidy 不会让你先诊断差异究竟是无用代码、提示词臃肿、外观噪声，还是得不偿失的罕见情况处理；它会审查你的差异，将发现归入四个互斥的精简类别，提供具体的证据表，并在征得你同意后执行精细清理。每个类别都只提出建议；由你决定要整理哪些内容。

Tidy 只做减法；不会在不同边界之间移动代码，也不会重新设计架构。

---

4 个互斥的精简类别

Agent 会读取目标需求和周边代码，将差异拆解为各项发现，并根据一个界定严格的引擎评估每项可精简的发现。并非每个改动块都需要提出建议。

                              Incoming Working Diff
                                        │
                         Decompose into isolated findings
                         (semantic edits absorb inseparable
                              cosmetic surroundings)
                                        │
                    ┌───────────────────┴───────────────────┐
                    ▼                                       ▼
          Canonical artifact unchanged?              Semantic change
                    │                                       │
                    ▼                         ┌─────────────┴─────────────┐
              Diff noise                 [Code / Config]       [Prompt / Rules]
          (Cosmetic-only churn)                 │                      │
                                  Does deleting it change              ▼
                                  observable behavior in any case?   Prompt bloat
                                     ┌──────────┴──────────┐
                                     ▼ no                  ▼ yes, a rare case
                                 Dead code           Edge-case trade

类别按建议操作会改变什么来划分，而不是按代码的外观来划分：

建议操作	类别
还原表示方式；规范产物保持不变	差异噪声
删除或合并代码；外部可观察行为不变	无用代码
编辑提示词或指令文本	提示词臃肿
删除或简化代码，并改变罕见情况下的行为	边缘情况取舍

如果相同代码行支持两种操作（例如用同类辅助函数替换手写代码，但在一种罕见情况下有所不同），请将该发现归入建议操作所属的类别，并在证据中说明另一种方案。

面向用户的标签（始终优先使用这些标签——报告、审批选项或摘要中绝不使用“类别 1/2/3”）：

简短标签	完整名称
无用代码	Dead Code & AI Residue
提示词臃肿	Instruction & Prompt Bloat
差异噪声	Cosmetic Diff Noise
边缘情况取舍	Edge-Case Trades (80/20)

以下类别编号仅用于内部章节定位。

---

类别 1：无用代码与 AI 残留（垃圾回收）

• 目标：AI 迭代过程中新增或修改，但未被调用、孤立或不再需要的代码。
• 核心理念：举证责任倒置。每个新增符号都先假定有罪（属于残留或无用代码），直到证明其无罪。
• 4 项证据验证：
  1. 可达性验证：运行时是否能从有效入口（路由、UI 组件、CLI 命令、导出项或事件处理程序）实际到达此处？如果不能 → 清除。
  2. 需求验证：哪条明确的用户提示要求添加此内容？如果答案是*“以防以后用得上”* → 按 YAGNI 原则移除。
  3. 非重复性验证：现有辅助函数、同类功能、标准库工具或依赖项选项是否已经能实现此功能？按用途搜索，而不只按名称搜索；如果某个分支用于防止依赖项可能已经处理的情况，也要阅读依赖项源码。如果已有 → 合并。
  4. 无损验证：如果现在删除，是否会导致测试或行为出错？如果没有失败，也没有行为变化 → 移除。
• 操作：只做减法（删除无用函数、类型、属性、导入项和僵尸链）。
• 深入指南：references/lane-1-dead-code.md — 举证责任倒置、残留的 4 级分类，以及调用图和僵尸链追踪。

---

Lane 2：指令与提示词膨胀（提示词精简）

• 目标：差异中的系统提示词、技能文件（SKILL.md）、规则指令（.cursorrules、AGENTS.md）和 Markdown 提示词文档。
• 核心理念：精简且覆盖所需，胜过面面俱到。每一行在证明其不可或缺之前，都应视为可疑。做减法，而不是重新设计。
• 提示词精简的 5 项验证：
  1. 覆盖性：删掉后，是否会遗漏实际必需的场景？如果不会 → 删除。
  2. 冗余性：这条内容是否已在指令的其他位置说明？如果是 → 合并。
  3. 涵盖性：这条规则是否属于已有更广泛规则的子集？如果是 → 并入。
  4. 默认知识：能力合格的模型是否无需提示也会做到？如果会 → 删除。
  5. 不可或缺性：没有这行内容，Agent 的输出是否确实会变差？如果不会 → 删除。
• 行动：在差异窗口内做减法（删去填充内容、冗余的边缘情况和过度解释）。
• 深入指南：references/lane-2-prompt-shake.md — 目标内容、5 项验证的完整说明，以及精简但不失信息的防护原则。

---

Lane 3：外观差异噪声（规范等价清理）

• 目标：独立的、仅涉及外观的发现项，其表示形式发生了变化，但规范化产物及其预期含义并未改变。
• 核心理念：先看上下文，证明等价，否则保留。一行代码不会仅仅因为移动了位置就成为噪声。阅读需求和周边代码，然后使用适合该仓库的工具证明规范等价。如果无法证明，或变更与语义编辑混杂，就不要将其归入此类别。
• 4 项证据验证：
  1. 意图验证：这项变更是否与所需行为或指令效果无关？为修复作用域、时序或顺序而移动声明属于语义变更，不符合条件。
  2. 规范等价验证：仅经过安全规范化后，变更前后的产物在结构上是否相同（例如，相同的解析后代码结构、Markdown 结构及指令文本，或解析后的依赖关系图）？
  3. 重要性验证：对于此语言和仓库，变更的空白、顺序、换行符或元数据是否不起作用？切勿假定导入语句、缩进、文件模式、注释、快照或生成的输出只是外观内容。
  4. 还原安全性验证：将外观差异还原为基础表示后，仓库要求的格式化、生成、构建和测试检查是否仍能全部通过？
• 行动：仅还原表示形式（还原外观差异区块，或使用仓库预期的工具重新生成）。在此类别下，绝不重写语义或手动编辑生成的输出。
• 深入指南：references/lane-3-diff-noise.md — 发现项拆解、按产物类型进行规范证明、混合区块的归属，以及失败时默认拒绝的陷阱。

---

第 4 条车道：边缘情况处理（80/20）

• 目标：代码或配置文件中的可运行代码，唯一作用是处理罕见情况：罕见竞态条件下的重试、特殊情况错误消息、围绕可恢复步骤的防御性 try/catch，以及比仓库惯例更严格的保护措施。
• 核心理念：明确说明代价，再让用户权衡。找出可以删除的代码，前提是我们愿意放弃处理某种罕见情况，从而删去收益最小的部分。绝不能把这种取舍说成毫无损失。
• 5 项取舍依据（必须全部成立）：
  1. 发生频率：什么会触发这种情况？它有多罕见？发生频率未知会提高风险。
  2. 后果：没有这项处理时，用户是否会看到明显且可恢复的错误？静默地产生错误结果、数据丢失、重复扣费或信息泄露都不可接受。
  3. 恢复方式：是否有成本低廉的补救方式，例如重试或再次粘贴？
  4. 惯例：同类功能如何处理相同情况？高于惯例的处理可以权衡；低于惯例则不行，仓库规则要求的处理必须保留。
  5. 收益：哪些代码行、测试、常量、辅助函数和概念可以一并删除？若收益很小，却要承受实际损失，就不值得推荐。
• 底线：安全与身份验证、租户或用户隔离、数据完整性、金钱和隐私方面的处理，最多只能降至仓库惯例，绝不能低于惯例；调查结果中还必须注明应由安全审查人员确认。
• 操作：明确说明损失后再建议取舍；获批后，删除相关处理及所有仅为其服务的内容，并更新描述已放弃处理的情况的文档。
• 深入指南：references/lane-4-edge-case-trade.md — 目标、5 项依据、底线及示例条目。

---

工作流

1. Resolve Scope  ──►  2. Adaptive Diagnosis  ──►  3. Present Evidence  ──►  4. Ask Approval  ──►  5. Tidy & Verify
  (Prompt or Flag)      (Route by lane name)        Unified Table             (ask_question)       (Tests green)

---

步骤 1：确定范围

审查前先确认差异范围。除非另有说明，默认审查未提交的更改：

• 未提交的工作树（暂存 + 未暂存的 git diff）——默认
• 分支与基准分支的差异（例如 origin/main...HEAD 或 main...HEAD）
• 最近 N 次提交（例如 HEAD~2..HEAD）
• 特定文件或路径

如果目标不明确，请使用 ask_question 询问用户。

---

步骤 2：自适应诊断与车道分流

检查请求的结果、相关上下文和差异。分流可精简的发现，不要盲目按文件分流：

1. 拆解差异：
   • 使用 git diff 的代码块作为输入，并在安全的前提下拆分独立的发现。
   • 如果外观调整与语义编辑无法分开，则由语义车道负责整个发现。
   • 保留有意为之、必要且位置恰当的更改，不要为了凑整洁建议而凭空制造问题。
2. 检查所有文件类型中独立的外观调整候选项：
   • 使用适合仓库的解析器、格式化工具或规范化表示，对比基准与更改后的文件。
   • 仅当 4 项依据全部成立时，才分流到差异噪声。缺少任何依据，都不要将其纳入此车道。
3. 针对代码或配置文件（.ts、.py、.go、.rs 等）中的语义更改：
   • 沿调用图向上追踪调用方。将未引用的符号和僵尸调用链标记为死代码。
   • 按用途搜索同类功能、标准库和依赖项的选项，查找新代码重新实现的功能。将重复实现标记为死代码。
   • 列出每个分支、catch、重试、回退、特殊消息和额外检查所处理的情况。应用 5 项取舍依据，并标记值得放弃的罕见情况处理。每次整理时都运行此车道，即使用户没有要求权衡取舍。
4. 针对提示词/指令文件（.md、.prompt、.cursorrules 等）中的语义更改：
   • 根据提示词膨胀车道的 5 项提示词依据，审查更改的行。

步骤 3：呈现统一的证据与诊断表

在修改任何代码之前，输出一份简洁易读、按类别分组的表格。在类别列中，使用简短标签（死代码、提示词臃肿、差异噪声、边缘情况权衡）——绝不使用类别编号。除 边缘情况权衡 外，每个类别的 我们失去了什么 一栏都填 —；对于 边缘情况权衡，则写明从用户角度看失去的情况。

### 🧹 Tidy Audit Results (Scope: uncommitted diff)

| Lane | Target | Issue / Evidence | Proposed Action | What we lose | Risk |
|---|---|---|---|---|---|
| **Dead code** | `src/utils/date.ts:L40` (`formatDateV2`) | **Reachability**: 0 callers across repo. | Delete dead helper | — | Low |
| **Dead code** | `src/types/user.ts:L15` (`DraftRole`) | **Breakage**: Unreferenced enum variant. | Delete variant | — | Low |
| **Prompt bloat** | `skills/deploy/SKILL.md:L18` | **Default Knowledge**: Explains how git commit works to the model. | Cut line | — | Low |
| **Diff noise** | `src/routes/admin.ts:L20-L45` | **Canonical equivalence**: Formatter-only delta; parsed structure is unchanged and format check passes after restore. | Restore base formatting | — | Low |
| **Edge-case trade** | `src/connect/service.ts:L120-L134` (retry on 400) | **Frequency**: only when two users connect the same site within a second. **Recovery**: connecting again succeeds. **Precedent**: no other connector retries. | Drop retry, `RETRY_DELAY_MS`, `delay()`, and its test | One of two simultaneous connects fails and must be retried | Low |

如果没有任何罕见情况处理通过 5 项权衡证明，请在表格下方用一行说明，不要悄悄省略该类别。

---

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

未经人工批准，绝不修改文件或删除代码。

使用 ask_question 提示用户：

• 问题："你希望如何处理这些精简建议？"
• 选项：
  1. (推荐) 应用所有建议（死代码、提示词臃肿、差异噪声和边缘情况权衡）
  2. 仅应用保留行为的清理（死代码 + 提示词臃肿 + 差异噪声；跳过边缘情况权衡）
  3. 让我从表格中选择具体项目
  4. 取消（保持工作树不变）

如果没有边缘情况权衡，则省略选项 2。

---

步骤 5：精确精简与验证

获得批准后：

1. 处理差异噪声：将获批的纯外观问题还原为其基础表示形式；使用预期的生成器/格式化工具，而不是手动编辑生成的文件。
2. 处理死代码：删除死函数、类型和未被引用的导入。
3. 处理提示词臃肿：精简差异范围内提示词/指令文档中的冗余内容。
4. 处理边缘情况权衡：删除获批的处理逻辑及所有仅为其服务的内容（常量、辅助函数、导入、测试）。保留一个用于验证主路径仍可运行的测试，并更新描述已舍弃情况的文档和注释。
5. 保留承载关键信息的上下文：保留承载关键信息的注释和意图说明。
6. 运行验证：
   • 运行测试（npm test、pytest、cargo test、go test）。
   • 运行类型检查/构建（tsc、mypy、cargo check）。
   • 如果测试失败，立即修复或还原导致问题的更改。
7. 汇总报告（以类别名称开头，而非编号）：
   • 死代码、提示词臃肿、差异噪声和边缘情况权衡各自有哪些更改
   • 对于每项已应用的权衡，说明代码不再处理的情况
   • 删除/新增的行数
   • 已清理或还原至干净状态的文件
   • 验证状态（例如 36 项测试全部通过）

---

应做 / 不应做

• 应将删除死代码（死代码）、精简提示词（提示词臃肿）、还原外观（差异噪声）和舍弃罕见情况（边缘情况权衡）视为彼此独立、互不重叠的工作类别。
• 不应重写可正常工作的架构；精简应做减法。
• 应通过具体的调用图证明代码可达性，然后再声称代码已失效。
• 不应在不列出调用方和需求的情况下说“这看起来没必要”。
• 应按用途搜索同级功能，再决定是否保留用于解决仓库中已有问题的新代码。
• 不应在 边缘情况权衡 之外删减行为，也绝不要称某项权衡为等效或“最小化”；每项权衡都必须说明失去了什么。
• 不应让安全性、隔离性、数据完整性、资金或隐私保护低于仓库既有标准。
• 应先查明某行被移动的原因，并证明其与规范形式等效，再将其视为纯外观更改。
• 不应仅凭表象将导入、声明移动、空白字符、生成文件或文件模式归类为噪声。
• 应采取失败关闭策略：对不确定的外观问题，保留在差异中，并排除在 差异噪声 之外。
• 应在修改代码前通过 ask_question 获得明确的人工批准。