TypeScript: Claude Code 활용 가이드

ユーティリティ타입で타입定義を효율화する

TypeScriptのユーティリティ타입は、既存の타입を変換して新しい타입を作る仕組みです。Claude Code는 標準ユーティリティ타입の활용は물론、프로젝트固有のカスタムユーティリティ타입の설계にも力を発揮します。

標準ユーティリティ타입の実践활용

Claude Code에「타입を変換して」と伝える만으로、적절한ユーティリティ타입を선택してくれます。

> User타입から폼用の타입を作って。
> id, createdAt, updatedAtは除外し、残りはすべてオプショナルに。

interface User {
  id: string;
  name: string;
  email: string;
  role: "admin" | "editor" | "viewer";
  bio: string;
  createdAt: Date;
  updatedAt: Date;
}

// Claude Code가 생성する타입
type UserFormData = Partial<Omit<User, "id" | "createdAt" | "updatedAt">>;

// 新規생성時は必須フィールドを指定
type CreateUserData = Required<Pick<User, "name" | "email" | "role">> &
  Partial<Pick<User, "bio">>;

Record타입とMapped Typesの활용

설정やマッピング定義にはRecord타입が便利です。

// ロールごとの権限マッピング
type Permission = "read" | "write" | "delete" | "admin";
type Role = "admin" | "editor" | "viewer";

const rolePermissions: Record<Role, Permission[]> = {
  admin: ["read", "write", "delete", "admin"],
  editor: ["read", "write"],
  viewer: ["read"],
};

// 폼フィールドの유효성 검사ルール
type ValidationRule<T> = {
  [K in keyof T]: {
    required?: boolean;
    minLength?: number;
    maxLength?: number;
    pattern?: RegExp;
    validate?: (value: T[K]) => string | true;
  };
};

const userValidation: ValidationRule<CreateUserData> = {
  name: { required: true, minLength: 2, maxLength: 50 },
  email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ },
  role: { required: true },
  bio: { maxLength: 500 },
};

カスタムユーティリティ타입の설계

Claude Code에프로젝트固有のユーティリティ타입を依頼すると、적절한설계を提案してくれます。

> API응답で使うカスタムユーティリティ타입を설계して。
> 페이지네이션、정렬、フィルタに대응して。

// 페이지네이션付き응답
type Paginated<T> = {
  items: T[];
  total: number;
  page: number;
  perPage: number;
  totalPages: number;
  hasNext: boolean;
  hasPrev: boolean;
};

// 정렬可能なフィールドを抽出
type SortableKeys<T> = {
  [K in keyof T]: T[K] extends string | number | Date ? K : never;
}[keyof T];

type SortParams<T> = {
  sortBy: SortableKeys<T>;
  sortOrder: "asc" | "desc";
};

// フィルタ타입を自動생성
type FilterParams<T> = {
  [K in keyof T]?: T[K] extends string
    ? { contains?: string; equals?: string; startsWith?: string }
    : T[K] extends number
      ? { gte?: number; lte?: number; equals?: number }
      : T[K] extends Date
        ? { after?: Date; before?: Date }
        : T[K];
};

// 組み合わせて使う
type ListQuery<T> = Partial<SortParams<T>> &
  FilterParams<T> & {
    page?: number;
    perPage?: number;
  };

// Usage example
type UserListQuery = ListQuery<User>;
// => { sortBy?: "name" | "email" | "createdAt" | ..., page?: number, ... }

Extract / Exclude で타입を絞り込む

ユニオン타입からの타입の抽出・除外もClaude Code에依頼すると빠르게구현할 수 있습니다。

type Event =
  | { type: "click"; x: number; y: number }
  | { type: "keypress"; key: string; code: number }
  | { type: "scroll"; scrollY: number }
  | { type: "resize"; width: number; height: number };

// 特定の이벤트だけ抽出
type MouseEvent = Extract<Event, { type: "click" }>;
// => { type: "click"; x: number; y: number }

// 이벤트핸들러ーの타입を自動생성
type EventHandlers = {
  [E in Event as `on${Capitalize<E["type"]>}`]: (event: E) => void;
};
// => { onClick: (event: ...) => void; onKeypress: ... }

Template Literal Typesとの組み合わせ

TypeScript 4.1以降のTemplate Literal Typesをユーティリティ타입と組み合わせるパターンです。

type CSSProperty = "margin" | "padding" | "border";
type Direction = "top" | "right" | "bottom" | "left";

type CSSDirectionalProperty = `${CSSProperty}-${Direction}`;
// => "margin-top" | "margin-right" | ... | "border-left"

// CSS스타일객체の타입
type StyleObject = Partial<Record<CSSDirectionalProperty, string | number>>;

const style: StyleObject = {
  "margin-top": 16,
  "padding-left": "1rem",
};

実践的な使い方のポイント

Claude Code에ユーティリティ타입を依頼する際のコツです。

• 変換前後の타입を明示する - 「User타입からこういう타입を作って」と伝える
• 用途を説明する - 「폼用」「API응답用」など文脈を示す
• 既存の타입定義を共有する - 元になる타입を見せると精度が上がる

정리

ユーティリティ타입を使いこなすことで、타입定義の重複を減らし유지보수성の高いコードベースを実現할 수 있습니다。Claude Code는 複雑な타입変換も一発で생성してくれるので、타입パズルに悩む시간を大幅に削減할 수 있습니다。

ジェネリクスの基礎はTypeScriptジェネリクス実践가이드を、유효성 검사との연동はZod유효성 검사実践가이드를 참고하세요.TypeScript公式のユーティリティ타입레퍼런스도 참고가 됩니다.