zod

Zod のベストプラクティス

TypeScript アプリケーションにおける Zod 4 の包括的なスキーマ検証ガイドです。自動リファクタリングとコード生成の指針となるよう、影響度順に優先順位付けした 8 つのカテゴリ、46 のルールを収録しています。

適用するタイミング

次の場合に、このガイドラインを参照してください。

• 新しい Zod スキーマを作成するとき
• parse() と safeParse() のどちらを使うか選ぶとき
• z.infer を使って型推論を実装するとき
• ユーザーへのフィードバック用に検証エラーを処理するとき
• 複雑なオブジェクトスキーマを合成するとき
• refinements と transforms を使うとき
• バンドルサイズと検証パフォーマンスを最適化するとき
• Zod のコードをベストプラクティスに照らしてレビューするとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	スキーマ定義	CRITICAL	schema-
2	パースと検証	CRITICAL	parse-
3	型推論	HIGH	type-
4	エラー処理	HIGH	error-
5	オブジェクトスキーマ	MEDIUM-HIGH	object-
6	スキーマ合成	MEDIUM	compose-
7	refinements と transforms	MEDIUM	refine-
8	パフォーマンスとバンドル	LOW-MEDIUM	perf-

クイックリファレンス

1. スキーマ定義（CRITICAL）

• schema-use-primitives-correctly - 各型に適切なプリミティブスキーマを使用する
• schema-use-unknown-not-any - 型安全性のため、z.any() ではなく z.unknown() を使用する
• schema-avoid-optional-abuse - オプショナルフィールドの過剰な使用を避ける
• schema-string-validations - スキーマ定義時に文字列の検証を適用する
• schema-use-enums - 固定文字列値には列挙型を使用する
• schema-coercion-for-form-data - フォームデータとクエリデータには型強制を使用する

2. パースと検証（CRITICAL）

• parse-use-safeparse - ユーザー入力には safeParse() を使用する
• parse-async-for-async-refinements - 非同期の refinements には parseAsync を使用する
• parse-handle-all-issues - 最初のものだけでなく、すべての検証上の問題を処理する
• parse-validate-early - システムの境界で検証する
• parse-avoid-double-validation - 同じデータを二重に検証しない
• parse-never-trust-json - JSON.parse の出力を決して信用しない
• parse-validate-for-boolean-checks - はい／いいえの確認には validate() を使用する（Zod 4.6 以降）

3. 型推論（HIGH）

• type-use-z-infer - 手動で型を定義する代わりに z.infer を使用する
• type-input-vs-output - transforms では z.input と z.infer を区別する
• type-export-schemas-and-types - スキーマと推論された型の両方をエクスポートする
• type-branded-types - ドメインの安全性のためにブランド型を使用する
• type-enable-strict-mode - TypeScript の strict モードを有効にする

4. エラー処理（HIGH）

• error-custom-messages - カスタムエラーメッセージを指定する
• error-use-flatten - Zod 4 のエラー整形ヘルパーを使用する
• error-path-for-nested - ネストされたエラーの位置には issue.path を使用する
• error-i18n - 国際化されたエラーメッセージを実装する
• error-avoid-throwing-in-refine - refine 内で例外をスローする代わりに false を返す

5. オブジェクトスキーマ（MEDIUM-HIGH）

• object-strict-vs-strip - 未知のキーに対するポリシーを明示的に選択する
• object-partial-for-updates - 更新用スキーマには partial() を使用する
• object-pick-omit - スキーマのバリエーションには pick() と omit() を使用する
• object-extend-for-composition - フィールドの追加には extend() を使用する
• object-optional-vs-nullable - optional() と nullable() を区別する
• object-discriminated-unions - 型の絞り込みには判別可能なユニオンを使用する

6. スキーマ合成（MEDIUM）

• compose-shared-schemas - 共有スキーマを再利用可能なモジュールに抽出する
• compose-intersection - 型の組み合わせには intersection() を使用する
• compose-lazy-recursive - 再帰スキーマには z.lazy() を使用する
• compose-preprocess - データの正規化には preprocess() を使用する
• compose-pipe - 多段階の検証には pipe() を使用する

7. リファインと変換（MEDIUM）

• refine-vs-superrefine - refine() と superRefine() を適切に使い分けます
• refine-transform-coerce - transform()、refine()、coerce() の違いを理解します
• refine-use-codec - 双方向の変換には z.codec() を使用します（4.1+）
• refine-add-path - リファインエラーに path を追加します
• refine-defaults - デフォルト値を持つオプションフィールドには default() を使用します
• refine-catch - 障害に強いパースには catch() を使用します

8. パフォーマンスとバンドル（LOW-MEDIUM）

• perf-cache-schemas - スキーマインスタンスをキャッシュします
• perf-zod-mini - バンドルサイズが重視されるアプリケーションでは Zod Mini を使用します
• perf-avoid-dynamic-creation - ホットパスでの動的なスキーマ作成を避けます
• perf-lazy-loading - 大きなスキーマを遅延読み込みします
• perf-arrays - 大きな配列の検証を最適化します
• perf-compile-schemas - z.compile を使ってホットパスのスキーマをコンパイルします（Zod 4.5+）

使用方法

まず、プロジェクトのルートで実行します。

npx -y @pymodel/react-frontend-skills detect            # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill zod  # deprecated APIs → rule IDs

上記のルールのうちタスクに該当するものと、scan の各検出項目について、references/<rule-id>.md を読み、重要な理由と誤ったコード・正しいコードを確認してください。

関連スキル

• React Hook Form との連携については、react-hook-form スキルを参照してください

参照元

• Zod 公式ドキュメント
• Zod v4 リリースノート
• Zod GitHub リポジトリ
• Zod Mini
• Total TypeScript Zod チュートリアル