CLAUDE.md for TypeScript -The Template That Actually Works
TypeScript conventions are useless if your AI agent ignores them. Here's a CLAUDE.md that makes Claude write strict, idiomatic TypeScript every time.
Why TypeScript conventions need to be explicit
TypeScript's compiler enforces types, but it doesn't enforce idioms. Claude will write valid TypeScript that still uses any liberally, mixes interface and type inconsistently, and skips return type annotations. CLAUDE.md is where you encode the team decisions that the compiler can't catch.
The conventions worth encoding
Focus on decisions that vary by team: strict mode expectations, when to use interface vs type, how to handle unknown external data (Zod), naming patterns for generics, and when to annotate return types explicitly. These are the areas where AI agents are most inconsistent without guidance.
TypeScript CLAUDE.md template
Add this to your CLAUDE.md TypeScript section or create a standalone file.
# TypeScript Conventions
## Compiler Settings
- strict: true in tsconfig.json. Never override.
- noImplicitAny: true. No implicit any -ever.
- strictNullChecks: true. Always handle null/undefined explicitly.
## Types vs Interfaces
- `interface` for: object shapes, component props, API response structures, class contracts.
- `type` for: union types, intersection types, utility type aliases, function signatures.
- NEVER use enums. Use union string literals instead:
✓ type Status = 'idle' | 'loading' | 'success' | 'error'
✗ enum Status { Idle, Loading, Success, Error }
## No Any
- Never use `any`. No exceptions without an explicit comment and eslint-disable.
- Use `unknown` when the type is truly unknown, then narrow with type guards.
- Use `as` type assertions only when you have verified the type -add a comment.
## Zod at Boundaries
- All external data (API responses, form inputs, env variables) validated with Zod.
- Infer types from schemas: type User = z.infer<typeof UserSchema>
- Never manually duplicate a type that can be inferred from a Zod schema.
## Generics
- T -general single generic
- TData -data payload shapes
- TResponse -API response wrappers
- TError -error types
- Avoid cryptic single letters (K, V) in non-utility-type contexts.
## Return Types
- Always annotate return types on exported functions.
- Exception: simple inline arrow functions where type is obvious.
## Naming
- Boolean variables: isX / hasX / canX / shouldX
- Custom hooks: useX
- Constants: UPPER_SNAKE_CASE
- Type utilities: XType, XProps, XPayload