typescript-expert

TypeScript エキスパート

呼び出されたとき

1. プロジェクトのセットアップを包括的に分析します。

   パフォーマンスを考慮し、組み込みのファイル読み取り機能や検索機能を優先してください。シェルコマンドは代替手段として使用します。

   # Core versions and configuration
   bunx tsc --version
   node -v
   # Detect tooling ecosystem (prefer parsing package.json)
   node -e "const p=require('./package.json');console.log(Object.keys({...p.devDependencies,...p.dependencies}||{}).join('\n'))" 2>/dev/null | grep -E 'biome|eslint|prettier|vitest|turborepo|nx' || echo "No tooling detected"
   # Check for monorepo (fixed precedence)
   (test -f pnpm-workspace.yaml || test -f lerna.json || test -f nx.json || test -f turbo.json) && echo "Monorepo detected"
   

   検出後は、次の点に応じてアプローチを調整します。

   • インポート形式（絶対パスか相対パスか）を合わせる
   • 既存の baseUrl/paths 設定を尊重する
   • 生のツールより既存のプロジェクトスクリプトを優先する
   • モノレポでは、広範な tsconfig の変更を行う前にプロジェクト参照を検討する

2. 問題の具体的なカテゴリと複雑さのレベルを特定します。

3. 以下の専門知識から適切な解決策を選択します。

4. 十分に検証します。

   # Fast fail approach (avoid long-lived processes)
   bun run typecheck || bunx tsc --noEmit
   bun run test || bunx vitest run --reporter=basic --no-watch
   # Only if needed and build affects outputs/config
   bun run build
   

   安全上の注意： 検証時に watch/serve プロセスを起動しないでください。単発の診断のみを使用します。

高度な型システムの専門知識

型レベルのプログラミングパターン

ドメインモデリングのためのブランド型 — 名目的型（type UserId = Brand<string, 'UserId'>）を使うと、同じ基底型を持つドメインプリミティブが誤って混同されるのを防げます。重要なドメインプリミティブ、API 境界、通貨や単位に使用します。ルール：references/rules/arch-branded-types.md、チートシート：references/typescript-cheatsheet.md（§ Branded Types）。参考資料：https://egghead.io/blog/using-branded-types-in-typescript

高度な条件型 — 再帰的な型操作（例：DeepReadonly<T>）や、テンプレートリテラルを使ったイベントソース API です。ライブラリ API、型安全なイベントシステム、コンパイル時検証に使用します。型のインスタンス化深度エラーに注意してください（再帰は10レベルまでに制限します）。references/typescript-cheatsheet.md（§ Conditional Types、§ Mapped Types、§ Template Literal Types）と references/rules/compile-avoid-deep-recursion.md を参照してください。

型推論のテクニック — リテラル型を保持したまま制約を検証するには satisfies（TS 5.0+）を使用し、リテラル配列やオブジェクトで最大限に推論させるには as const アサーションを使用します。ルール：references/rules/arch-satisfies-over-annotation.md、references/rules/arch-const-assertion.md。

リファクタリングのルール

型安全性を高めるための TypeScript のリファクタリングやモダナイズ（as キャストをナローイングに置き換える、列挙型より判別可能なユニオンを使う、型付きエラー処理、TS 4.x-5.x の機能、コンパイル速度など）では、references/rules/ にある43のルールを活用します。該当するルールのみを、1つずつファイルを開いてください。references/rules/_sections.md ではカテゴリが、_template.md では新しいルールの形式が定義されています。

優先度	カテゴリ	プレフィックス
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 — 網羅的なパターンマッチングには、文字列列挙型より判別可能なユニオンを使用する
• 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 — 事前条件のチェックにアサーション関数を使用します
• narrow-exhaustive-switch — never を使用して、switch の網羅性を徹底します
• narrow-in-operator — インターフェースのユニオン型を 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 — 自動生成されるゲッターとセッターには accessor を使用します
• modern-verbatim-module-syntax — 明示的なインポート型を使用するには 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 — 大規模なユニオン型ではなく、基底型を使用します

6. エラーの安全性（MEDIUM）

• error-result-type — スローされる例外ではなく、Result 型を使用します
• error-exhaustive-error-handling — 型付きエラーのバリアントには網羅的なチェックを使用します
• error-typed-catch — catch 節の変数を unknown として型付けします
• error-never-for-unreachable — 到達不能なコードパスを示すには never を使用します
• error-discriminated-error-unions — ドメインエラーを判別可能なユニオン型としてモデル化します

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

• perf-union-literals-over-enums — enum の代わりにユニオンリテラルを使用します
• 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 を使用します

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

• quirk-excess-property-checks — オブジェクトリテラルに対する余剰プロパティチェックを理解します
• quirk-empty-object-type — {} 型を避けます。これは nullish でない値を意味します
• quirk-type-widening-let — let 宣言による型の拡大を防ぎます
• quirk-variance-annotations — ジェネリックインターフェースには分散注釈を使用します
• quirk-structural-typing-escapes — 構造的型付けの抜け道に備えます

動作を維持した再構成は refactor-code スキルが担当します。型アーキテクチャの作業では、このスキルがこれらのルールを読み込みます。

パフォーマンス最適化戦略

型チェックのパフォーマンス

bunx tsc --extendedDiagnostics --incremental false | grep -E "Check time|Files:|Lines:|Nodes:"

「Type instantiation is excessively deep」に対する一般的な修正方法：型の交差をインターフェースに置き換える（references/rules/arch-interfaces-over-intersections.md）、大きなユニオン型（100 メンバー超）を分割する（references/rules/compile-base-types-over-unions.md）、循環するジェネリック制約を避ける、型エイリアスを使用して再帰を断ち切る。エクスポートする関数には明示的な戻り値の型を追加します（references/rules/compile-explicit-return-types.md）。

ビルドパフォーマンスのパターン

• ライブラリの型チェックに限り skipLibCheck: true を有効にします（大規模プロジェクトではパフォーマンスが大幅に向上することがよくありますが、アプリの型付けに関する問題を見逃さないようにしてください）
• .tsbuildinfo キャッシュとともに incremental: true を使用します
• include／exclude を正確に設定します
• モノレポの場合：composite: true とプロジェクト参照を使用します（references/rules/compile-project-references.md）

実際の問題の解決

複雑なエラーパターン

「X の推論された型に名前を付けられません」

• 原因：型のエクスポート漏れ、または循環依存
• 修正の優先順位：必要な型を明示的にエクスポートする、ReturnType<typeof function> ヘルパーを使用する、型のみのインポートで循環依存を解消する
• リソース：https://github.com/microsoft/TypeScript/issues/47663

型宣言の不足 — 型付けされていないパッケージに対して、アンビエント .d.ts モジュール宣言を追加します。references/typescript-cheatsheet.md（§ Module Declarations）を参照してください。詳しくは Declaration Files Guide を参照してください。

「型の比較でスタック深度が過剰です」

• 原因：循環型、または深く再帰する型
• 修正の優先順位：条件型で再帰の深さを制限する、型の交差の代わりに interface の継承を使用する、ジェネリック制約を簡素化する

// Bad: Infinite recursion
type InfiniteArray<T> = T | InfiniteArray<T>[];

// Good: Limited recursion
type NestedArray<T, D extends number = 5> =
  D extends 0 ? T : T | NestedArray<T, [-1, 0, 1, 2, 3, 4][D]>[];

モジュール解決の謎 — ファイルが存在するのに「Cannot find module」と表示される場合：

1. moduleResolution がバンドラーに合っているか確認します
2. baseUrl と paths の整合性を確認します
3. モノレポの場合：ワークスペースプロトコル（workspace:*）が設定されていることを確認します
4. キャッシュのクリアを試します：rm -rf node_modules/.cache .tsbuildinfo

実行時のパスマッピング — TypeScript のパスはコンパイル時にのみ機能し、実行時には機能しません。

• ts-node：ts-node -r tsconfig-paths/register を使用します
• Node ESM：ローダーの代替手段を使用するか、実行時に TS パスを使用しないようにします
• 本番環境：パスを解決した状態で事前コンパイルします

移行の専門知識

JavaScript から TypeScript への移行 — 段階的な戦略です。既存の tsconfig で allowJs／checkJs を有効にし、ファイル名を少しずつ変更し（.js → .ts）、ファイルごとに型を追加して、strict モードの機能を一つずつ有効にします。コマンドの全手順と任意の自動化ヘルパー（ts-migrate、typesync）については、references/full-guide.md（§ Migration Playbook）を参照してください。

ツール移行の判断

移行元	移行先	移行するタイミング	移行にかかる労力
ESLint + Prettier	Biome	大幅な高速化が必要で、ルールが少なくても問題ない場合	低（1 日）
lint に TSC を使用	型チェックのみ	ファイルが 100 個以上あり、より速いフィードバックが必要な場合	中（2〜3 日）
Lerna	Nx/Turborepo	キャッシュや並列ビルドが必要な場合	高（1 週間）
CJS	ESM	Node 18 以降で、モダンなツールを使用する場合	高（状況による）

モノレポの管理

Nx と Turborepo の判断基準

• Turborepo を選ぶ場合：構成がシンプルで、速度が必要で、パッケージ数が 20 未満
• Nx を選ぶ場合：依存関係が複雑で、可視化が必要で、プラグインが必須
• パフォーマンス：大規模なモノレポ（パッケージ数が 50 超）では、Nx の方が優れたパフォーマンスを発揮することがよくあります

TypeScript モノレポの設定 — ルート tsconfig の references 配列と、パッケージごとの composite／declaration／declarationMap を設定します。設定の全体については、references/full-guide.md（§ Monorepo TypeScript Configuration）を参照してください。

モダンなツールに関する専門知識

Biome と ESLint の比較

Biome を使う場合： 速度が重要で、lint とフォーマットに単一のツールを使いたい場合、TypeScript を第一に考えたプロジェクトの場合、typescript-eslint の 100 以上のルールに対して、TS ルールが 64 個でも問題ない場合。

ESLint を使い続ける場合： 特定のルールやプラグインが必要な場合、複雑なカスタムルールがある場合、Vue／Angular を使用している場合（Biome のサポートは限定的です）、型情報を活用した lint が必要な場合（Biome はまだ対応していません）。

型テストの戦略

Vitest による型テスト（推奨） — expectTypeOf を使った .test-d.ts ファイルを作成し、コンパイル時にプロパティや戻り値の型を検証します。全体的な例については、references/full-guide.md（§ Vitest Type Testing）を参照してください。

型をテストするタイミング： ライブラリを公開する場合、複雑なジェネリック関数を使う場合、型レベルのユーティリティを使う場合、API コントラクトを扱う場合。

デバッグの熟達

CLI デバッグツール — モジュール解決をトレースし（tsc --traceResolution）、型チェックのパフォーマンスをプロファイルし（tsc --generateTrace）、tsx／ts-node --inspect-brk でファイルを直接デバッグします。コマンド一式については、references/full-guide.md（§ CLI Debugging Tools）を参照してください。

カスタムエラークラス — Error を継承し、this.name を設定して、スタックを保持するために Error.captureStackTrace を呼び出します。パターンの全体については、references/full-guide.md（§ Custom Error Classes）を参照してください。

現在のベストプラクティス

デフォルトで strict にする

strict: true に加えて、noUncheckedIndexedAccess、noImplicitOverride、exactOptionalPropertyTypes、noPropertyAccessFromIndexSignature を使用します。本番環境ですぐに使える strict 設定の全体については、references/tsconfig-strict.json を参照してください。

ESM を第一にするアプローチ

• package.json で "type": "module" を設定します
• 必要に応じて、TypeScript の ESM ファイルには .mts を使います
• モダンなツール向けに "moduleResolution": "bundler" を設定します
• CJS には動的インポートを使います：const pkg = await import('cjs-package')
  • 注：await import() を使うには、async 関数または ESM のトップレベル await が必要です
  • ESM で CJS パッケージを使う場合：パッケージのエクスポート構造やコンパイラー設定によっては、(await import('pkg')).default が必要になることがあります

AI を活用した開発

• AI コーディングアシスタントは、TypeScript のジェネリクスや定型的な型定義を得意とします
• AI が生成した型は型テストで検証します
• 複雑な型は、AI が文脈を把握できるようにドキュメント化します

コードレビューのチェックリスト

型安全性

• 暗黙の any 型がない（unknown または適切な型を使う）
• 厳密な null チェックが有効になっており、適切に処理されている
• 型アサーション（as）には根拠があり、最小限にとどめられている
• ジェネリック制約が適切に定義されている
• エラー処理に判別可能なユニオン型が使われている
• 公開 API の戻り値の型が明示的に宣言されている

TypeScript のベストプラクティス

• オブジェクトの形状には type より interface を優先します（エラーメッセージが改善されます）
• リテラル型には const アサーションを使用します
• 型ガードと型述語を活用します
• よりシンプルな解決策がある場合は、複雑な型操作を避けます
• テンプレートリテラル型を適切に使用します
• ドメインプリミティブにはブランド型を使用します

パフォーマンスに関する考慮事項

• 型の複雑さによってコンパイルが遅くならないようにします
• 型のインスタンス化の深さが過剰にならないようにします
• ホットパスでは複雑なマップ型を避けます
• tsconfig で skipLibCheck: true を使用します
• モノレポではプロジェクト参照を設定します

モジュールシステム

• 一貫したインポート／エクスポートパターンを使用し、循環依存を避けます
• バレルエクスポートを適切に使用します（過剰なバンドルを避けます）
• ESM／CJS の互換性を適切に処理し、コード分割には動的インポートを使用します

エラー処理のパターン

• エラーには Result 型または判別可能なユニオンを使用します（references/rules/error-*.md）
• 適切な継承を備えたカスタムエラークラスと、型安全なエラーバウンダリーを使用します
• never 型を使用して switch ケースを網羅します

コードの整理

• 型を実装と同じ場所に配置します
• 共有型は専用のモジュールにまとめます
• 可能な限りグローバルな型拡張を避けます
• 宣言ファイル（.d.ts）を適切に使用します

クイック判断ツリー

"Which tool should I use?"
Type checking only? → tsc
Type checking + linting speed critical? → Biome
Type checking + comprehensive linting? → ESLint + typescript-eslint
Type testing? → Vitest expectTypeOf
Build tool? → Project size <10 packages? Turborepo. Else? Nx

"How do I fix this performance issue?"
Slow type checking? → skipLibCheck, incremental, project references
Slow builds? → Check bundler config, enable caching
Slow tests? → Vitest with threads, avoid type checking in tests
Slow language server? → Exclude node_modules, limit files in tsconfig

専門家向けリソース

• パフォーマンス：TypeScript Wiki Performance、Type instantiation tracking
• 高度なパターン：Type Challenges、Type-Level TypeScript Course
• ツール：Biome（リンター／フォーマッター）、TypeStat（型の自動修正）、ts-migrate（移行ツールキット）
• テスト：Vitest Type Testing、tsd（スタンドアロンの型テスト）

問題を解決済みとする前に、変更によって既存の機能が損なわれないことを必ず検証してください。

Typescript ベストプラクティスの手順

このワークフローを実行する際は、typescript-best-practices procedure を読みます。 このエントリーポイントで許可された範囲とモードを、すべての手順に適用してください。 他のスキルは、このディストリビューションの有効なカタログを通じて解決し、 リソースはインストール済みのスキルディレクトリを基準に解決してください。