TypeScript リファクタリング ベストプラクティス

AI エージェントと LLM 向けに設計された包括的な TypeScript リファクタリングと現代化ガイド。8 つのカテゴリにわたる 43 のルールを含み、自動リファクタリング、コードレビュー、コード生成を導くために影響度で優先順位付けされています。

適用するタイミング

以下の場合、これらのガイドラインを参照してください:

• TypeScript コードのタイプセーフティとメンテナンス性のためのリファクタリング
• 型アーキテクチャの設計 (判別可能な Union、ブランド型、ジェネリクス)
• 型の絞り込みによる安全でない as キャストの排除
• 最新の TypeScript 4.x-5.x 機能への採用 (satisfies、using、const 型パラメータ)
• 大規模コードベースのコンパイラパフォーマンス最適化
• 型安全なエラーハンドリングパターンの実装
• TypeScript の落とし穴とアンチパターンのコードレビュー

ルールカテゴリ (優先度順)

優先度	カテゴリ	影響	プレフィックス
1	型アーキテクチャ	CRITICAL	arch-
2	型の絞り込みとガード	CRITICAL	narrow-
3	最新 TypeScript	HIGH	modern-
4	ジェネリクスパターン	HIGH	generic-
5	コンパイラパフォーマンス	MEDIUM-HIGH	compile-
6	エラー安全性	MEDIUM	error-
7	ランタイムパターン	MEDIUM	perf-
8	落とし穴とアンチパターン	LOW-MEDIUM	quirk-

クイックリファレンス

1. 型アーキテクチャ (CRITICAL)

• arch-discriminated-unions — 文字列列挙型の代わりに判別可能な Union を使用して完全パターンマッチングを実現
• arch-branded-types — ドメイン識別子にブランド型を使用して値の混同を防止
• arch-satisfies-over-annotation — 設定オブジェクトに satisfies を使用してリテラル型を保持
• arch-interfaces-over-intersections — 型の交差の代わりにインターフェースを拡張してエラーメッセージを改善
• arch-const-assertion — イミュータブルなリテラル推論に as const を使用
• arch-readonly-by-default — 関数のパラメータと戻り値をデフォルトで readonly 型に
• arch-avoid-partial-abuse — ビルダーパターンの Partial<T> の悪用を回避

2. 型の絞り込みとガード (CRITICAL)

• narrow-custom-type-guards — 型アサーションの代わりにカスタム型ガードを記述
• narrow-assertion-functions — 前提条件チェックに assertion 関数を使用
• narrow-exhaustive-switch — never を使用して switch を完全に網羅
• narrow-in-operator — インターフェース Union に in 演算子で絞り込み
• narrow-eliminate-as-casts — 適切な絞り込みチェーンで as キャストを排除
• narrow-typeof-chains — プロパティアクセス前に typeof 絞り込みを使用

3. 最新 TypeScript (HIGH)

• modern-using-keyword — リソースクリーンアップに using キーワードを使用
• modern-const-type-parameters — リテラル推論に const 型パラメータを使用
• modern-template-literal-types — 文字列パターンにテンプレートリテラル型を使用
• modern-noinfer-utility — 型パラメータ推論を制御するために NoInfer を使用
• modern-accessor-keyword — 自動生成される getter と setter に accessor を使用
• modern-verbatim-module-syntax — 明示的な import 型に verbatimModuleSyntax を有効化

4. ジェネリクスパターン (HIGH)

• generic-infer-over-annotate — 明示的なアノテーションの代わりに TypeScript に推論させる
• generic-constrain-dont-overconstrain — ジェネリクスは最小限の制約で
• generic-avoid-distributive-surprises — 分配条件型の予期しない挙動を制御
• generic-mapped-type-utilities — 繰り返し変換に対してカスタムマップ型を構築
• generic-return-type-inference — ジェネリック関数の戻り値型推論を保持

5. コンパイラパフォーマンス (MEDIUM-HIGH)

• compile-explicit-return-types — エクスポートされた関数に明示的な戻り値型を追加
• compile-avoid-deep-recursion — 深くネストされた型定義を回避
• compile-project-references — モノレポビルドにプロジェクト参照を使用
• compile-base-types-over-unions — 大規模 Union 型の代わりにベース型を使用

6. エラー安全性 (MEDIUM)

• error-result-type — スローされた例外の代わりに Result 型を使用
• error-exhaustive-error-handling — 型付きエラーバリアントに完全なチェックを使用
• error-typed-catch — catch 句の変数を unknown として型付け
• error-never-for-unreachable — 到達不可能なコードパスを示すために never を使用
• error-discriminated-error-unions — ドメインエラーを判別可能な Union としてモデル化

7. ランタイムパターン (MEDIUM)

• perf-union-literals-over-enums — 列挙型の代わりに Union リテラルを使用
• perf-avoid-delete-operator — オブジェクト上の delete 演算子を回避
• perf-object-freeze-const — 真のイミュータビリティに Object.freeze と as const を使用
• perf-object-keys-narrowing — Object.keys の型拡張を回避
• perf-map-set-over-object — 動的コレクションにはプレーンオブジェクトの代わりに Map と Set を使用

8. 落とし穴とアンチパターン (LOW-MEDIUM)

• quirk-excess-property-checks — オブジェクトリテラルの過剰プロパティチェックを理解
• quirk-empty-object-type — {} 型を避ける — これは非 null-ish を意味する
• quirk-type-widening-let — let 宣言での型の拡張を防止
• quirk-variance-annotations — ジェネリックインターフェースに分散アノテーションを使用
• quirk-structural-typing-escapes — 構造的型付けのエスケープハッチから保護

使い方

各リファレンスファイルを読んで詳細な説明とコード例を確認してください:

• セクション定義 — カテゴリ構造と影響レベル
• ルールテンプレート — 新しいルール追加用テンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリ定義と順序付け
assets/templates/_template.md	新しいルール用テンプレート
metadata.json	バージョンとリファレンス情報