code-quality

在编写或重构代码时，应用一小组类型驱动的质量技巧。每种技巧都有自己的参考文档，其中包含原则、本仓库中的真实改造前后示例，以及可供搜索的代码异味。阅读与当前代码相符的参考文档；不要不加区分地套用全部五种技巧。

适用场景

当有人要求_重构／清理／改进／强化／收紧_代码或 API 时；或者你准备编写新的模块、类型或公开导出，并希望一次就做好时。不是用于查找 bug（请使用 /code-review）。

技巧——阅读匹配的参考文档

当前遇到的代码异味	技巧	参考文档
魔法值 0／""／-1；同一原始值在多处反复校验；反复使用 "x" in obj	解析，不验证	references/parse-dont-validate.md
字段始终为 ""；布尔标志泛滥；用哨兵值表示“缺失”；不可能的组合仍能通过编译	让非法状态无法表示	references/make-illegal-states-irrepresentable.md
对联合类型使用 switch／if 链，却没有穷尽性检查	穷尽式匹配	references/exhaustive-matching.md
逻辑与 IO 缠在一起（spawn／fetch／fs）；函数难以测试	纯函数 + 注入接缝	references/pure-functions.md
公开导出的形状含糊不清；用 string 表示枚举；泄露内部辅助函数	公共 API 质量	references/public-api-quality.md

如何应用

1. 在改变结构前，明确说出你的决策——它禁止了哪种非法状态，解析边界在哪里（surface-architecture-decisions 习惯）。如果审查者看不出质量改进，就只是徒增改动。
2. 一次只用一种技巧，确保测试始终通过。 修改类型，让 tsc 列出所有调用点，逐一修复，然后运行测试。不要把五种重构捆成一个无法审查的差异。
3. 不要过度抽象（三次原则／YAGNI）。为 3 种真实变体使用标记联合类型是好做法；为尚不存在的差异创建抽象，正是这项技能旨在避免的错误。
4. 在可判定性允许的范围内，优先选择最强方案——无法表达错误状态的类型，胜过寄希望于运行时检查能发现问题；但如果输入确实是动态的，在边界进行运行时检查也胜过什么都不做。

防护原则

• 只关注质量，不关注正确性。 这项技能改进代码结构／设计；它不负责查找 bug——那是 /code-review 的职责。
• 每项改动都必须消除真实的故障模式。 如果你说不出新结构能防止什么 bug，就不要改。
• 保持公开接口精简。 新增 export 就是一份契约（参见公共 API 参考文档）；不要为了方便重构而扩大公开接口。