zod

Zod のベストプラクティス

TypeScript アプリケーションにおける Zod の包括的なスキーマ検証ガイドです。8 つのカテゴリにわたる 43 のルールが含まれており、影響度に基づいて優先順位を付け、リファクタリングの自動化やコード生成に役立てます。

適用する場面

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

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

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

優先度	カテゴリ	影響度	接頭辞
1	スキーマ定義	CRITICAL	schema-
2	解析と検証	CRITICAL	parse-
3	型推論	HIGH	type-
4	エラー処理	HIGH	error-
5	オブジェクトスキーマ	MEDIUM-HIGH	object-
6	スキーマの合成	MEDIUM	compose-
7	リファインメントと変換	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 - 非同期リファインメントには parseAsync を使用します
• parse-handle-all-issues - 最初の問題だけでなく、すべての検証問題を処理します
• parse-validate-early - システム境界で検証します
• parse-avoid-double-validation - 同じデータを二重に検証しないようにします
• parse-never-trust-json - JSON.parse の出力を決して信頼しないでください

3. 型推論（HIGH）

• type-use-z-infer - 手動で型を定義する代わりに z.infer を使用します
• type-input-vs-output - 変換を扱う際は 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 - フォームのエラー表示には flatten() を使用します
• error-path-for-nested - ネストされたエラーの位置を示すには issue.path を使用します
• error-i18n - 国際化されたエラーメッセージを実装します
• error-avoid-throwing-in-refine - refine 内で例外をスローする代わりに false を返します

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

• object-strict-vs-strip - 不明なキーの扱いには strict() と 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-add-path - リファインメントのエラーに path を追加します
• refine-defaults - デフォルト値のあるオプショナルフィールドには default() を使用します
• refine-catch - 障害に強い解析には catch() を使用します

8. パフォーマンスとバンドル（低〜中）

• perf-cache-schemas - スキーマインスタンスをキャッシュする
• perf-zod-mini - バンドルサイズに配慮が必要なアプリケーションでは Zod Mini を使用する
• perf-avoid-dynamic-creation - ホットパスでの動的なスキーマ作成を避ける
• perf-lazy-loading - 大きなスキーマを遅延読み込みする
• perf-arrays - 大きな配列の検証を最適化する

使い方

詳しい説明とコード例については、各リファレンスファイルを参照してください。

• セクションの定義 - カテゴリー構成と影響レベル
• ルールのテンプレート - 新しいルールを追加するためのテンプレート
• 個別のルール：references/{prefix}-{slug}.md

コンパイル済みの完全版ドキュメント

すべてのルールを展開したガイド全文はこちらです：AGENTS.md

関連スキル

• React Hook Form との統合については、react-hook-form スキルを参照してください
• API クライアントの生成については、orval スキルを参照してください

ソース

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