К основному содержанию
правило CX Codex

zod-validation-patterns — правило для Claude Code: установка

Правило zod-validation-patterns задаёт шаблоны валидации входных DTO через Zod 4 в TypeScript-проектах. Оно пригодится при создании и проверке схем.

MIT ★ 372 обновлён 2026-09-10

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add giuseppe-trisciuoglio/developer-kit
/plugin install developer-kit-typescript@developer-kit
Открыть на GitHub

Что делает zod-validation-patterns

Правило применяется к файлам **/*.ts и описывает структуру схем в libs/shared/{domain}-dto/. Для каждой схемы предлагается отдельный файл вида libs/shared/{domain}-dto/src/lib/{action}-{entity}.schema.ts, экспорт схемы и типа через z.infer, а также реэкспорт из src/index.ts.

Рекомендации охватывают цепочки для строк, email, обязательных и необязательных полей, регулярных выражений, перечислений и UUID. Отдельно разобраны z.record() с двумя типами, .pipe() для последовательных преобразований, .refine() для бизнес-проверок, обработка ошибок и различия .default() и .prefault() в Zod 4. В обработчиках Lambda правило предлагает применять .safeParse() и возвращать ошибки валидации. Код на Zod 3 придётся сверять, потому что рекомендации рассчитаны на Zod 4.

Какие задачи решает

  • разложить Zod-схемы по файлам DTO
  • задать порядок очистки и проверки строк
  • вывести TypeScript-тип через z.infer
  • проверить входные данные через .safeParse()
  • перейти с устаревших приёмов Zod 3 на синтаксис Zod 4

Примеры запросов агенту

  • Создай схему CreateTenantSchema для DTO арендатора с очисткой имени и проверкой adminEmail.
  • Проверь все TypeScript-схемы в libs/shared/{domain}-dto/ и приведи цепочки .trim(), преобразований и валидаций к правилу.
  • Обнови проверку записи с одним аргументом z.record() до синтаксиса Zod 4 с типами ключа и значения.

Как установить zod-validation-patterns

1Через маркетплейс плагинов

/plugin marketplace add giuseppe-trisciuoglio/developer-kit
/plugin install developer-kit-typescript@developer-kit

2Вручную: положить файлы

.claude/rules/zod-validation-patterns.md

Поле paths во frontmatter ограничивает файлы

По шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать

Вопросы о zod-validation-patterns

Как установить zod-validation-patterns в Claude Code?

Затем /plugin install developer-kit-typescript@developer-kit и добавьте файл .claude/rules/zod-validation-patterns.md. Обратите внимание: команды нужно писать как /plugin marketplace add giuseppe-trisciuoglio/developer-kit и /plugin install developer-kit-typescript@developer-kit.

Что делает zod-validation-patterns?

Правило задаёт единый способ размещать и писать схемы Zod 4 для входных DTO в TypeScript. Оно также описывает вывод типов, обработку ошибок и проверку данных в Lambda-обработчиках.

Какая версия Zod нужна для zod-validation-patterns?

Рекомендации рассчитаны на Zod 4: в них используются z.email(), z.uuid(), двухаргументный z.record(), единый параметр error и .prefault().

Исходный текст

zod-validation-patterns.md · MIT
---
paths:
  - "**/*.ts"
---

# Rule: Zod 4 Validation Patterns

## Context
Enforce consistent validation patterns using Zod v4 for input DTOs in `libs/shared/{domain}-dto/`. Zod schemas provide type-safe runtime validation with clean TypeScript inference.

## Guidelines

### Schema File Organization
- Place Zod schemas in `libs/shared/{domain}-dto/src/lib/{action}-{entity}.schema.ts`
- Export both the schema (`const`) and the inferred type (`type`)
- Use descriptive schema names: `{Action}{Entity}Schema` (e.g., `CreateTenantSchema`)

```typescript
// libs/shared/tenant-dto/src/lib/create-tenant.schema.ts
import { z } from 'zod';

export const CreateTenantSchema = z.object({
  tenantName: z.string().trim().min(1).max(255),
  adminEmail: z.string().trim().toLowerCase().pipe(z.email()),
});

export type CreateTenantInput = z.infer<typeof CreateTenantSchema>;
```

### String Validation Chain
Always apply transformations **before** validations. The correct order:
1. `.string()` — base type
2. `.trim()` — remove whitespace
3. `.toLowerCase()` / `.toUpperCase()` — normalize case if applicable
4. `.pipe()` — complex transformations (email, UUID parsing)
5. `.min()`, `.max()`, `.regex()` — validations
6. Custom error messages as last parameter

```typescript
// ✅ Correct order
z.string()
  .trim()
  .toLowerCase()
  .pipe(z.email('Invalid email format'))
  .max(254, 'Email must be at most 254 characters')

// ❌ Wrong: validations before trim
z.string().min(1).trim()  // trim happens after min check
```

### Required Fields
Use `.min(1, 'message')` for required non-empty strings:

```typescript
tenantName: z
  .string()
  .trim()
  .min(1, 'Tenant name is required')
  .max(255, 'Tenant name must be at most 255 characters')
```

### Email Validation
Use `.pipe(z.email())` with trim and lowercase:

```typescript
email: z
  .string()
  .trim()
  .toLowerCase()
  .max(254, 'Email must be at most 254 characters')
  .pipe(z.email('Invalid email format'))
```

### Regex Patterns
- Define regex constants at module level with descriptive names
- Use `u` flag for Unicode patterns
- Provide clear error messages showing expected format

```typescript
const SUPPORTED_VAT_REGEX = /^IT\d{11}$/u;

vatNumber: z
  .string()
  .trim()
  .min(1, 'VAT number is required')
  .max(14, 'VAT number must be IT followed by 11 digits')
  .regex(SUPPORTED_VAT_REGEX, 'VAT number must be in format IT followed by 11 digits (e.g., IT12345678901)')
```

### Enum Validation with Zod
Export native TypeScript enums from `*-enum.ts` files. For Zod schemas, use `.enum()` which handles both string unions AND native enums in Zod v4:

```typescript
// tenant-status.enum.ts
export enum TenantStatus {
  Created = 'created',
  Active = 'active',
  Suspended = 'suspended',
  Deleted = 'deleted',
}

// In schema: use z.enum() for Zod-native validation with string literals
status: z.enum(['created', 'active', 'suspended', 'deleted'])

// In Zod v4, z.enum() also accepts native TypeScript enums
// z.nativeEnum() is deprecated - prefer z.enum()
import { TenantStatus } from './tenant-status.enum';
status: z.enum(TenantStatus)
```

### Type Inference
Always export the inferred type using `z.infer`:

```typescript
export const CreateTenantSchema = z.object({ /* ... */ });
export type CreateTenantInput = z.infer<typeof CreateTenantSchema>;
```

### Optional Fields
Use `.optional()` for nullable fields:

```typescript
description: z
  .string()
  .trim()
  .max(1000)
  .optional(),
```

### Barrel Export Pattern
Export schemas and types from the library index:

```typescript
// src/index.ts
export { CreateTenantSchema } from './lib/create-tenant.schema';
export type { CreateTenantInput } from './lib/create-tenant.schema';
```

### Usage in Lambda Handlers
Use `.safeParse()` for validation with error handling:

```typescript
import { CreateTenantSchema, type CreateTenantInput } from '@sibill-erp-gateway/shared/tenant-dto';

const validationResult = CreateTenantSchema.safeParse(parseResult.data);
if (!validationResult.success) {
  return this.validationErrorResponse(validationResult.error.issues, requestId);
}
// validationResult.data is typed as CreateTenantInput
```

## Zod 4 Specific Patterns

### UUID Validation

Zod v4 supports one UUID validation approaches:

```typescript
// Standalone z.uuid() - RFC 9562/4122 compliant
const strictUuidSchema = z.uuid();

strictUuidSchema.parse('550e8400-e29b-41d4-a716-446655440000'); // ✅
```

Use `z.guid()` for permissive UUID-like patterns (any 8-4-4-4-12 hex format).

### Record Schemas (Zod v4 Breaking Change)

Zod v4 **requires both key and value types** explicitly - single-argument usage is removed:

```typescript
// ❌ Zod 3 (deprecated in v4)
z.string().uuid();
z.record(z.string())  // Error: Expected 2-3 arguments, got 1

// ✅ Zod 4 - both key and value types required
z.record(z.string(), z.string())     // Record<string, string>
z.record(z.string(), z.unknown())    // Record<string, unknown>
z.record(z.enum(['a', 'b']), z.number())  // Record<'a'|'b', number>
```

### .pipe() for Transformations
Zod 4 uses `.pipe()` for sequential transformations:

```typescript
// Transform and validate email
z.string()
  .trim()
  .toLowerCase()
  .pipe(z.email())  // pipe creates new zod schema

// Custom transformation with validation
z.string()
  .transform(val => val.toUpperCase())
  .pipe(z.enum(['VALUE1', 'VALUE2']))
```

### Refine with Custom Validation
Use `.refine()` for business logic validation:

```typescript
vatNumber: z
  .string()
  .trim()
  .min(1)
  .refine(
    (val) => validateVatChecksum(val),
    { message: 'VAT checksum validation failed' }
  )
```

### Error Handling (Zod v4)

Zod v4 uses a unified `error` parameter instead of separate `invalid_type_error`/`required_error`:

```typescript
// ❌ Zod 3 style (deprecated in v4)
z.string({ invalid_type_error: 'Must be a string', required_error: 'Required' })

// ✅ Zod 4 style - unified error parameter
z.string({ error: 'Invalid string value' })

// ✅ Zod 4 with error function for dynamic messages
z.string({
  error: (issue) => issue.input === undefined ? 'Required' : 'Invalid'
})
```

### Default Values (Zod v4)

`.default()` in Zod v4 short-circuits for `undefined`. Use `.prefault()` to replicate Zod 3's pre-parse default behavior:

```typescript
// .default() only applies when value is undefined
const schema = z.string().default('fallback');
schema.parse(undefined); // 'fallback'
schema.parse(null);      // Error (null is not undefined)

// Use .prefault() for Zod 3-like behavior
const prefaultSchema = z.string().prefault(() => 'fallback');
```

## Examples

### ✅ Good
```typescript
export const CreateTenantSchema = z.object({
  tenantName: z
    .string()
    .trim()
    .min(1, 'Tenant name is required')
    .max(255, 'Tenant name must be at most 255 characters')
    .regex(/^[a-zA-Z0-9_\-\s]+$/u, 'Tenant name contains invalid characters'),
  vatNumber: z
    .string()
    .trim()
    .min(1, 'VAT number is required')
    .regex(SUPPORTED_VAT_REGEX, 'Invalid VAT format'),
  adminEmail: z
    .string()
    .trim()
    .toLowerCase()
    .max(254)
    .pipe(z.email('Invalid email format')),
});

export type CreateTenantInput = z.infer<typeof CreateTenantSchema>;

// UUID validation
const uuidSchema = z.uuid();
const userIdSchema = z.string().uuid();

// Record with key and value types (Zod v4)
const metadataSchema = z.record(z.string(), z.string());
const payloadSchema = z.record(z.string(), z.unknown());

// Enum validation with TypeScript native enum
const statusSchema = z.enum(TenantStatus);  // z.enum() handles native enums in v4
```

### ❌ Bad
```typescript
// No trim before validation — accepts "  value  "
z.string().min(1).max(255)

// No lowercase for email — case-sensitive comparison
z.string().email()

// Missing error messages — generic Zod errors
z.string().min(1).max(255).regex(/^[a-z]+$/)

// Missing type export
export const schema = z.object({ name: z.string() });
// No: export type SchemaInput = z.infer<typeof schema>;

// Regex without unicode flag
z.string().regex(/^[a-z]+$/)  // Should be /^[a-z]+$/u

// Record with single argument (Zod v4 breaking change)
z.record(z.string())  // Error: Expected 2-3 arguments, got 1

// Native enum with z.nativeEnum() (deprecated in v4)
z.nativeEnum(MyEnum)  // Use z.enum(MyEnum) instead
```

## File Naming

| Type | Naming | Example |
|---|---|---|
| Schema file | `{action}-{entity}.schema.ts` | `create-tenant.schema.ts` |
| Schema const | `{Action}{Entity}Schema` | `CreateTenantSchema` |
| Inferred type | `{Action}{Entity}Input` | `CreateTenantInput` |
| Enum file | `{entity}-status.enum.ts` | `tenant-status.enum.ts` |
| DTO file | `{entity}.dto.ts` | `tenant.dto.ts` |

© Giuseppe Trisciuoglio · MIT · giuseppe-trisciuoglio/developer-kit

Похожие правила IDE

Все правила IDE по теме «Языки программирования» →
zod-schema-validation Mindrally Скилл zod-schema-validation задаёт правила валидации данных через Zod и вывода типов TypeScript на границах системы: в API, формах и внешних ответах. Помогает писать схемы без лишнего дублирования. CX Codex +1 1 200установок zod-validation-expert davila7 Скилл zod-validation-expert настраивает Claude Code на генерацию схем валидации Zod, вывод типов через z.infer и связку с формами React Hook Form или экшенами Next.js. CX Codex +1 238установок zod-validation oakoss Скилл zod-validation учит агента синтаксису и правилам Zod v4 в TypeScript. Пригодится при составлении схем данных, валидации форм, парсинге API и конвертации схем в JSON Schema. CX Codex +1 222установок validation-patterns wshaddix Скилл validation-patterns подсказывает агенту, как валидировать данные в ASP.NET Core: от атрибутов до FluentValidation и проверки конфигурации на старте. CX Codex +1 545установок laravel-validation-patterns iSerter Скилл laravel-validation-patterns обучает ИИ-агента паттернам валидации в Laravel: от выноса логики в Form Request до фильтрации строк и условий Rule::when. Помогает избежать утечек $request->all(). CX Codex +1 105установок zod bobmatnyc Скилл по библиотеке zod: схемы один раз, а на выходе проверка данных в рантайме и типы TypeScript. Пригодится на формах и API. CX Codex +1 907установок

Из того же набора191

Весь набор →
java-security-expert Субагент java-security-expert проводит аудит безопасности Java и Spring Boot: находит уязвимости по OWASP Top 10, проверяет OAuth2 и настраивает DevSecOps-пайплайны. CX Codex ★ 372звёзд репо general-code-reviewer Субагент general-code-reviewer проверяет изменения на ошибки, уязвимости и проблемы качества, а в отчёт включает только находки с уверенностью не ниже 80%. CX Codex ★ 372звёзд репо aws-cloudformation-vpc Скилл aws-cloudformation-vpc для Claude Code содержит шаблоны CloudFormation для VPC и помогает создавать сетевую инфраструктуру AWS. CX Codex +1 ★ 372звёзд репо devkit.java.security-review Команда devkit.java.security-review для Claude Code проверяет безопасность корпоративных Java-приложений. Она запускается для аудита приложения или перед выпуском в production. CX Codex +1 ★ 372звёзд репо prompt-engineering-expert Субагент prompt-engineering-expert для создания и оптимизации промптов под LLM. Применяет chain-of-thought, constitutional AI, few-shot learning и другие техники. CX Codex ★ 372звёзд репо devkit.typescript.code-review Команда devkit.typescript.code-review проводит аудит TypeScript-монорепозиториев на Nx с бэкендом NestJS, веб-клиентом React и мобильными приложениями React Native. CX Codex +1 ★ 372звёзд репо nestjs-code-review-expert Субагент nestjs-code-review-expert для Claude Code проверяет NestJS-код после изменений и при разработке функций. Он разбирает архитектуру, практики TypeScript и качество тестов. CX Codex ★ 372звёзд репо spring-boot-code-review-expert Субагент spring-boot-code-review-expert разбирает изменения в Spring Boot-коде: паттерны, архитектуру, REST, транзакции и тесты. На выходе — замечания по severity с примерами правок. CX Codex ★ 372звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой