absolute-debt

请以 🧾 表情符号作为首次回复的开头。

Absolute Debt

分批次、按规则清理整个仓库中累积的 lint 和类型检查债务——包括长期积累的警告、错误和抑制项——并确保每批修复后测试都通过。目标是真正让 lint 和 typecheck 干净，而不是让输出变少。

运行 references/health-engine.md 中的共享引擎——请阅读其中的 DETECT → SCAN → TRIAGE → FIX → VERIFY → REPORT 循环和安全约定。本文件仅介绍 lint 和类型债务的特定内容。

---

适用场景

• “修复 lint 警告”“清理类型错误”“让代码库达到严格模式”。
• 收紧配置（启用规则、提高 tsconfig 严格程度）并处理由此产生的问题。
• 清理累积的 eslint-disable / @ts-ignore / # type: ignore 抑制项。

debt 与 simplify： simplify 用于提升当前工作差异的质量。debt 用于清理在绿色 main 上仓库范围内预先存在的 lint/类型违规。用 debt 处理长期积累的清理工作，而不是当前正在进行的修改。

---

扫描范围

生态系统	Lint 债务	类型债务
JS/TS	eslint .（完整报告，按规则分类）	tsc --noEmit
Python	ruff check / flake8	mypy / pyright
Go	golangci-lint run	go vet ./...、staticcheck

还要将抑制项本身列为债务：eslint-disable*、 @ts-ignore/@ts-expect-error、# type: ignore、# noqa、//nolint。每一项都是隐藏的 违规。按规则（而非文件）统计违规数量——这样才能分批次处理。

---

风险排序（TRIAGE）

批次	类别	默认处理方式
1	可自动修复的 lint（eslint --fix、ruff --fix、gofmt）	立即修复——机械性操作，安全
2	按规则手动修复的 lint，行为风险低（未使用项、样式、导入）	本轮修复，一次处理一条规则
3	类型错误，以及修复不当可能改变行为的 lint 规则	设门槛——逐项审查，可能需要修改实际逻辑
4	移除抑制项（@ts-ignore 等）	设门槛——每一项都可能暴露真实错误

每个批次应针对整个仓库的一条规则进行修复，而不是在单个文件中一次处理所有规则——这样差异更易审查，回归问题也更易二分定位。收紧配置（启用规则 / 提高严格程度）本身就是一项发现：先提出，再清理它暴露的问题。

---

修复与验证

• 先运行自动修复工具（第 1 批），整理成可提交的状态，然后重新扫描，找出真正需要手动修复的内容。
• 手动修复时，应解决根本原因，而非表面症状。类型错误意味着某处类型有误——应修正类型，不要强制转换为 any / 添加 # type: ignore。
• 绝不要通过添加抑制项来清除违规。移除抑制项才是目标，而非修复手段。
• 每个批次完成后：运行完整的测试、lint、类型检查和构建。违规数量必须减少，且不能引入回归。

---

注意事项

1. 通过添加抑制项来修复。 用 @ts-ignore 清除类型错误会增加债务。本流程禁止这样做。
2. 用 any / 强制转换蒙混过关。 这只会让检查器不再报错，问题仍然存在。应修正真正的类型。
3. 单文件处理所有规则。 这会混杂不同问题，导致差异难以审查。应按规则处理所有文件。
4. 不经审查就自动修复。 --fix 可能改变行为（例如，由于 bug，对重新赋值的变量应用 prefer-const）。自动修复后也要运行测试。
5. 禁用规则，而不是修复问题。 放宽配置以达到零违规是在转移债务，并非偿还债务。

---

配套命令

• /absolute simplify ——提升当前正在修改的代码的质量。
• /absolute prune ——清理死代码后，许多未使用变量/导入警告会随之消失。
• /absolute work ——如果清理债务需要实际重构，请交接处理。