Zod: Claude Code 활용 가이드

Zodで타입安全な유효성 검사を구축する

Zodは「스키마定義 = 타입定義」を実現するTypeScriptファーストの유효성 검사라이브러리です。Claude Code는 스키마の설계から複雑な유효성 검사ロジックの구현まで、的確にサポートしてくれます。

기본적인스키마定義

Claude Code에데이터構造を伝える만으로、적절한Zod스키마が생성されます。

> 사용자등록폼のZod스키마를 생성해줘。
> メール形式チェック、비밀번호強度검증、확인비밀번호の一致チェックを含めて。

import { z } from "zod";

const registerSchema = z
  .object({
    name: z
      .string()
      .min(2, "名前は2文字以上で入力してください")
      .max(50, "名前は50文字以内で入力してください"),
    email: z
      .string()
      .email("有効なメールアドレスを入力してください"),
    password: z
      .string()
      .min(8, "パスワードは8文字以上で入力してください")
      .regex(/[A-Z]/, "大文字を1文字以上含めてください")
      .regex(/[a-z]/, "小文字を1文字以上含めてください")
      .regex(/[0-9]/, "数字を1文字以上含めてください"),
    confirmPassword: z.string(),
    agreeToTerms: z.literal(true, {
      errorMap: () => ({ message: "利用規約への同意が必要です" }),
    }),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: "パスワードが一致しません",
    path: ["confirmPassword"],
  });

// 스키마から타입を推論
type RegisterFormData = z.infer<typeof registerSchema>;

ネストされた객체と배열の검증

複雑な데이터構造の스키마も、Claude Code에構造を説明すれば正確に생성할 수 있습니다。

const orderSchema = z.object({
  customer: z.object({
    name: z.string().min(1),
    email: z.string().email(),
    phone: z.string().regex(/^0\d{9,10}$/, "有効な電話番号を入力してください"),
  }),
  items: z
    .array(
      z.object({
        productId: z.string().uuid(),
        quantity: z.number().int().positive().max(99),
        options: z.record(z.string()).optional(),
      })
    )
    .min(1, "商品を1つ以上選択してください"),
  shippingAddress: z.object({
    postalCode: z.string().regex(/^\d{3}-?\d{4}$/, "郵便番号の形式が正しくありません"),
    prefecture: z.string().min(1),
    city: z.string().min(1),
    street: z.string().min(1),
    building: z.string().optional(),
  }),
  paymentMethod: z.enum(["credit_card", "bank_transfer", "convenience_store"]),
  notes: z.string().max(500).optional(),
});

type OrderData = z.infer<typeof orderSchema>;

Zodとtanstack/react-hook-formの연동

폼라이브러리とZodを組み合わせるパターンです。

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";

const loginSchema = z.object({
  email: z.string().email("有効なメールアドレスを入力してください"),
  password: z.string().min(1, "パスワードを入力してください"),
  rememberMe: z.boolean().default(false),
});

type LoginFormData = z.infer<typeof loginSchema>;

function LoginForm() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<LoginFormData>({
    resolver: zodResolver(loginSchema),
  });

  const onSubmit = (data: LoginFormData) => {
    // data は타입安全
    console.log(data.email); // string
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("email")} />
      {errors.email && <span>{errors.email.message}</span>}
      <input type="password" {...register("password")} />
      {errors.password && <span>{errors.password.message}</span>}
      <button type="submit">ログイン</button>
    </form>
  );
}

カスタム유효성 검사とtransform

Zodのtransformとrefineを활용して、데이터変換と유효성 검사を同時に行えます。

const environmentSchema = z.object({
  PORT: z.string().transform(Number).pipe(z.number().int().min(1).max(65535)),
  DATABASE_URL: z.string().url(),
  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
  CORS_ORIGINS: z
    .string()
    .transform((s) => s.split(",").map((o) => o.trim()))
    .pipe(z.array(z.string().url())),
});

// 환경 변수のパースと검증を一度に実行
const env = environmentSchema.parse(process.env);
// env.PORT は number 타입、env.CORS_ORIGINS は string[] 타입

API요청・응답の스키마설계

APIの엔드포인트ごとに스키마を定義し、요청と응답の両方を검증するパターンです。

// 共通の페이지네이션매개변수
const paginationSchema = z.object({
  page: z.coerce.number().int().positive().default(1),
  perPage: z.coerce.number().int().min(1).max(100).default(20),
});

// 검색매개변수
const userSearchSchema = paginationSchema.extend({
  q: z.string().optional(),
  role: z.enum(["admin", "editor", "viewer"]).optional(),
  sortBy: z.enum(["name", "createdAt", "email"]).default("createdAt"),
  sortOrder: z.enum(["asc", "desc"]).default("desc"),
});

// API 핸들러ーで使用
async function handleUserSearch(req: Request) {
  const url = new URL(req.url);
  const params = Object.fromEntries(url.searchParams);
  const query = userSearchSchema.parse(params);
  // query は完全に타입安全
}

정리

ZodとClaude Codeの組み合わせにより、유효성 검사ロジックの구현速度が大幅に向上します。스키마から타입を推論する仕組み에 의해、타입定義と유효성 검사ルールの二重관리も解消할 수 있습니다。

폼유효성 검사との연동はReact Hook Form実践가이드を、타입安全なAPIの구축はtRPC타입安全API개발를 참고하세요.Zod공식 문서도 확인해 두세요.