TypeScript Cursor Rules Template

When Cursor generates code that does not type-check, the cheapest fix available to it is widening something to any — and because any propagates, one any parameter can un-type an entire call chain before a human notices. This is the single most damaging habit in AI-written TypeScript: the diff looks fine, tsc passes, and the error surfaces months later at runtime.

The rule pair "avoid any, use unknown and type guards" changes what Cursor does when it hits a type it cannot name. unknown is deliberately inconvenient: you cannot touch the value until you narrow it, so Cursor is forced to generate the typeof check, the in check, or the custom guard function that documents what the value actually is. That inconvenience is the feature — the narrowing code the rule extracts from Cursor is exactly the validation a careful human would have written.

Reasonable teams disagree about interface versus type, and the language mostly does not care. Cursor, however, mirrors whatever file it happens to have in context — so a codebase without a written convention drifts into a mix, and every AI-generated PR reopens the style debate. The template picks the mainstream split: interfaces for object shapes, type aliases for unions, intersections, and mapped types.

The split is not purely cosmetic. Interfaces produce better error messages and support declaration merging, which matters when Cursor augments third-party types; unions and mapped types simply cannot be expressed as interfaces, so the alias half of the rule tells Cursor where the boundary sits instead of letting it force object-shape syntax onto things that are not object shapes. If your team standardized on type for everything, flip the rule — the value is in having a written answer, not in this particular one.

Under strict tsconfig settings a catch variable is unknown, and this is where AI-generated TypeScript most often cheats: Cursor will write catch (e: any) or e as Error to reach .message, reintroducing the exact unsafety strict mode exists to prevent. The error-handling rules make the honest version the default — narrow with instanceof or a type guard, and never throw non-Error values, so there is always something meaningful to narrow to.

The Result<T, E> discriminated-union rule goes a step further: for expected failures, the error becomes part of the return type instead of an invisible throw. This suits AI-assisted work unusually well, because Cursor cannot see which functions in your codebase throw — but it can see a return type. When failure is in the signature, the compiler forces every AI-generated call site to handle it, no code review required.

as is a promise to the compiler with no evidence attached, and Cursor makes that promise freely — especially on config objects, JSON parses, and test fixtures. An as Config assertion both silences excess-property errors and widens the value, so typos in keys survive and literal types are lost.

The template steers Cursor to satisfies for these cases: the value is checked against the target type but keeps its own narrower inferred type, so a misspelled property is a compile error and downstream code still sees the exact literals. Assertions do not disappear entirely — DOM casts and deliberate test doubles remain legitimate — but with satisfies named in the rules, Cursor stops reaching for as as the default way to make a type complaint go quiet.