zod AGENTS.md

AGENTS.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

The project uses pnpm workspaces. Key commands:

• pnpm build - Build all packages (runs recursive build command)
• pnpm vitest run - Run all tests with Vitest. Includes the compile-mode project, which re-runs the zod tests with global AOT compilation enabled (see wiki/compile.md).
• pnpm vitest run <path> - Run specific test file (e.g., packages/zod/src/v4/classic/tests/string.test.ts)
• pnpm vitest run <path> -t "<pattern>" - Run specific test(s) within a file (e.g., -t "MAC")
• pnpm vitest run --update - Update all test snapshots
• pnpm vitest run <path> --update - Update snapshots for specific test file
• pnpm test:watch - Run tests in watch mode
• pnpm vitest run --coverage - Run tests with coverage report
• pnpm test:compile - Focused alias for just the compile-mode project. Already covered by pnpm test; use this when iterating on compile-related changes.
• pnpm dev - Execute code with tsx under source conditions
• pnpm dev <file> - Execute <file> with tsx & proper resolution conditions. Usually use for play.ts.
• pnpm dev:play - Quick alias to run play.ts for experimentation
• pnpm check:comments - Fail on stacked // comment lines (--fix joins them)
• pnpm lint - Run biome linter with auto-fix
• pnpm format - Format code with biome
• pnpm fix - Run both format and lint

Rules

• Node.js v24+ required (use nvm if needed); pnpm v10.12.1
• ES modules are used throughout ("type": "module")
• All tests must be written in TypeScript - never use JavaScript
• Use play.ts for quick experimentation; use proper tests for all permanent test cases
• Features without tests are incomplete - every new feature or bug fix needs test coverage
• Don't skip tests due to type issues - fix the types instead
• Test both success and failure cases with edge cases
• Keep added tests as minimal and dense as possible without sacrificing comprehensiveness; avoid redundant assertions or broad fixtures when a focused case proves the behavior.
• No log statements (console.log, debugger) in tests or production code
• Never stack prose across consecutive // lines. Lines have no maximum width here — the editor wraps for display — so a paragraph split across several // lines is just a hard-wrapped line, and hard wrapping breaks search, diffs and editing. Write one long // instead. pnpm check:comments enforces this in pre-commit and CI; --fix joins the offenders. Commented-out code, @ts-/@__NO_SIDE_EFFECTS__-style pragmas, bullet lists, and blocks separated by a bare // are exempt. When two adjacent comments describe two different statements, separate them with a blank line rather than joining them.
• Keep comments SHORT AND TIGHT — one lowercase sentence fragment, one clause, no trailing period. Never a capitalized full sentence, and never two of them. Extreme concision: say only what the code cannot say, and cut the setup sentence, the recap, and the same point restated in different words; a comment that needs three sentences usually means the code should be clearer. Identifiers keep their real casing (Error, parse()), only the prose is lowercase.
• Ask before generating new files
• Use util.defineLazy() for computed properties to avoid circular dependencies
• Never branch on specific schema types in shared code. No def.type === "optional" conditionals, no hardcoded lists of wrapper type names, no walks up the wrapper chain hunting for a particular type. Every schema type added later silently falls through such a check, and the list is wrong the moment someone writes a new wrapper. When a shared path needs to know something about a schema, express it as a structural property on the internals — optin/optout, values, pattern, propValues — and let each type declare its own answer. This is not negotiable in the parse paths; a PR that adds edge-case conditional logic keyed on schema types will be rejected regardless of how well it is tested.
• Performance is critical - parameter reassignment is allowed for optimization
• Any change to packages/zod/src must be weighed on all three axes: runtime performance, memory consumption, and bundle size — see "The three axes" below. A change that improves one and is only checked on that one is not finished.
• ALWAYS use the gh CLI to fetch GitHub information (issues, PRs, etc.) instead of relying on web search or assumptions
• Keep JSDoc as minimal as possible. A self-explanatory type or symbol name needs no doc comment. When a comment is genuinely required, write one short sentence describing behavior — not history, rationale, or examples. Don't add interface-level JSDoc that just restates the interface name.
• When you've modified a PR (or opened/closed/commented on one), include the PR URL liberally in summary messages — at minimum once at the end of any reply that touched it
• When creating a PR, do not include a separate test plan section in the body. Link to any relevant issues under discussion, and use the same copywriting guidelines from "Commenting on issues and PRs": concise maintainer voice, prose over templates, and validation details only when they are material to the reader.
• Format validators (z.iso.*, z.email(), z.url(), z.uuid(), …) are deliberately narrower than the specs they're named after. "The spec allows X" is not a reason to accept X — see "Format validators: spec compliance is not the bar" below.
• NEVER bump the version in packages/zod/package.json (or any package's package.json). A version bump is the only thing that triggers a release; everything else (including direct pushes to main) is recoverable until that happens. If a version bump is genuinely needed, ask first.