nledford/engineering-review-board / skills/zod-engineering
zod-engineering
VerifiedSelect, add, migrate, review, test, or optimize Zod schemas; parse unknown JSON, form, query, environment, event, or tool data; map Zod errors; or use Zod-to-JSON-Schema and backend interoperability. Do not use for static TypeScript-only work, backend-native validation, public API design, authorization, sanitization, or domain-invariant ownership.
Zod Engineering
Use Zod as a runtime boundary adapter, not as a replacement for public-contract, security, backend, or domain ownership.
Use When
- A JavaScript or TypeScript boundary needs runtime parsing, normalization, or typed output.
- A repository selects or migrates Zod, including Zod 3-to-4 compatibility.
- A Zod schema, mapped validation error, generated JSON Schema, or performance claim needs review or tests.
Boundaries
Parse unknown once at ingress; use parsed output afterwards; map it to plain
application or domain types. Independently validate outbound data that crosses
an untrusted or compatibility-sensitive boundary. Zod parsing is neither
authorization nor sanitization and does not own domain invariants.
For a cross-language wire boundary use:
unknown JSON/IPC → Zod boundary schema → plain wire DTO → backend-native deserializer/validator → backend domain type
and reverse it through a stable serialized envelope before a UI/application parse. See the patterns and examples.
Workflow
- Inspect
package.json, the selected lockfile/package manager/runtime, TypeScript version, existing validator and import style, framework adapter, trust boundary, and installed Zod version. - Preserve a suitable established validator or Standard Schema adapter unless a migration is explicitly requested. Decide whether a public artifact, backend contract, or boundary schema owns the contract before writing a schema.
- Decide missing versus
null, unknown keys, coercion, defaults, transforms/codecs, numeric/date/byte representation, size/depth/cardinality limits, and error exposure explicitly. - Parse at the adapter, map inward, normalize errors at the adapter/render layer, and test the observable boundary.
Core Rules
- Prefer schema-first contracts with
z.infer,z.input, andz.output; usez.toZod<T>()only for type-first compatibility. Never maintain duplicate interfaces and schemas that can drift. - Compose object shapes or use
.safeExtend()rather than long.extend()chains. Use strict discriminated branches for overlapping event or intent unions. - Use object getters for recursive objects; use
z.lazy()when deferred non-object or mutually recursive shapes are clearer. - Read patterns and examples before selecting parse APIs, composition, error mapping, JSON Schema, or interop.
Errors And Security
Map structured issue codes and bounded paths to a stable application/API error
envelope. Do not expose ZodError, default library wording, raw input,
transformed values, full issues, or reportInput without an explicit sanitized
policy. z.treeifyError() and z.flattenError() belong only in a presentation
adapter.
Load security-review and
security-review-evidence for trust
boundaries; they own authorization, sanitization, resource limits, and safe
security evidence. Load internationalization-localization
for translated user messages.
Testing
Test accepted and rejected boundaries; optional/null/unknown-key policy; transforms and input/output divergence; sync and async parsing; mapped error stability; and generated-contract parity. Add bounded property tests only when the repository already uses a suitable generator. The runnable oracle is common patterns.
Load test-driven-development for an
implementation loop and testing-strategy for
coverage review.
Performance And Migration
Measure representative valid, invalid-with-diagnostics, boolean-validation,
schema construction/reuse, transform, depth, and async workloads before using
z.compile() or z.validate(). Upstream benchmarks are not local evidence.
Read the dated Zod 4.5 baseline before a
version-sensitive change or migration.
Routing
javascript-typescript-engineeringowns package/runtime/tooling mechanics.api-designowns public schemas, compatibility, versioning, and stable error envelopes.typescript-javascript-design-patternsowns adapter/core placement.performance-reviewowns workload evidence.python-engineering,rust-engineering, andcsharp-dotnet-engineeringown backend-native DTO validation, mapping, serialization, and errors.
References
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |