typescript-best-practices

TypeScript のベストプラクティス

Muse では、このスキルに従う前に、スキルごとの注意事項を含め、プラットフォームのマッピングを確認してください。

まず 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。