majiayu000 Zod Validation
概要
Zodライブラリによるランタイムバリデーションとスキーマ定義を専門とするスキル。 TypeScriptの型推論と組み合わせて、コンパイル時とランタイムの両方で型安全性を確保する。
ワークフロー
Phase 1: スキーマ設計
目的: データ構造からZodスキーマを設計する
アクション:
- バリデーション対象のデータ構造を分析
- TypeScript型からZodスキーマへマッピング
- 制約（min/max/regex/refine）を追加
- 再利用可能なスキーマパターンを適用
z.infer<typeof schema>で型推論を確認
Task: agents/schema-designer.md を参照
Phase 2: バリデーション実装
目的: 設計したスキーマでバリデーションロジックを実装する
アクション:
- parse/safeParseの適切な選択
- エラーハンドリングの実装
- カスタムバリデーション（refine/superRefine）の実装
- エラーメッセージのフォーマット
Task: agents/validation-implementer.md を参照
Phase 3: 統合
目的: フレームワークやAPIにバリデーションを統合する
アクション:
- フォーム統合: react-hook-form + zodResolver
- API統合: リクエスト/レスポンス検証
Task: agents/form-integrator.md または agents/api-validator.md を参照
Phase 4: 検証と記録
目的: 成果物の検証と実行記録の保存
アクション:
scripts/validate-schema.mjsでスキーマ構造を確認scripts/validate-skill.mjsでスキル構造を確認scripts/log_usage.mjsで記録を残す
Task仕様ナビ
| Task | リソース | 説明 |
|---|---|---|
| スキーマ設計 | agents/schema-designer.md | データ構造からZodスキーマを設計 |
| バリデーション実装 | agents/validation-implementer.md | スキーマを使用したバリデーション実装 |
| フォーム統合 | agents/form-integrator.md | react-hook-form等との統合 |
| API検証 | agents/api-validator.md | APIリクエスト/レスポンス検証 |
ベストプラクティス
すべきこと
- 型推論を活用する:
z.infer<typeof schema>を使用して型安全性を確保 - safeParseを使用する: ユーザー入力には例外をスローしないsafeParseを使用
- エラーメッセージをカスタマイズする: ユーザーフレンドリーなメッセージを定義
- スキーマを再利用する: 共通パターンは抽出して再利用（extend, merge, pick, omit）
- 段階的バリデーション: 複雑なバリデーションはrefine/superRefineで実装
- 詳細は
references/schema-patterns.mdとreferences/validation-patterns.mdを参照
避けるべきこと
- parseを直接使用しない: ユーザー入力にはsafeParseを使用（例外回避）
- バリデーションロジックを分散させない: 一箇所にまとめる
- 非同期バリデーションを過度に使用しない: パフォーマンスへの影響を考慮
- エラーハンドリングを省略しない: すべてのバリデーション結果を処理
- any型を使用しない:
z.any()の使用は最小限に
リソース参照
agents/（Task仕様書）
| ファイル | 説明 |
|---|---|
| agents/schema-designer.md | スキーマ設計のTask仕様書 |
| agents/validation-implementer.md | バリデーション実装のTask仕様書 |
| agents/form-integrator.md | フォーム統合のTask仕様書 |
| agents/api-validator.md | API検証のTask仕様書 |
references/（詳細知識）
| ファイル | 説明 |
|---|---|
| references/schema-patterns.md | スキーマパターンと実装例 |
| references/validation-patterns.md | バリデーションパターンと実践例 |
| references/integration-patterns.md | フレームワーク統合パターン |
scripts/（検証・ロギング）
| スクリプト | 説明 | 使用法 |
|---|---|---|
validate-schema.mjs |
Zodスキーマの構造検証 | node scripts/validate-schema.mjs <schema-file> |
validate-skill.mjs |
スキル構造の検証 | node scripts/validate-skill.mjs |
log_usage.mjs |
使用統計とログ記録 | node scripts/log_usage.mjs --help |
assets/（テンプレート）
| テンプレート | 説明 | 用途 |
|---|---|---|
| assets/schema-template.ts | 基本スキーマテンプレート | 新規スキーマ作成 |
| assets/api-schema-template.ts | APIスキーマテンプレート | API検証実装 |
| assets/form-validation-template.tsx | フォーム統合テンプレート | react-hook-form連携 |
変更履歴
| Version | Date | Changes |
|---|---|---|
| 4.0.0 | 2026-01-01 | 18-skills.md完全準拠: 4エージェント体制、統合パターン追加、テンプレート拡充 |
| 3.0.0 | 2026-01-01 | 18-skills.md仕様準拠：agents/追加、references/整理、ワークフロー刷新 |
| 2.0.0 | 2025-12-31 | YAML frontmatter最適化、Task仕様ナビ追加 |
| 1.0.0 | 2025-12-24 | 初版作成 |