Zod with 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 は完全に型安全
}

Zusammenfassung

ZodとClaude Codeの組み合わせにより、バリデーションロジックの実装速度が大幅に向上します。スキーマから型を推論する仕組みによって、型定義とバリデーションルールの二重管理も解消できます。

フォームバリデーションとの連携はReact Hook Form実践ガイドを、型安全なAPIの構築はtRPC型安全API開発を参照してください。Zod公式ドキュメントも確認しておきましょう。