reclaim-code-entropy

收回代码熵

将代码熵视为当前没有承载理由的维护面：产品必须持续保持一致的额外表示、状态、API、分支、包、策略或测试。

核心规则：扫描器负责生成候选项；只有消费者、所有权、历史记录和验证证据才能证明删除合理。优先做少数有证据支持的精简，而不是列出一长串猜测性清单。没有找到安全的删除项也是有效结果。

选择模式

• 对于“审计”“查找”“审查”或“报告”，只做检查并返回按优先级排列的候选项。不要编辑。
• 对于“应用”“删除”“清理”“简化”或“重构”，实施请求中最安全的精简，并进行验证。
• 将删除可触达的用户功能、受支持的公共 API、持久化格式或兼容路径视为产品决策。除非用户已明确作出该决定，否则应先说明对用户可见的取舍，再进行更改。

明确约定

1. 阅读仓库说明及范围最近的对应文件：AGENTS.md、CONTRIBUTING、架构文档、ADR/RFC/决策记录、包清单和测试指南。
2. 检查 git status；保留无关工作。在对代码分类之前，先识别生成内容、供应商代码、迁移、固定数据和公共包所在路径。
3. 沿着入口、配置、注册表、依赖注入、事件、队列、持久化、进程/工作线程和线协议，追踪实际运行时流程。
4. 在应用模式下，查明仓库实际使用的窄范围和广范围验证命令，并在可行时按比例运行基线检查。基线已有失败会限制后续检查能证明的内容；应记录这些失败，而不是声称它们是回归问题。

不要删减信任边界上的验证、授权、安全控制、无障碍基础保障、防止数据丢失的措施、持久化数据兼容性，或用于确保资源静止的清理逻辑。

调查代码熵

从大型或核心的生产代码入手，不要只关注显而易见的未使用符号。优先使用仓库原生工具：rg --files、rg、编译器/代码检查器输出、依赖清单和 git log。有用时可运行已安装的死代码或依赖分析工具，但应将每项结果都视为线索。

关注以下候选类别：

1. 未消费的表面：没有生产代码消费者的公共方法、导出项、事件、配置键、钩子、包、注册表通知或协议字段。
2. 重复记录的事实：两个事件、缓存、摘要、状态存储、快照或适配器记录相同事实，且必须保持同步。
3. 推测性的通用设计：未设置的旋钮、固定的功能标志、未使用的回退方案、只有一个实现的接口、被弃用的存根或没有所有者的扩展点。
4. 多余的路径或层：多个入口通向同一行为、只负责转发的包装器、仅作透传的包，或掩盖单一调用方的辅助工具。
5. 生命周期重复：多个标志、哨兵值、Promise、队列或控制器表示同一个转换，例如就绪、停止、完成、刷新或释放。
6. 位置不当的防御措施：副本、冻结、验证器、回滚路径或恶意对象测试，保护的是同一进程内的类型化交接，而非实际的信任边界或所有权边界。
7. 手写基础设施：已有标准库、原生平台功能或已安装依赖能够处理的本地解析器、重试循环、通配符匹配、分帧、差异比较或数据结构。
8. 仅用于支持的残留项：唯一消费者是测试或文档的代码；重复的预期输出；过时的清单；会增加运行时或发布成本的演示/测试包。
9. 添加后弃用的残留项：实现已消失，但标志、架构、文档、测试、兼容分支或决策记录仍在描述它。

不要把重复误认为必要的独立性。不同的后端、适配器、表示形式或生命周期机制，可能是为了有意测试某项约定或保护不同的所有者。

证明或否定候选项

对于每个确切的符号、行为或产物：

1. 在整个仓库中搜索其符号、文件路径、包名、配置键、事件／线上字符串以及其他调用语法。
2. 对每个命中进行分类：
   • 生产代码：运行时源代码、随产品发布的配置、实际入口点、迁移脚本、运维脚本。
   • 非生产代码：测试、文档、注释、快照、生成的预期输出。
   • 不明确：示例、固定数据、插件、反射、注册表、延迟导入、代码生成、供外部使用的导出。分类前先检查。
3. 检查调用方和被调用方，而不只是搜索结果数量。检查动态加载、基于字符串的分发、路由、插件清单、依赖注入容器、序列化、按环境键查找以及外部包契约。
4. 阅读历史记录和决策记录。了解是什么问题促成了这个接口、该问题是否仍然存在，以及现有哪些证据足以推翻最初的理由。
5. 梳理异步或有状态代码的所有权。将每个状态标记、释放器、取消路径、就绪 Promise 和终止结果对应到不同的所有者或状态转换。
6. 说明删除会放弃哪些能力或行为，即使答案是“没有可观察到的影响”。
7. 估算净减少量：移除的代码、仅针对该代码的测试、文档、配置、生成产物、依赖项和概念，减去新增的替代粘合代码和迁移工作。
8. 指出一项最小检查，说明如果简化有误，它会在哪里失败。

出现以下任一情况时，保留或降低候选项的优先级：

• 存在实际生产使用方或外部使用方。
• 无法排除动态可达性或兼容性问题。
• 当前决策记录为该接口提供了正当理由，且新证据不足以推翻该理由。
• 变更只是将复杂性转移到其他位置，并未缩小契约或减少事实来源的数量。
• 候选项很小、结论不确定，或与请求范围无关。

在审查输出中使用以下简明证据记录：

[confidence / risk] candidate
evidence: production consumers; dynamic/public/compatibility checks; owning rationale
cut: exact code, artifacts, dependency, and concept removed
tradeoff: observable capability or behavior lost
verify: smallest decisive check; estimated net reduction

实施有证据支持的删减

1. 每次只处理一个所有权边界。修复共同的复杂性源头，而不是逐个修补调用方。
2. 端到端删除过时契约：声明、实现、分支、仅用于已移除行为的测试、导出、配置、文档、示例、快照、生成清单和依赖项。
3. 保留对现存可观察契约的测试。测试是证据，不是不可触碰的规范，也不能为了减少行数而随意丢弃。
4. 将镜像状态归并到承载真实状态的表示上。不要用同步包装层替代两个事实来源。
5. 优先删除，其次使用标准库／原生功能，再其次使用已安装的依赖项。只有当新增依赖所减少的实现和专用测试负担，大于其粘合代码和供应链成本时，才添加依赖。
6. 不存在兼容性义务时，避免使用兼容性垫片。若确有兼容性义务，应保留原有路径或设计明确的迁移方案，而不是悄无声息地删除。
7. 保持变更批次便于审查和回退。切勿丢弃无关的用户改动。

代码行数净减少是删减的证据，而非目标。安全的简化可以增加少量测试或迁移代码；大规模删除仍可能是错误的。

验证结果

每完成一批有实质意义的改动后：

1. 再次搜索已删除的符号、字符串、路径和过时文档。
2. 先运行范围最窄且结论明确的测试，再运行仓库中相关范围更广的类型检查、lint、测试、构建、代码生成或冒烟测试。
3. 重新运行生成候选项的任何静态分析器。
4. 如果可以使用 Git，则运行 git diff --check，并检查完整差异，确认没有意外扩大改动范围。
5. 对照公共接口、持久化、线缆协议和用户可见边界处的行为。只有在提出性能声明时才测量性能。

如果验证失败，请确定候选项是否承担关键作用、实现是否不完整，或基线本身是否已有问题。只回滚当前批次，或修复验证过程；不要削弱有意义的检查来强行通过删除操作。

报告结果

对于审计，请按可信度、风险和净维护成本降低幅度，对最有力的候选项排序。只有当缺失的证据可采取行动时，才纳入被否决或尚不确定的高价值候选项。

对于已应用的改动，请报告：

• 移除了哪些契约或重复事实；
• 删除的文件、行数、依赖项和概念（如可衡量）；
• 用户可见功能或兼容性行为的任何变化；
• 运行的确切验证及结果；
• 有意保留的高价值候选项及原因。