Skill: Effective TypeScript

原則 2: 型推論を最大限に活用する

不要な型アノテーションを書かない（項目18-28）

TypeScript の型推論は非常に強力。冗長な型アノテーションはコードのノイズになる。

書くべき場所:

• 関数のパラメーター（推論できない）
• パブリック API の戻り値（意図を明示・エラーの局所化）
• オブジェクトリテラル（余剰プロパティチェックの活用）

書かないべき場所:

• 初期値から型が明らかなローカル変数
• 関数の戻り値（型が自明な場合）
• 式から推論可能な中間変数

// NG: 冗長な型アノテーション
const person: { name: string; age: number } = { name: "Alice", age: 30 };

// OK: 推論に任せる
const person = { name: "Alice", age: 30 };

// OK: パブリック API には型を明示
function getUser(id: string): Promise<User> { /* ... */ }

制御フロー解析の活用（項目22）

• TypeScript は if、switch、instanceof、in 演算子等で型を自動的に絞り込む
• 型ガード関数（is キーワード）でカスタムの絞り込みを定義できる
• エイリアスを作ったら一貫してそれを使う（項目23）

原則 3: 有効な状態のみ表現する型を設計する

型設計の核心（項目29-42）

CRITICAL: これは本書で最も重要な章の1つ。

タグ付きユニオン（判別可能ユニオン）を使う（項目29, 34）:

// NG: 不正な状態を許容する設計
interface State {
  isLoading: boolean;
  error: string | null;
  data: string | null;
}
// isLoading=true かつ error="fail" という矛盾した状態を許してしまう

// OK: 有効な状態のみ表現
type State =
  | { status: "loading" }
  | { status: "error"; error: string }
  | { status: "success"; data: string };

Postel の法則: 入力には寛容に、出力には厳格に（項目30）:

• 関数のパラメーターは広い型（ユニオン、readonly）を受け入れる
• 関数の戻り値は具体的な型を返す

string / number を直接使わず、より精度の高い型を選択する（項目35-36）:

// NG
function play(artist: string, title: string): void {}
play("Led Zeppelin", "Stairway to Heaven"); // OK
play("Stairway to Heaven", "Led Zeppelin"); // 引数が逆でもエラーにならない！

// OK: ブランド型や専用型を使う
type ArtistName = string & { readonly __brand: "ArtistName" };
type SongTitle = string & { readonly __brand: "SongTitle" };

オプションプロパティは限定的に使用する（項目37）:

• ? プロパティは「未設定」と「未定義」を混同させる
• 明示的に | undefined をユニオンに含めるか、必須プロパティにすることを検討

null / undefined を型エイリアスに含めない（項目32）:

// NG
type UserOrNull = User | null;
function getUser(): UserOrNull {}  // null がどこに伝播するか追跡困難

// OK: null は使用箇所で明示
function getUser(): User | null {}

原則 4: any 型を排除する

不健全性と any の制限（項目5, 43-49）

any は型安全性を破壊する。以下のルールを厳守する:

1. any よりも unknown を使う（項目46）
   • unknown は型安全な「何でも入る」型。使用前に型の絞り込みが必須
   • any はすべての型チェックを無効化する
2. any を使う場合はスコープを最小限に（項目43）

   // NG: 変数全体を any にする
   const config: any = loadConfig();
   
   // OK: 必要な箇所のみ
   const config = loadConfig();
   (config as any).experimentalFeature;
   

3. any をそのまま使わず、より具体的な形式で使う（項目44）
   • any → any[]、{[key: string]: any}、(...args: any[]) => any 等
4. 安全でない型アサーションは関数内部に隠す（項目45）

   // 内部で any を使うが、外部には型安全な API を公開
   function cacheLast<T extends Function>(fn: T): T {
     let lastArgs: any[] | null = null;
     let lastResult: any;
     return function (...args: any[]) {
       if (lastArgs && shallowEqual(lastArgs, args)) return lastResult;
       lastResult = fn(...args);
       lastArgs = args;
       return lastResult;
     } as unknown as T;
   }
   

5. 型カバレッジを監視する（項目49）
   • type-coverage ツールで any の割合を計測

原則 5: ジェネリックを適切に使う

ジェネリックと型レベルプログラミング（項目50-58）

ジェネリックを「型に対する関数」と考える（項目50）:

• 型パラメーター T は関数の引数に相当
• extends で制約を加え、安全性を確保

不必要な型パラメーターを避ける（項目51）:

// NG: T が1回しか使われていない → ジェネリック不要
function identity<T>(arg: T): T { return arg; }
// これは有用だが、以下は不要
function printLength<T extends { length: number }>(arg: T): void {
  console.log(arg.length);
}
// OK: ジェネリックなしで十分
function printLength(arg: { length: number }): void {
  console.log(arg.length);
}

条件型をオーバーロードより優先する（項目52）:

// NG: オーバーロード
function double(x: number): number;
function double(x: string): string;
function double(x: number | string) { /* ... */ }

// OK: 条件型
function double<T extends number | string>(
  x: T
): T extends string ? string : number {
  // ...
}

コード生成を複雑な型の代替手段として検討する（項目58）:

• 型が複雑すぎる場合、スキーマや DB 定義からコードを自動生成することを検討
• pgTyped、Prisma、GraphQL Code Generator 等

原則 6: TypeScript レシピ

実践パターン（項目59-64）

never 型で網羅性チェック（項目59）:

type Shape = { kind: "circle"; r: number } | { kind: "square"; s: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle": return Math.PI * shape.r ** 2;
    case "square": return shape.s ** 2;
    default:
      // 新しいバリアントを追加し忘れるとコンパイルエラー
      const _exhaustive: never = shape;
      throw new Error(`Unexpected shape: ${_exhaustive}`);
  }
}

Record 型で値の同期を保つ（項目61）:

type PageKey = "home" | "about" | "contact";
// すべてのキーに対応する値が必須
const pageUrls: Record<PageKey, string> = {
  home: "/",
  about: "/about",
  contact: "/contact",
};

ブランド型で名目的型付け（項目64）:

type Meters = number & { readonly __brand: "Meters" };
type Kilometers = number & { readonly __brand: "Kilometers" };

function metersToKm(m: Meters): Kilometers {
  return (m / 1000) as Kilometers;
}

原則 7: TypeScript 独自機能を避ける

ECMAScript の機能を優先（項目72）

以下の TypeScript 独自機能は避ける:

// NG: enum
enum Flavor { Vanilla = "vanilla", Chocolate = "chocolate" }

// OK: ユニオン型
type Flavor = "vanilla" | "chocolate" | "strawberry";

原則 8: 型宣言のベストプラクティス

型宣言と @types（項目65-71）

• TypeScript と @types は devDependencies に追加する（項目65）
• パブリック API で使われるすべての型をエクスポートする（項目67）
• API コメントに TSDoc を使う（項目68）
• モジュールオーグメンテーションで既存の型を改善できる（項目71）

原則 9: JavaScript からの移行

段階的な移行戦略（項目79-83）

1. モダン JavaScript を書く（項目79）: ES2015+ の機能を採用
2. @ts-check と JSDoc で試す（項目80）: ファイル単位で型チェック
3. allowJs で共存（項目81）: JS と TS を混在させる
4. 依存関係グラフの下から上へ移行（項目82）: import される側から変換
5. noImplicitAny を有効にして完了（項目83）: これがオンになるまで移行は未完了

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

TypeScript コードをレビューする際は以下を確認:

型設計:

• 不正な状態を表現できる型がないか（タグ付きユニオンにすべき）
• string や number を直接使っている箇所に、より精度の高い型を適用できないか
• オプションプロパティが本当に必要か（必須にできないか）
• null/undefined が型エイリアスに埋もれていないか

型安全性:

• any が使われていないか（unknown に置き換え可能か）
• as 型アサーションが適切か（型ガードに置き換え可能か）
• enum が使われていないか（ユニオン型に置き換え可能か）

型推論:

• 冗長な型アノテーションがないか（推論に任せるべき箇所）
• パブリック API に戻り値型が明示されているか
• 型の絞り込みが適切に行われているか

パターン:

• switch 文に網羅性チェック（never 型）があるか
• ジェネリックの型パラメーターが本当に必要か（1回しか使われていないものはないか）
• Record で値の同期が保たれているか

TypeScript Slop 防止:

• TypeScript Slop チェック（ET-1〜ET-6）に 2 つ以上該当しない
• 出力がドメイン固有の要素を含み、汎用テンプレートに見えない

TypeScript Slop 防止チェック（Distributional Convergence 対策）

LLM が生成する TypeScript コード・型設計ガイダンスは、同じパターンの繰り返しに収束しやすい。プロジェクト固有のドメインや制約を反映しない「どこにでも当てはまる型設計」は、型安全性の表面だけを満たし、本質的な設計改善を見逃す。

核心原則: 型は設計図である — 型定義はドメインの構造とビジネスルールを反映すべきであり、言語機能のデモではない。「別のプロジェクトの型定義にそのまま差し替えても違和感がないか？」→ 違和感がないなら TypeScript Slop である。

Examples

Example 1: 型設計の改善

「effective-typescript スキルで、この State 型をタグ付きユニオンにリファクタリングして」

→ 不正な状態を排除するタグ付きユニオンに変換し、switch 文に網羅性チェックを追加。

Example 2: コードレビュー

「effective-typescript スキルで、この TypeScript コードをレビューして」

→ 上記チェックリストに沿って型設計・型安全性・パターンの観点からレビュー。

Example 3: JavaScript からの移行

「effective-typescript スキルで、この JS ファイルを TypeScript に移行して」

→ 段階的移行戦略に沿い、型アノテーション追加・any の排除・strict 有効化を実施。

Example 4: ジェネリック関数の設計

「effective-typescript スキルで、このユーティリティ関数にジェネリックを適用して」

→ 型パラメーターの必要性を判断し、制約付きジェネリックを設計。

Example 5: React コンポーネントの Props 型設計

「React コンポーネントの Props をタグ付きユニオンで型安全に設計して」

→ Step 1: 共通 Props（children, className）を BaseProps として定義
→ Step 2: バリアント別 Props をタグ付きユニオンで設計（type: 'primary' | 'secondary' の discriminant）
→ Step 3: コンポーネント内で switch(props.type) による型の絞り込みを実装
→ Step 4: Storybook でバリアント別の表示を確認、型エラーがないことを tsc --noEmit で検証
→ 出力: 型安全なバリアント Props（無効な組み合わせがコンパイル時に検出される）

Example 6: API レスポンス型の安全な絞り込み

「外部 API レスポンスを unknown から型安全に絞り込んで」

→ Step 1: API レスポンスの型を Zod スキーマで定義（z.object + z.infer で型を導出）
→ Step 2: fetch の戻り値を unknown として受け取り、schema.safeParse() で検証
→ Step 3: success: true の場合のみ data にアクセス（型が自動的に絞り込まれる）
→ Step 4: エラーケースの型（ZodError）を API エラーレスポンスに変換
→ 出力: 実行時型安全な API クライアント（any を一切使わない）

Example 7: モノレポでの型共有パッケージ設計

「モノレポで frontend と backend の型を共有するパッケージを設計して」

→ Step 1: packages/shared-types/ を作成し、API 契約型（Request/Response）を定義
→ Step 2: tsconfig の paths と references でパッケージ間の型解決を設定
→ Step 3: frontend は shared-types の Response 型を使用、backend は Request 型を使用
→ Step 4: tsc --build で全パッケージの型整合性を一括検証
→ 出力: 型安全なモノレポ構成（API 契約の変更がフロント・バック双方でコンパイルエラーになる）

Troubleshooting

References

アンチパターン検出

このスキルの出力品質を検証するためのチェックリスト。

• 型設計が any / as を安易に使用していないか（型安全性の妥協を排除）
• Union 型の分岐が網羅的か（never チェックによる exhaustiveness guard を含む）
• Branded Type / Newtype パターンがドメイン固有の値オブジェクトに適用されているか
• エラーハンドリングが Result 型パターンまたは具体的な例外型で設計されているか
• namespace ではなく ESM の import/export で構成されているか（レガシーパターンの排除）
• 型の循環参照が interface または遅延参照パターンで解決されているか

Related Skills