TypeScript best practices

Apply the type-system-discipline principle skill first; this skill grounds it in TypeScript syntax.

Rule	Summary
Discriminated unions	Model variants with a `kind` literal discriminant so impossible states can't be represented. No optional-field bags.
Branded types	Brand primitives with `& { readonly __brand: "X" }` so they can't be mixed up. Validate once at creation.
`unknown` over `any`	External data is `unknown`. `any` disables type checking everywhere it touches.
No `as` casts	Every `as` is a runtime crash waiting. Cast only after validation.
Narrowing hierarchy	Discriminant switch > `in` operator > `typeof`/`instanceof` > user-defined type guard > `as`.
Type guards	Must verify the claim. A lying guard is worse than `as` because the bug hides behind a name that says it's safe. Name them `isX` or `hasX`.
Exhaustiveness	Inline `const _exhaustive: never = x;` in default arms so the compiler errors when a new variant is added.
`satisfies` over `as`	Validates the value without widening literal types.
Boundary validation	Validate where data crosses in; trust types inside. See the boundary-discipline principle skill.
Schema-derived types	Reach for `Pick`/`Omit`/`Parameters`/`ReturnType`/`Awaited`/`typeof` before declaring a new interface.
Object args	Pass objects, not positional, so argument order is self-documenting. Skip on hot paths (per-frame render, tokenizers, parsers).

Examples: references/patterns.md.

typescript-best-practices