gjalla-cleanup-audit

清理审计

找出那些增加维护成本、让新加入的 Agent 和人类感到困惑的代码。通常，这是因为代码未被使用、存在重复，或过度设计。

删除之前，必须证明某段代码已无用。 grep 无法发现所有引用，而在未进行充分验证的情况下删除代码，会导致生产事故。

流程

第 1 阶段：了解情况

确定审查范围。在仓库内审查很好，但评估影响时，请务必考虑跨仓库互操作性。gjalla 可以为你提供帮助。 简要查看近期变更，以了解重点区域，但不应忽略任何区域。 检查 gjalla 中的架构、规则、经验总结和系统演进记录。

第 2 阶段：调查

找出无用代码、重复逻辑（或非常相似但已经出现偏差的逻辑）、过度设计、不遵循预期架构模式（因而导致意大利面式代码）的代码、混乱添加的内容等。

第 3 阶段：验证

针对每个候选项，枚举整个审查范围内的引用，包括那些可能无法通过 grep 发现的引用方式。例如，对于公共 API 端点要格外谨慎，因为你无法看到所有调用方。

第 4 阶段：分类

层级	描述	操作
层级 1	可证明确实无用：完整枚举后没有任何引用，也不存在动态或外部调用路径	删除及其测试
层级 2	代码已无用，但仍有数据遗留（孤立的行、列）	立即删除代码；单独、审慎地决定如何处理数据
层级 3	存在重复实现，且有明确的负责方	合并为一个实现，保留测试覆盖最佳的实现
层级 4	有可疑之处但尚未证实，或可从审查范围之外访问	报告，不要删除。说明哪些证据可以定论
过时的断言	声称实际并非如此的注释、文档、规格说明	立即修正——这是审计中成本最低、价值最高的修复

第 5 阶段：分批移除

从叶节点开始，确保中途不会破坏任何内容：先删除测试，再删除调用方，然后删除实现，最后删除数据文件或模块。每批之间运行相关测试套件。确保每批都能独立回滚，不要把删除和重构混在一起。

输出

1. 层级 1 删除项：文件路径、行数，以及证明每项无用的枚举结果。
2. 层级 3 合并项：存在哪些副本、保留哪一个，以及哪个测试可以固定其行为。
3. 层级 4 未证实项：你怀疑哪些内容，以及哪些证据可以定论。
4. 已修正的过时断言：之前声称了什么，实际情况如何。
5. 影响：哪些内容变得更简单、接受了哪些风险，以及有意保留了哪些内容。

原则

• 要证据，不要凭把握。“我没找到调用方”和“没有调用方”是两种不同的说法。请说明你能证明的是哪一种。
• **删除是最好的重构。**不存在的代码不会有缺陷，不需要测试，也不会让任何人困惑。
• **不要在代码审计中删除数据。**数据行会比写入它们的代码存在得更久，而且此后可能已被修改。移除写入逻辑是代码层面的决定；移除其写入的数据是产品层面的决定，应由人来做。
• **先修正误导性内容。**过时的注释或声称工作已完成的规格说明，比无用代码更容易引发错误决策。
• **一次变更只处理一个问题。**如果清理时还顺手“改进其他内容”，就会变得难以审查，也无法干净地回滚。