typescript-refactor

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

AI エージェントと LLM 向けに設計された、TypeScript および TSX の包括的なリファクタリングとモダナイズのガイドです。影響度に基づいて優先順位付けされた 9 カテゴリ、47 のルールを収録し、自動リファクタリング、コードレビュー、コード生成を支援します。TypeScript 6.0 と React 19 に対応しています。

適用する場面

次のような場合に、このガイドラインを参照してください。

• 型安全性と保守性を高めるために、TypeScript または React／TSX コードをリファクタリングする
• 型アーキテクチャ（判別可能なユニオン、ブランド型、ジェネリクス）を設計する
• 危険な as キャストをなくすために型を絞り込む
• .tsx ファイルで React コンポーネントやフック（props、refs、events、state）に型を付ける
• 最新の TypeScript 5.x～6.0 の機能（satisfies、using、const 型パラメーター、推論される型述語、消去可能な構文、with インポート属性）を導入する
• 大規模なコードベースでコンパイラーのパフォーマンスを最適化する（isolatedDeclarations、プロジェクト参照）
• 型安全なエラー処理パターンを実装する
• TypeScript 固有の挙動や落とし穴についてコードをレビューする

優先度別のルールカテゴリ

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

クイックリファレンス

1. 型アーキテクチャ（CRITICAL）

• arch-discriminated-unions — 網羅的なパターンマッチングには、文字列列挙型より判別可能なユニオンを使用する
• 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 — as を実行時チェック付きのガードに置き換える。TS 5.5 以降では述語が推論される
• narrow-assertion-functions — 前提条件のチェックにはアサーション関数を使用する
• narrow-exhaustive-switch — never を使って switch の網羅性を保証する
• narrow-in-operator — インターフェイスのユニオン型を in 演算子で絞り込む
• narrow-eliminate-as-casts — 適切な絞り込みの連鎖で as キャストをなくす

3. モダンな TypeScript（HIGH）

• modern-using-keyword — リソースのクリーンアップには using キーワードを使用します
• modern-const-type-parameters — リテラル型の推論には const 型パラメーターを使用します
• modern-template-literal-types — 文字列パターンにはテンプレートリテラル型を使用します
• modern-noinfer-utility — 型パラメーターの推論を制御するには NoInfer を使用します
• modern-verbatim-module-syntax — インポート型を明示するには verbatimModuleSyntax を有効にします
• modern-erasable-syntax — 型のストリッピングには、enum や namespace より消去可能な構文を優先します
• modern-import-attributes — 非推奨の assert の代わりに with インポート属性を使用します

4. React と TSX（HIGH）

• tsx-avoid-react-fc — React.FC の代わりに props を直接型付けします
• tsx-ref-as-prop — forwardRef の代わりに ref を prop として渡します（React 19）
• tsx-extend-native-props — ネイティブ要素の props を再宣言する代わりに、ComponentPropsWithRef で拡張します
• tsx-discriminated-props — 相互に排他的な props は判別可能なユニオンとしてモデル化します
• tsx-event-handler-types — React の合成イベント型でイベントハンドラーを型付けします
• tsx-hook-typing — nullable な状態や変更可能な状態に合わせて useState／useRef を型付けします

5. ジェネリックのパターン（HIGH）

• generic-constrain-dont-overconstrain — ジェネリックの制約は必要最小限にします
• generic-avoid-distributive-surprises — 分配条件型を制御します
• generic-mapped-type-utilities — 繰り返し行う変換にはカスタムのマップ型を構築します
• generic-return-type-inference — ジェネリック関数の戻り値型の推論を維持します

6. コンパイラーのパフォーマンス（MEDIUM-HIGH）

• compile-explicit-return-types — エクスポートする関数には明示的な戻り値型を追加します
• compile-avoid-deep-recursion — 深く再帰する型定義を避けます
• compile-project-references — モノレポのビルドにはプロジェクト参照を使用します
• compile-base-types-over-unions — 大規模なユニオン型の代わりに基本型を使用します
• compile-isolated-declarations — 宣言ファイルの並列出力には isolatedDeclarations を有効にします

7. エラー安全性（MEDIUM）

• error-result-type — スローされる例外の代わりに Result 型を使用します
• error-exhaustive-error-handling — 型付けされたエラーのバリアントには網羅性チェックを使用します
• error-typed-catch — catch 節の変数を unknown として型付けします
• error-discriminated-error-unions — ドメインエラーを判別可能なユニオンとしてモデル化します

8. ランタイムパターン（中）

• perf-union-literals-over-enums — 列挙型ではなくユニオンリテラルを使用します — 列挙型は消去できません
• perf-avoid-delete-operator — オブジェクトに対する delete 演算子の使用を避けます
• perf-object-freeze-const — 真の不変性を実現するには、as const とともに Object.freeze を使用します
• perf-object-keys-narrowing — Object.keys による型の拡大を避けます
• perf-map-set-over-object — 動的なコレクションにはプレーンオブジェクトではなく Map と Set を使用します

9. 特有の挙動と落とし穴（低〜中）

• quirk-excess-property-checks — オブジェクトリテラルに対する余剰プロパティチェックについて理解します
• quirk-empty-object-type — {} 型の使用を避けます — この型は nullish ではない値を意味します
• quirk-structural-typing-escapes — 構造的型付けの抜け道に注意します
• quirk-variance-annotations — ジェネリックの意図を文書化するために分散注釈を使用します（速度向上のためではありません）

使用方法

詳しい説明とコード例については、個々のリファレンスファイルをお読みください。

• セクション定義 — カテゴリーの構成と影響レベル
• ルールのテンプレート — 新しいルールを追加するためのテンプレート

リファレンスファイル

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