Back to Details

reclaim-code-entropy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Reclaim Code Entropy

回收代码熵

Treat code entropy as maintenance surface with no current load-bearing reason: extra representations, states, APIs, branches, packages, policies, or tests that the product must keep coherent.
Core rule: a scanner produces candidates; only consumer, ownership, history, and verification evidence justify deletion. Prefer a few proved cuts over a long speculative list. Finding nothing safe to remove is a valid result.
将代码熵视为当前无承载价值的维护面：产品必须保持一致性的额外表示、状态、API、分支、包、策略或测试。
核心规则：扫描工具生成候选对象；只有使用者、归属权、历史记录和验证证据才是删除的依据。优先选择少量已证实可删除的内容，而非冗长的推测性列表。未找到可安全移除的内容也是合理结果。

Choose The Mode

选择操作模式

  • For "audit", "find", "review", or "report", inspect only and return ranked candidates. Do not edit.
  • For "apply", "remove", "clean up", "simplify", or "refactor", implement the safest requested cuts and verify them.
  • Treat removal of a reachable user capability, supported public API, persisted format, or compatibility path as a product decision. Surface the visible tradeoff before changing it unless the user already made that decision explicitly.
  • 若为「审计」「查找」「审查」或「报告」，仅进行检查并返回排序后的候选对象，不做编辑。
  • 若为「应用」「移除」「清理」「简化」或「重构」，执行最安全的请求删除操作并进行验证。
  • 将可访问的用户功能、受支持的公共API、持久化格式或兼容性路径的移除视为产品决策。除非用户已明确做出该决策，否则在更改前需明确展示可见的权衡。

Establish The Contract

确立操作规范

  1. Read repository instructions and the nearest scoped equivalents: 
    AGENTS.md
    , 
    CONTRIBUTING
    , architecture docs, ADRs/RFCs/decision notes, package manifests, and test guidance.
  2. Inspect 
    git status
    ; preserve unrelated work. Identify generated, vendored, migration, fixture, and public-package paths before classifying code.
  3. Trace the real runtime flow through entrypoints, configuration, registries, dependency injection, events, queues, persistence, processes/workers, and wire protocols.
  4. In apply mode, discover the repository's actual narrow and broad verification commands and run a proportional baseline when feasible. A red baseline limits what later checks can prove; record it instead of claiming a regression.
Do not simplify away validation at trust boundaries, authorization, security controls, accessibility basics, data-loss prevention, durable-data compatibility, or cleanup that establishes resource quiescence.
  1. 阅读仓库说明及最相关的范围等效文档：
    AGENTS.md
    、
    CONTRIBUTING
    、架构文档、ADRs/RFCs/决策记录、包清单和测试指南。
  2. 检查
    git status
    ；保留无关工作。在对代码分类前，识别生成代码、第三方依赖代码、迁移代码、测试夹具代码和公共包路径。
  3. 追踪通过入口点、配置、注册表、依赖注入（dependency injection）、事件、队列、持久化、进程/工作线程和网络协议的真实运行时流程。
  4. 在应用模式下，发现仓库实际的窄范围和宽范围验证命令，并在可行时运行相应的基线测试。若基线测试失败，限制后续检查可证明的内容；记录该情况而非声称出现回归。
不要简化信任边界处的验证、授权、安全控制、基础可访问性、数据丢失防护、持久数据兼容性，或用于确保资源静止状态的清理逻辑。

Survey For Entropy

排查代码熵

Start with large or central production surfaces, not only obvious unused symbols. Use repository-native tools first: 
rg --files
, 
rg
, compiler/linter output, dependency manifests, and 
git log
. Run installed dead-code or dependency tools when useful, but treat every result as a lead.
Look for these candidate classes:
  1. Unconsumed surface: public methods, exports, events, config keys, hooks, packages, registry notifications, or protocol fields with no production consumer.
  2. Mirrored fact: two events, caches, summaries, state stores, snapshots, or adapters record the same truth and must be synchronized.
  3. Speculative generality: unset knobs, fixed feature flags, unused fallbacks, one-implementation interfaces, abandoned stubs, or extension points with no owner.
  4. Extra route or layer: multiple front doors to one behavior, forwarding-only wrappers, pass-through packages, or helpers that obscure a single caller.
  5. Lifecycle duplication: several flags, sentinels, promises, queues, or controllers represent one transition such as ready, stopped, settled, flushed, or disposed.
  6. Misplaced defense: copies, freezes, validators, rollback paths, or hostile-object tests protect a same-process typed handoff rather than an actual trust or ownership boundary.
  7. Hand-rolled infrastructure: local parsers, retry loops, globbing, framing, diffing, or data structures already covered by the standard library, native platform, or an installed dependency.
  8. Support-only residue: tests or docs are the only consumers; duplicate expected outputs; obsolete inventories; demo/test packages that impose runtime or publishing cost.
  9. Added-then-abandoned residue: implementation disappeared but flags, schemas, docs, tests, compatibility branches, or decision notes still describe it.
Do not confuse duplication with necessary independence. Separate backends, adapters, representations, or lifecycle mechanisms may intentionally test a contract or protect distinct owners.
从大型或核心生产面开始，而非仅关注明显未使用的符号。优先使用仓库原生工具：
rg --files
、
rg
、编译器/检查器输出、依赖清单和
git log
。在有用时运行已安装的死代码或依赖分析工具，但将每个结果视为线索。
寻找以下候选类别：
  1. 未被使用的接口：无生产环境使用者的公共方法、导出项、事件、配置键、钩子、包、注册表通知或协议字段。
  2. 镜像事实：两个事件、缓存、摘要、状态存储、快照或适配器记录相同事实且必须保持同步。
  3. 推测性通用性：未设置的旋钮、固定的功能标志、未使用的回退、仅一个实现的接口、已弃用的存根或无归属者的扩展点。
  4. 额外路由或层级：同一行为的多个入口、仅做转发的包装器、透传包，或掩盖单一调用者的辅助工具。
  5. 生命周期重复：多个标志、标记、Promise、队列或控制器表示同一状态转换，如就绪、停止、稳定、刷新或释放。
  6. 错位防护：复制、冻结、验证器、回滚路径或恶意对象测试保护的是同进程类型传递，而非实际的信任或归属边界。
  7. 自研基础设施：本地解析器、重试循环、通配匹配、帧处理、差异对比或数据结构，而这些功能已被标准库、原生平台或已安装的依赖覆盖。
  8. 仅用于支持的残留：测试或文档是唯一使用者；重复的预期输出；过时的清单；带来运行时或发布成本的演示/测试包。
  9. 添加后弃用的残留：实现已消失，但标志、 schema、文档、测试、兼容性分支或决策记录仍在描述它。
不要将重复与必要的独立性混淆。独立的后端、适配器、表示或生命周期机制可能是为了有意测试契约或保护不同的归属者。

Prove Or Reject A Candidate

验证或排除候选对象

For each exact symbol, behavior, or artifact:
  1. Search its symbol, file path, package name, config key, event/wire string, and alternate call syntax across the whole repository.
  2. Classify every hit:
    • Production: runtime source, shipped configuration, real entrypoints, migrations, operational scripts.
    • Non-production: tests, docs, comments, snapshots, generated expected output.
    • Ambiguous: examples, fixtures, plugins, reflection, registries, lazy imports, code generation, externally consumed exports. Inspect before classifying.
  3. Inspect callers and callees, not only search counts. Check dynamic loading, stringly typed dispatch, routes, plugin manifests, DI containers, serialization, environment-keyed lookup, and external package contracts.
  4. Read history and decision records. Ask what problem created the surface, whether that problem still exists, and what evidence now beats the original rationale.
  5. Draw ownership for asynchronous or stateful code. Map each state flag, disposer, cancellation path, readiness promise, and terminal outcome to a distinct owner or transition.
  6. State what capability or behavior the deletion gives up, even if the answer is "none observable".
  7. Estimate net reduction: code, tests dedicated only to that code, docs, config, generated artifacts, dependencies, and concepts removed minus replacement glue and migrations added.
  8. Name the smallest check that would fail if the simplification were wrong.
Keep or downgrade a candidate when any of these holds:
  • A real production or external consumer exists.
  • Dynamic reachability or compatibility cannot be ruled out.
  • A current decision record justifies the surface and new evidence does not beat it.
  • Churn moves complexity elsewhere without shrinking the contract or number of truths.
  • The candidate is tiny, uncertain, or unrelated to the requested scope.
Use this compact evidence record in audit output:
text
[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. 检查调用者和被调用者，而非仅搜索计数。检查动态加载、字符串类型调度、路由、插件清单、DI容器、序列化、环境键查找和外部包契约。
  4. 阅读历史记录和决策记录。明确该接口解决的问题是什么，该问题是否仍然存在，以及现有哪些证据可以推翻最初的理由。
  5. 确定异步或有状态代码的归属者。将每个状态标志、释放器、取消路径、就绪Promise和最终结果映射到明确的归属者或转换过程。
  6. 说明删除会放弃哪些功能或行为，即使答案是“无可见影响”。
  7. 估算净减少量：移除的代码、仅针对该代码的测试、文档、配置、生成工件、依赖项和概念，减去添加的替代粘合代码和迁移代码。
  8. 指出如果简化错误，会失败的最小检查项。
当满足以下任一条件时，保留或降级候选对象：
  • 存在真实的生产环境或外部使用者。
  • 无法排除动态可达性或兼容性需求。
  • 当前决策记录证明该接口存在的合理性，且新证据无法推翻它。
  • 修改仅将复杂度转移到其他地方，而未缩小契约范围或减少事实数量。
  • 候选对象规模极小、存在不确定性，或与请求范围无关。
在审计输出中使用以下简洁的证据记录格式：
text
[置信度 / 风险] 候选对象
证据：生产环境使用者；动态/公共/兼容性检查；归属理由
删除内容：确切的代码、工件、依赖项和移除的概念
权衡：失去的可见功能或行为
验证：最具决定性的最小检查项；估算的净减少量

Implement A Proven Cut

执行已验证的删除操作

  1. Work in one ownership boundary at a time. Fix the shared source of entropy rather than patching every caller.
  2. Delete the obsolete contract end to end: declaration, implementations, branches, tests that exist only for the removed behavior, exports, config, docs, examples, snapshots, generated inventories, and dependency entries.
  3. Preserve tests of the surviving observable contract. Tests are evidence, not an untouchable specification and not disposable merely to improve the line count.
  4. Collapse mirrored state onto the load-bearing representation. Do not replace two truths with a synchronization wrapper.
  5. Prefer deletion, then standard library/native features, then already-installed dependencies. Add a dependency only when it removes more implementation and dedicated testing burden than its glue and supply-chain cost add.
  6. Avoid compatibility shims when there is no compatibility obligation. When one exists, keep the path or design an explicit migration instead of silently deleting it.
  7. Keep batches reviewable and reversible. Never discard unrelated user changes.
Net-negative lines are evidence of a cut, not the goal. A safe simplification may add a small test or migration; a large deletion can still be wrong.
  1. 每次在一个归属边界内操作。修复代码熵的共享来源，而非修补每个调用者。
  2. 端到端删除过时契约：声明、实现、分支、仅针对移除行为的测试、导出项、配置、文档、示例、快照、生成的清单和依赖项条目。
  3. 保留针对留存可见契约的测试。测试是证据，而非不可触碰的规范，也不能仅仅为了减少行数而丢弃。
  4. 将镜像状态合并到承载核心功能的表示中。不要用同步包装器替代两个重复的事实。
  5. 优先选择删除，其次是使用标准库/原生功能，然后是已安装的依赖项。只有当添加依赖项减少的实现和专用测试负担超过其粘合代码和供应链成本时，才添加依赖项。
  6. 若无兼容性义务，避免使用兼容性垫片。若存在兼容性义务，保留兼容路径或设计明确的迁移方案，而非静默删除。
  7. 确保批量操作可审查、可回滚。永远不要丢弃用户的无关更改。
代码行数净减少是删除操作的证据，而非目标。安全的简化操作可能会添加少量测试或迁移代码；大规模删除仍可能存在错误。

Validate The Result

验证结果

After each non-trivial batch:
  1. Search again for deleted symbols, strings, paths, and stale documentation.
  2. Run the narrowest decisive test first, then the repository's broad relevant type, lint, test, build, codegen, or smoke gates.
  3. Re-run any static analyzer that produced the candidate.
  4. Run 
    git diff --check
    when Git is available and inspect the complete diff for accidental scope expansion.
  5. Compare behavior at public, persisted, wire, and user-visible boundaries. Measure performance only if a performance claim is made.
If verification fails, identify whether the candidate was load-bearing, the implementation was incomplete, or the baseline was already red. Revert only the current batch or repair the proof; do not weaken a meaningful check to force the deletion through.
每次非 trivial 的批量操作后：
  1. 再次搜索已删除的符号、字符串、路径和过时文档。
  2. 先运行最具决定性的窄范围测试，再运行仓库相关的宽范围类型检查、代码检查、测试、构建、代码生成或冒烟测试。
  3. 重新运行生成候选对象的静态分析工具。
  4. 若Git可用，运行
    git diff --check
    并检查完整差异，防止意外扩大范围。
  5. 比较公共、持久化、网络和用户可见边界处的行为。仅在提出性能声明时才测量性能。
若验证失败，确定候选对象是否为核心承载功能、实现是否不完整，或基线测试原本就失败。仅回滚当前批量操作或修复验证依据；不要为了强行删除而削弱有意义的检查。

Report The Outcome

报告结果

For an audit, rank the strongest candidates by confidence, risk, and net maintenance reduction. Include rejected or uncertain high-value candidates only when the missing evidence is actionable.
For applied changes, report:
  • what contract or duplicate truth was removed;
  • files, lines, dependencies, and concepts removed where measurable;
  • any user-visible capability or compatibility behavior changed;
  • exact validation run and result;
  • high-value candidates intentionally kept and why.
对于审计，按置信度、风险和维护成本净减少量排序最强候选对象。仅当缺失的证据可操作时，才包含被拒绝或不确定的高价值候选对象。
对于已应用的更改，报告：
  • 移除的契约或重复事实；
  • 可测量的已移除文件、行数、依赖项和概念；
  • 任何用户可见的功能或兼容性行为变更；
  • 执行的确切验证及结果；
  • 有意保留的高价值候选对象及其原因。