typescript-best-practices について
typescript-best-practices は、TypeScript の型システムを適切に使うためのスキルです。有効な状態のモデル化、境界でのデータ検証、実際の動作に基づくテストを重視します。
主な機能
- 01判別可能なユニオンによる変種のモデル化
- 02検証済みプリミティブへのブランド型の利用
- 03any より unknown を優先
- 04ランタイムスキーマからの型導出
- 05switch 分岐の網羅性チェック
活用シーン
- 01不正な状態を防ぐドメイン型の設計
- 02入力境界での外部データの検証
- 03TypeScript の型アサーションと型ガードのレビュー
- 04実際のテストフレームワークの機能を使ったテスト作成
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/typescript-best-practicesを入力して読み込まれたか確認します。
同梱ファイルreferences/patterns.md
詳細
TypeScript のベストプラクティス
まず type-system-discipline 原則のスキルを適用してください。
| ルール | 概要 |
|---|---|
| 判別可能なユニオン | kind のリテラル判別子を使ってバリアントをモデル化し、表現できない状態を作れないようにします。オプショナルフィールドの寄せ集めは使いません。 |
| ブランド型 | プリミティブ型に & { readonly __brand: "X" } を付け、取り違えを防ぎます。検証は境界で一度だけ行います。ブランドは検証する型ガード（input is AgentId）から付与し、as は使いません。 |
| 構成的なモデリング | 不正な値を構築できない形にします。空でない配列には [T, ...T[]]、偶数個の配列には [T, T][]、範囲には start と duration を使います。これは実行時ガードではなく、リファインメント型を望むことでもありません。 |
| 最も単純な全域型 | T[] に対するすべての操作が全域的である間は、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 対応