Skip to main content
TypeScript Strict Mode & ZodlanguageTarget: TypeScript 5.4+ / 5.5+

TypeScript Strict Mode AI Agent Rules & Cursorrules

Force AI coding agents to write 100% type-safe, exhaustive TypeScript.

Stop AI agents from cutting corners with 'any', 'as unknown as T', or non-null assertions. Enforce branded types, exhaustive switch statements, and schema-driven type safety.

#typescript cursorrules#typescript cursor rules#typescript claude md#strict typescript prompt#cursor rules for typescript

Configuration Workbench

Select your agent format below to preview, copy, or download the configuration file.

Cursor configuration enforcing strict TypeScript typing.
15 lines•0.8 KB
# TypeScript Strict Mode Cursor Rules

You are a Principal TypeScript Architect.

## Strict Invariants
- NEVER use 'any'. Use 'unknown' with type narrowing or generic constraints.
- NEVER use non-null assertions ('!'). Handle null/undefined explicitly.
- Avoid unsafe type casting ('as SomeType'). Use type predicate functions or Zod validation.
- Enforce exhaustive pattern matching on discriminated unions using 'assertNever(x: never): never'.
- Use 'readonly' on properties that should not be mutated after initialization.

## Type Design
- Prefer 'type' for unions, intersections, and primitives; prefer 'interface' for public object contracts.
- Use branded types for domain IDs (e.g., UserId, TenantId) to prevent accidental ID swapping.
- Single source of truth: Infer types from runtime schemas (e.g. 'type User = z.infer<typeof UserSchema>').

Pro-tip: Place this file directly in the root directory of your TypeScript Strict Mode & Zod project. AI agents like Cursor Composer, Claude Code, and GitHub Copilot will read it automatically on initialization.

Architectural Principles Enforced

When this configuration file is loaded into Cursor or Claude Code, the agent strictly enforces the following design invariants:

Zero tolerance for `any`. Use `unknown` with narrowing or typed generic parameters.

No non-null assertions (`!`) unless immediately preceded by a verified runtime guard.

Use discriminated unions with exhaustive `never` checks for domain state machines.

Use branded types for domain identifiers (`type UserId = string & { readonly __brand: unique symbol }`).

Derive TypeScript types directly from Zod schemas (`z.infer<typeof Schema>`) to maintain single source of truth.

Installation & Repository Setup

Place in project root as `.cursorrules` or `.cursor/rules/typescript.mdc`.

1Add `.cursorrules` to the root of your TypeScript monorepo or project.
2Ensure your `tsconfig.json` has `strict: true` and `noUncheckedIndexedAccess: true` enabled.

Verified Agent Behavior Examples

Observe how the AI agent responds when prompted under these active rules.

Scenario: Handling an API response with unknown payload
User prompt: “Write a function to process user preferences received from an external webhook.”
Agent Behavior: The agent parses the incoming payload through a Zod schema using `safeParse`, returning a typed Result object without unsafe `as` casting.

Frequently Asked Questions

Why should I use unknown instead of any in TypeScript?

The `any` type completely disables TypeScript's type checker, propagating unsafety across your codebase. `unknown` forces developers (and AI agents) to perform runtime type narrowing before reading properties.