Validation (Zod + Guards)

Validation (Zod + Guards)

Consistent validation at boundaries: Zod for complex schemas, small guards for simple runtime checks.

When to Use

Use this skill when:

• Validating API responses or external data in services
• Validating request/​input shapes at boundaries (e.g. route handlers, SDK)
• Adding or refactoring utils/​validation/ helpers
• Defining Zod schemas alongside types in types/<area>/

Non-Negotiables (MUST)

• Services: validate API/​external data with Zod schemas (e.g. .safeParse()).
• Utils: keep small coercion/​guard helpers under utils/​validation/ (one function per file).
• Types: Zod schemas can live in types/<area>/; infer types with z.infer<typeof Schema>.
• Prefer unknown inputs at boundaries + explicit narrowing.
• No inline validation logic inside components/​hooks.

Rules

Boundaries & Placement

• validation-boundaries - Where validation lives (services, utils, types)

Zod Schemas (Complex Validation)

• validation-zod-schemas - Using Zod for complex validation with .safeParse()
• validation-zod-types - Inferring types from Zod schemas with z.infer

Guard Helpers (Simple Runtime Checks)

• validation-guard-helpers - Creating simple guard functions with type predicates
• validation-guard-examples - Recommended guard helpers (isRecord, isNonEmptyString, etc.)

Anti-Patterns

• validation-no-inline - No inline validation logic in components/​hooks

How to Use

Read individual rule files for detailed explanations and code examples:

rules/​validation-boundaries.md
rules/​validation-zod-schemas.md
rules/​validation-guard-helpers.md

Each rule file contains:

• Brief explanation of why it matters
• Code examples (correct and incorrect patterns)
• Additional context and best practices