code-quality

コードの作成やリファクタリングでは、型駆動の品質向上手法を少数適用します。各手法には、それぞれ原則、このリポジトリにおける実際の変更前／変更後の例、検索すべき問題の兆候をまとめたリファレンスがあります。目の前のコードに該当するリファレンスを読んでください。5つすべてをむやみに適用しないでください。

この手法を使う場面

コードや API の リファクタリング／整理／改善／堅牢化／引き締め の依頼を受けたとき、または新しいモジュール／型／公開エクスポートを作成する際に、最初から適切な形にしたいときに使います。バグの調査には使いません（/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. 一度に適用する手法は1つ。テストは成功したままにします。 型を変更し、tsc にすべての呼び出し箇所を示させて修正し、テストを実行します。レビューしきれない差分になるまで、5つのリファクタリングをまとめて行わないでください。
3. 過度な抽象化は避けます（rule-of-three／YAGNI）。実際に存在する3つのバリアントをタグ付きユニオンで表すのは適切です。まだ存在しない差異のための抽象化は、このスキルが防ごうとしている問題です。
4. 決定可能性が許す範囲で、最も強い選択肢を優先します。 不正な状態を表現できない型は、実行時に検出できることを期待するチェックより優れています。ただし、入力が本当に動的な場合は、境界での実行時ガードが何もしないより優れています。

ガードレール

• 対象は品質のみで、正しさではありません。 このスキルは形や設計を改善するもので、バグを探すものではありません。バグの調査には /code-review を使ってください。
• すべての変更で、現実に存在する失敗モードを1つ取り除きます。 新しい形で防げるバグを説明できないなら、変更しないでください。
• 公開する範囲は小さく保ちます。 新しい export は契約です（公開 API のリファレンスを参照）。リファクタリングを都合よく進めるために、公開範囲を広げないでください。