gjalla-cleanup-audit
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCleanup Audit
代码清理审计
Find the code that is costing us in maintenance costs, causing confusion to agents and humans who onboard. Usually this is due to being unused, duplicated, or overengineered.
You must prove something is dead before deleting it. Grep does not see every reference, and removing code with a full confidence verification will result in production incidents.
找出那些增加维护成本、给新入职的Agent和开发人员造成困惑的代码。这类问题通常源于代码未被使用、存在重复或过度设计。
在删除代码前，必须先证明它已废弃。 Grep无法发现所有引用，若未经过充分验证就删除代码，可能会导致生产事故。
Process
流程
Phase 1: Orient
阶段1：定位范围
Establish your boundary. Within the repo is great, make sure that you consider cross-repo interoperability when assessing impact. gjalla can help you with this.
Briefly review recent changes to give you an idea of hotspots, though no areas should be ignored.
Check architecture, rules, learnings, and system evolution in gjalla.
明确审计边界。以代码仓库（repo）内的代码为主，评估影响时务必考虑跨仓库的互操作性。gjalla可协助完成此项工作。
简要查看近期代码变更，了解代码热点区域，但任何区域都不应被忽略。
在gjalla中查看架构、规则、经验总结及系统演进情况。
Phase 2: Investigate
阶段2：排查问题
Find dead code, duplicated logic (or very similar but drifted), overengineering, code that doesn't follow intended architectural patterns (therefore causing spaghetti code), additions that are chaotic, etc.
找出死代码、重复逻辑（或高度相似但已偏离的逻辑）、过度设计的代码、不符合既定架构模式的代码（此类代码会导致面条式代码）、混乱添加的代码等。
Phase 3: Verify
阶段3：验证确认
For every candidate, enumerate references across the whole boundary, including ways that references can hide from grep. For example, be especially careful with public API endpoints because you cannot see all callers.
针对每个候选对象，枚举整个边界内的所有引用，包括那些能避开grep检测的引用方式。例如，需特别注意公共API endpoints，因为你无法看到所有调用方。
Phase 4: Classify
阶段4：分类处理
| Tier | Description | Action |
|---|---|---|
| Tier 1 | Provably dead: zero references after full enumeration, no dynamic or external reach | Delete, with its tests |
| Tier 2 | Dead in code but leaves data behind (orphaned rows, columns) | Delete code now; decide on data separately and deliberately |
| Tier 3 | Duplication with a clear owner | Consolidate to one implementation, keep the best-tested one |
| Tier 4 | Suspicious but unproven, or reachable from outside the boundary | Report, do not delete. Name what would settle it |
| Stale claims | Comments, docs, specs asserting things that aren't true | Correct immediately — cheapest and highest-value fix in the audit |
| 层级 | 描述 | 操作 |
|---|---|---|
| Tier 1 | 已确认废弃：经全面枚举后无任何引用，无动态调用或外部访问路径 | 删除代码及其对应的测试用例 |
| Tier 2 | 代码已废弃但遗留数据（孤立行、列） | 立即删除代码；数据的处理需单独决策、谨慎执行 |
| Tier 3 | 存在重复逻辑且有明确负责人 | 合并为单一实现，保留测试覆盖最完善的版本 |
| Tier 4 | 疑似废弃但未证实，或可从边界外部访问 | 仅上报，不删除。说明需何种证据才能确认状态 |
| 过时声明 | 注释、文档、规范中存在与实际不符的内容 | 立即修正——这是审计中成本最低、价值最高的修复操作 |
Phase 5: Remove in waves
阶段5：分批移除
Leaf-first, so nothing breaks midway: tests, then callers, then the implementation, then the data file or module. Run the relevant suite between waves. Keep each wave independently revertible, and don't mix a deletion wave with a refactor.
按照从叶子节点到根节点的顺序操作，避免中途出现故障：先移除测试用例，再移除调用方，接着移除实现代码，最后移除数据文件或模块。每批操作后运行相关测试套件。确保每批操作均可独立回滚，且不要将删除操作与重构操作混合进行。
Output
输出成果
- Tier 1 deletions: file paths, line counts, and the enumeration that proves each is dead.
- Tier 3 consolidations: which copies exist, which survives, what test pins the behavior.
- Tier 4 unproven: what you suspect and what evidence would settle it.
- Stale claims corrected: what was asserted, what is actually true.
- Impact: what gets simpler, what risk you accepted, what you deliberately left alone.
- Tier 1 删除项：文件路径、代码行数，以及证明每项代码已废弃的枚举依据。
- Tier 3 合并项：存在哪些重复副本、保留哪一个实现、用于固定行为的测试用例。
- Tier 4 未证实项：你的怀疑点，以及需要何种证据才能确认状态。
- 已修正的过时声明：原声明内容、实际真实情况。
- 影响评估：哪些内容变得更简洁、你承担了哪些风险、哪些内容被刻意保留。
Principles
原则
- Proof, not confidence. "I couldn't find a caller" and "there is no caller" are different claims. Report which one you have.
- Deletion is the best refactor. Code that doesn't exist has no bugs, needs no tests, and confuses nobody.
- Don't delete data on a code audit. Rows outlive the code that wrote them and may have been edited since. Removing the writer is a code decision; removing what it wrote is a product decision, and it belongs to a human.
- Fix the misleading thing first. A stale comment or a spec claiming finished work will cause a wrong decision faster than dead code will.
- One concern per change. A cleanup that also "improves things while in there" is impossible to review and impossible to revert cleanly.
- 重证据，而非主观判断。 “未找到调用方”和“不存在调用方”是两种不同的结论，需明确说明你得出的是哪一种。
- 删除是最佳重构方式。 不存在的代码不会有bug，无需测试，也不会造成任何混淆。
- 代码审计中不要删除数据。 数据的生命周期比写入它的代码更长，且可能自写入后被修改过。移除写入代码是技术决策；而移除数据属于产品决策，需由相关负责人决定。
- 优先修正误导性内容。 过时的注释或声称已完成工作的规范，比死代码更快导致错误决策。
- 每次变更只解决一个问题。 若在清理代码的同时“顺便优化其他内容”，则该变更既难以评审，也无法干净利落地回滚。