最后核对：2026-10-04（全库逐份翻新复核——标签体系与
#DXX编号约定未变，编号事实源《工程债务维护方案.md》持续在册。前一沿革 2026-09-11 前端切割后文档翻新）
目的
将隐形技术债务显式化，使维护者能快速定位已知待改进点、缺陷与临时 workaround。
注释标签
| 标签 | 含义 | 使用场景 | 示例 |
|---|---|---|---|
TODO(#<issue>): |
已知待改进点 | 有明确改进方向但当前未实现 | // TODO(#D08): 将此处 unwrap 替换为 Result 传播 |
FIXME(#<issue>): |
已知缺陷 | 代码能运行但行为/边界有问题 | // FIXME(#D14): 生产代码 unwrap 未清零，此处应改为 Result 传播以消除 panic 风险 |
HACK: |
临时 workaround | 为赶工期或绕过阻塞而采用的非理想方案 | // HACK: 通过空字符串占位避免 None 分支，后续应改 Option |
NOTE: |
重要设计决策 | 非显而易见的实现选择，需要解释原因 | // NOTE: 这里故意不用递归，避免深层嵌套栈溢出 |
SAFETY: |
unwrap/expect 合理性说明 | 对 clippy unwrap_used/expect_used 的豁免依据 |
// SAFETY: 前面已检查非空 |
编号约定
- 优先使用现有债务编号（如
#D07、#D08）或 GitHub issue 编号。 - 若无现成编号，可临时使用
#DXX并在工程债务维护方案.md中追加。 - 前端相关债务编号（
D02/D06/D09）已随前端切割（2026-09-11）冻结，不再新增：这三项对应的 Dart/Flutter 代码已迁出本仓库（标签before-frontend-split），编号保留在工程债务维护方案.md中备查，不得复用于新的 Rust 侧问题。
禁止行为
- 禁止用 TODO/FIXME 标记掩盖真实缺陷而不跟踪。
- 禁止过度标记（如每行都加 NOTE），应聚焦真正需要沟通的设计点。
- 禁止删除他人的 TODO/FIXME 而不说明原因；修复后应在提交信息中引用。
统计与 review
TODO/FIXME/HACK 数量统计：原 engineering_health / lint_check.sh 两工具的对象（native/ Rust 侧、前端 Dart 段）均已退役，两脚本已随删区批删除；moonbit/ 活跃区的 TODO 趋势统计暂无专用工具（如实记录——待补），当前以 `grep -r "TODO(#DXX)" moonbit/ 人工抽查。
MoonBit 侧沿用同一标签集与 #DXX 编号（// TODO(#DXX): 形式）；豁免依据标签对应 moon check / moon fmt 口径，新增活账目在工程债务维护方案登记。