typescript-best-practices について
安全で明確なコードを書くための、TypeScript の型システムと実装指針をまとめたスキルです。バリアントのモデル化、境界での外部データ検証、実際のテスト機能による動作確認を扱います。
主な機能
- 01判別可能なユニオンでバリアントを表現
- 02境界で外部データを検証
- 03unknown とスキーマ由来の型を優先
- 04網羅性チェックの実施
- 05実際のテスト機能を使用
- 06構造化診断情報を出力
活用シーン
- 01ドメイン型とスキーマの設計
- 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 対応