TypeScript ベストプラクティス

高品質の TypeScript コードの執筆に AI エージェントをガイドします。このスキルはコーディング標準、アーキテクチャパターン、分析やスキャフォールディングのためのツールを提供します。

このスキルをいつ使うか

以下の場合にこのスキルを使用します:

• 新しい TypeScript コードを生成する
• TypeScript ファイルを品質問題についてレビューする
• 新しいモジュール、サービス、またはコンポーネントを作成する
• JavaScript を TypeScript にリファクタリングする
• TypeScript パターンまたは型についての質問に答える
• API またはインターフェースを設計する

以下の場合は使用しないでください:

• 純粋な JavaScript を扱う場合 (TypeScript ではない)
• ランタイムエラーをデバッグする場合 (デバッグツールを使用)
• フレームワーク固有のパターン (React、Vue など - フレームワークスキルを使用)

コア原則

1. 型安全性を第一に

コンパイル時のエラー検出を最大化します:

// unknown を any よりも優先
function processInput(data: unknown): string {
  if (typeof data === "string") return data;
  if (typeof data === "number") return String(data);
  throw new Error("Unsupported type");
}

// 公開 API に対しては明示的な戻り値型
export function calculateTotal(items: ReadonlyArray<Item>): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}

// リテラル型の const アサーション
const CONFIG = {
  mode: "production",
  version: 1,
} as const;

2. デフォルトではイミュータビリティ

意図しないミューテーションを防ぎます:

// オブジェクトプロパティに readonly を使用
interface User {
  readonly id: string;
  readonly email: string;
  name: string; // 意図的な場合のみミュータブル
}

// コレクションに ReadonlyArray を使用
function processItems(items: ReadonlyArray<Item>): ReadonlyArray<Result> {
  return items.map(transform);
}

// ミューテーションより spread を優先
function updateUser(user: User, name: string): User {
  return { ...user, name };
}

3. 型を使用したエラーハンドリング

型システムを用いてエラーハンドリングを行います:

// 回復可能なエラー向け Result 型
type Result<T, E = Error> =
  | { success: true; value: T }
  | { success: false; error: E };

// 型付きエラークラス
class ValidationError extends Error {
  constructor(
    message: string,
    readonly field: string,
    readonly code: string
  ) {
    super(message);
    this.name = "ValidationError";
  }
}

// Result 戻り値型を持つ関数
function parseConfig(input: string): Result<Config, ValidationError> {
  try {
    const data = JSON.parse(input);
    if (!isValidConfig(data)) {
      return {
        success: false,
        error: new ValidationError("Invalid config", "root", "INVALID_FORMAT"),
      };
    }
    return { success: true, value: data };
  } catch {
    return {
      success: false,
      error: new ValidationError("Parse failed", "root", "PARSE_ERROR"),
    };
  }
}

4. コード構成

保守性のためのコード構成:

// 1 つのファイルに 1 つの概念
// user.ts - User 型と関連ユーティリティ
export interface User {
  readonly id: string;
  readonly email: string;
  readonly createdAt: Date;
}

export function createUser(email: string): User {
  return {
    id: crypto.randomUUID(),
    email,
    createdAt: new Date(),
  };
}

// 明示的なエクスポート (バレルファイルのワイルドカード不可)
// index.ts
export { User, createUser } from "./user.ts";
export { validateEmail } from "./validation.ts";

クイックリファレンス

カテゴリ	優先	回避
不明な型	unknown	any
コレクション	ReadonlyArray<T>	入力に対する T[]
オブジェクト	Readonly<T>	デフォルトではミュータブル
null チェック	オプショナルチェーン ?.	!= null
型の絞り込み	型ガード	as アサーション
戻り値型	エクスポート時は明示的	エクスポート時の推論不可
列挙型	文字列リテラル共用体	数値列挙型
インポート	名前付きインポート	デフォルトインポート
エラー	Result 型	フロー制御のための throw
ループ	for...of、.map()	配列での for...in

コード生成ガイドライン

TypeScript コードを生成する際は、以下のパターンに従います:

モジュール構造

/**
 * モジュール説明
 * @module module-name
 */

// === Types ===
export interface ModuleOptions {
  readonly setting: string;
}

export interface ModuleResult {
  readonly data: unknown;
}

// === Constants ===
const DEFAULT_OPTIONS: ModuleOptions = {
  setting: "default",
};

// === Implementation ===
export function processData(
  input: unknown,
  options: Partial<ModuleOptions> = {}
): ModuleResult {
  const opts = { ...DEFAULT_OPTIONS, ...options };
  // Implementation
  return { data: input };
}

関数設計

// 純粋関数を優先
function transform(input: Input): Output {
  // 副作用なし、同じ入力 = 同じ出力
  return { ...input, processed: true };
}

// 明示的なパラメータ型
function fetchUser(id: string, options?: FetchOptions): Promise<User> {
  // Implementation
}

// 複雑なシグネチャに関数オーバーロードを使用
function parse(input: string): ParsedData;
function parse(input: Buffer): ParsedData;
function parse(input: string | Buffer): ParsedData {
  // Implementation
}

インターフェース設計

// オブジェクト形状ではインターフェースを優先
interface UserData {
  readonly id: string;
  readonly email: string;
}

// 共用体と交差に type を使用
type UserRole = "admin" | "user" | "guest";
type AdminUser = UserData & { readonly role: "admin" };

// JSDoc でドキュメント化
/**
 * API クライアントの設定
 * @property baseUrl - API リクエストの基本 URL
 * @property timeout - リクエストタイムアウト (ミリ秒単位)
 */
interface ApiConfig {
  readonly baseUrl: string;
  readonly timeout?: number;
}

よくあるアンチパターン

コード生成時にこれらのパターンを回避します:

アンチパターン	問題	解決策
any 型	型チェックを無効化	unknown を使用して絞り込む
as アサーション	ランタイムエラー	型ガードを使用
null 非認可 !	ヌルポインタエラー	オプショナルチェーン ?.
ミュータブルパラメータ	予期しないミューテーション	Readonly<T>
マジックストリング	タイプミス、オートコンプリート不可	文字列リテラル型
神クラス	テスト/保守が困難	単一責任
循環依存	ビルド/ランタイムの問題	依存性逆転
インデックスシグネチャ	型情報喪失	明示的なプロパティ

詳細な例については references/anti-patterns/common-mistakes.md を参照します。

スクリプトリファレンス

analyze.ts

TypeScript コードの品質問題を分析します:

deno run --allow-read scripts/analyze.ts <path> [options]

オプション:
  --strict        すべてのチェックを有効化
  --json          プログラム用途向け JSON 出力
  --fix-hints     提案される修正を表示

例:
  # ファイルを分析
  deno run --allow-read scripts/analyze.ts ./src/utils.ts

  # ストリクトモード付きでディレクトリを分析
  deno run --allow-read scripts/analyze.ts ./src --strict

  # CI 向け JSON 出力
  deno run --allow-read scripts/analyze.ts ./src --json

generate-types.ts

JSON データから TypeScript 型を生成します:

deno run --allow-read --allow-write scripts/generate-types.ts <input> [options]

オプション:
  --name <name>   ルート型名 (デフォルト: 推論)
  --output <path> 出力ファイルパス
  --readonly      readonly 型を生成
  --interface     type の代わりに interface を使用

例:
  # JSON ファイルから生成
  deno run --allow-read scripts/generate-types.ts ./data.json --name Config

  # readonly インターフェースを生成
  deno run --allow-read --allow-write scripts/generate-types.ts ./api-response.json \
    --interface --readonly --output ./types/api.ts

scaffold-module.ts

適切に構造化された TypeScript モジュールを作成します:

deno run --allow-read --allow-write scripts/scaffold-module.ts [options]

オプション:
  --name <name>   モジュール名 (必須)
  --path <path>   ターゲットディレクトリ (デフォルト: ./src)
  --type <type>   型: service、util、component
  --with-tests    テストファイルを含める

例:
  # ユーティリティモジュールを作成
  deno run --allow-read --allow-write scripts/scaffold-module.ts \
    --name "string-utils" --type util

  # テスト付きでサービスを作成
  deno run --allow-read --allow-write scripts/scaffold-module.ts \
    --name "user-service" --type service --with-tests

その他のリソース

型システムの詳細解説

• references/type-system/advanced-types.md - ジェネリクス、条件付き型、マップ型
• references/type-system/type-guards.md - 型の絞り込み手法
• references/type-system/utility-types.md - 組み込みユーティリティ型

パターンガイド

• references/patterns/error-handling.md - Result 型、型付きエラー
• references/patterns/async-patterns.md - Async/await ベストプラクティス
• references/patterns/functional-patterns.md - イミュータビリティ、合成
• references/patterns/module-patterns.md - エクスポート、依存性注入

アーキテクチャ

• references/architecture/project-structure.md - ディレクトリ構成
• references/architecture/api-design.md - インターフェース設計、バージョニング

テンプレート

• assets/templates/module-template.ts.md - モジュールスターターテンプレート
• assets/templates/service-template.ts.md - サービスクラステンプレート
• assets/tsconfig-presets/strict.json - 最大ストリクトネス設定
• assets/tsconfig-presets/recommended.json - バランスの取れたデフォルト