typescript-best-practices

TypeScript のベストプラクティス

太字またはバッククォートで記載されているスキル名、あるいは /<name> として実行するスキルは、このスキルのディレクトリと同じ階層にある ../<name>/SKILL.md ファイルです。接頭辞なしで記載されている原則名は ../principle-<name>/SKILL.md です。そのファイルを読み、従ってください。pstack のスキルの多くはユーザー専用のため、スキルツールでは読み込めません。

まず type-system-discipline の原則スキルを適用してください。

ルール	概要
判別可能なユニオン	kind リテラルを判別子として使い、バリアントをモデル化します。これにより、表現不可能な状態を作れます。オプショナルフィールドの寄せ集めは避けてください。
ブランド型	プリミティブ型に & { readonly __brand: "X" } を付けてブランド化し、取り違えを防ぎます。境界で一度だけ検証してください。ブランドは検証用の型ガード（input is AgentId）によって作成し、as で作成してはいけません。
構築的なモデリング	不正な値を構築できない形にします。空でない値には [T, ...T[]]、偶数個の値には [T, T][]、範囲には start と duration を使います。これは実行時ガードではなく、リファインメント型を望むことでもありません。
最も単純な全域型	すべての操作が全域的である限り、T[] を維持します。緩い型のために !、キャスト、または「起こるはずがない」という例外が必要になる場合に限り、NonEmpty<T> に強化します。
any より unknown	外部データには unknown を使います。
ガードよりスキーマ	プロパティごとの型ガードを手書きする前に、リポジトリの実行時スキーマライブラリを使い、z.infer などでスキーマから型を推論します。
as キャストなし	as は実行時クラッシュの原因になり得ます。検証後に限りキャストしてください。
絞り込みの優先順位	判別子による switch > in 演算子 > typeof／instanceof > ユーザー定義の型ガード > as。
型ガード	主張する内容を必ず検証してください。嘘をつく型ガードは、as よりも悪質です。安全だと示す名前の背後にバグが隠れるからです。isX または hasX という名前を付けてください。
網羅性	default 節に const _exhaustive: never = x; をインラインで記述し、新しいバリアントが追加されたときにコンパイラーがエラーを出すようにします。
as より satisfies	リテラル型を拡大させずに値を検証できます。
境界での検証	データが入ってくる境界でパースし、名前付きドメイン型に変換します。Record<string, unknown>（表記方法にかかわらず）はそのパースまでに限定します。内部では型を信頼してください。boundary-discipline の原則スキルを参照してください。
スキーマから導出する型	新しいインターフェースを宣言する前に、Pick／Omit／Parameters／ReturnType／Awaited／typeof を検討してください。
オブジェクト引数	位置引数ではなくオブジェクトを渡し、引数の順序が自明になるようにします。ホットパス（フレームごとのレンダリング、トークナイザー、パーサー）では省略してください。
実際のテスト	実行できるものをモックしないでください。リーク／破棄可能性のチェックを備えた、フレームワークの実際のテストプリミティブを優先し、実行中のビルドで UI を検証してください。ローカルで実行できないものだけをモックしてください。
構造化テレメトリー	ID からデバッグできるだけの情報を含む、構造化ロガーの診断機能を優先してください。出荷するコードでは console.log を使わないでください。

例：references/patterns.md。