typescript-best-practices について
無効な状態を型で表現しにくくすることを重視した、TypeScript 開発者向けのスキルです。型のモデリングに加え、境界検証、テスト、テレメトリーの指針を扱います。
主な機能
- 01判別可能なユニオンとブランド型
- 02構成による有効値のモデリング
- 03データ境界での外部入力検証
- 04スキーマと派生型の優先
- 05網羅的な分岐と安全な絞り込み
- 06実際のテストと構造化テレメトリー
活用シーン
- 01オプション項目の集合を避けたバリアント設計
- 02意味の異なる ID の混同防止
- 03信頼できない入力のドメイン型への変換
- 04TypeScript の危険な型アサーションの確認
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/typescript-best-practicesを入力して読み込まれたか確認します。
同梱ファイルagents/openai.yamlreferences/patterns.md
詳細
TypeScript のベストプラクティス
まず principle-type-system-discipline を指定して Skill ツールを呼び出してください。
| ルール | 概要 |
|---|---|
| 判別可能なユニオン | 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>（表記が異なる場合も同様）は、その解析で役目を終えます。内部では型を信頼します。principle-boundary-discipline を指定して Skill ツールを呼び出してください。 |
| スキーマから派生する型 | 新しいインターフェースを宣言する前に、Pick／Omit／Parameters／ReturnType／Awaited／typeof を検討します。 |
| オブジェクト引数 | 引数の順序が一目で分かるよう、位置引数ではなくオブジェクトを渡します。ホットパス（フレームごとのレンダリング、トークナイザー、パーサー）では適用しません。 |
| 実際のテスト | 実行できるものをモックしないでください。リークや破棄のチェックを含む、フレームワークの実際のテストプリミティブを優先し、実行中のビルドで UI を検証します。ローカルで実行できないものだけをモックします。 |
| 構造化テレメトリー | ID からデバッグできるだけのコンテキストを備えた、構造化ロガーの診断を優先します。リリースコードでは console.log を使用しません。 |
例：references/patterns.md。
コメント
Markdown 対応