typescript-best-practices について
型システムの規律をモデリング、検証、型の絞り込み、テストに適用する TypeScript 開発スキルです。不正な状態を型で防ぎ、データ境界で検証する方針を示します。
主な機能
- 01判別可能なユニオンによる変種のモデル化
- 02ブランド型によるプリミティブの区別
- 03any より unknown を優先
- 04ランタイムスキーマから型を導出
- 05データ境界での検証
- 06可能な限り実際のテスト機能を使用
活用シーン
- 01安全性の高い TypeScript ドメイン型の設計
- 02検証や型の絞り込みのレビュー
- 03テストとテレメトリーの改善
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/typescript-best-practicesを入力して読み込まれたか確認します。
同梱ファイルreferences/patterns.md
詳細
TypeScript のベストプラクティス
まず、type-system-discipline 原則スキルを適用してください。
| ルール | 概要 |
|---|---|
| 判別可能なユニオン | kind のリテラル判別子を使ってバリアントをモデル化し、表現不可能な状態を作れないようにします。オプションフィールドの寄せ集めは使いません。 |
| ブランド型 | プリミティブ型に & { readonly __brand: "X" } を付け、取り違えを防ぎます。検証は境界で一度だけ行います。 |
| 構成的モデリング | 不正な値を構築できないような形にします。空でない場合は [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。
コメント
Markdown 対応