Cursor Rules Advanced Guide 2026: Framework-Specific Configs & .mdc Best Practices

---
description: "Enforce Next.js 15 App Router conventions: server components by default, client components only when needed, no Pages Router patterns"
alwaysApply: false
globs: ["app/**/*.tsx", "app/**/*.ts", "components/**/*.tsx"]
---

---
description: "Global security and output rules"
alwaysApply: true
---
- Never expose secrets or API keys in generated code
- All user inputs must be validated before use
- Use parameterized queries — no string concatenation in SQL

---
description: "React component rules"
alwaysApply: false
globs: ["**/*.tsx", "**/*.jsx"]
---

---
description: "Authentication flow: JWT refresh token rotation pattern, session storage strategy, and OAuth2 provider integration details"
alwaysApply: false
---

---
description: "Next.js 15 App Router conventions — server vs client components, data fetching, routing patterns"
alwaysApply: false
globs: ["app/**/*.tsx", "app/**/*.ts", "components/**/*.tsx"]
---

## Component Model
Next.js 15 App Router introduces a fundamental shift in how components are classified: every component is a Server Component by default unless explicitly marked otherwise. This distinction determines where rendering happens, what APIs are available, and how data flows through the tree. The AI must respect this boundary to avoid generating code that breaks at runtime — mixing server and client patterns is the most common source of hydration errors and unexpected behavior in App Router projects. Client components are not worse, they are simply different: they handle interactivity, browser APIs, and stateful logic. Server components handle data access, heavy computation, and anything that should never reach the client bundle. Getting this boundary right is the foundation of every other App Router convention.
- Default to Server Components — add 'use client' only when you need hooks, event listeners, or browser APIs
- Never use `getServerSideProps`, `getStaticProps`, or Pages Router patterns in the `app/` directory
- Colocate loading.tsx, error.tsx, and not-found.tsx with their route segments

## Data Fetching
App Router data fetching is built on React's extended `fetch` API and async Server Components, replacing the Pages Router pattern of `getServerSideProps` and `getStaticProps` entirely. The mental model is straightforward: fetch data where you need it, as close to the component that uses it as possible, using native `async/await` syntax. Waterfall fetches — where one await blocks another — are the primary performance bottleneck in Server Component trees. Parallel fetching with `Promise.all` eliminates that bottleneck. The `cache()` function and `revalidate` options on `fetch` replace custom caching layers and give fine-grained control over when data is considered stale. Understanding these primitives prevents the AI from reaching for client-side `useEffect` patterns that belong to the Pages Router era and degrade both performance and developer experience.
- Use async Server Components for data fetching — no useEffect for initial data
- Parallel data fetching: use Promise.all for independent requests
- Use `cache()` and `revalidate` options on fetch, not custom caching layers

## TypeScript
TypeScript integration in Next.js 15 App Router is deeper than in previous versions: Server Actions require typed params, route segment config types are enforced by the framework, and the `Metadata` type constrains what `generateMetadata` can return. Allowing implicit `any` in this environment undermines the entire value of TypeScript — the AI will generate code that compiles but hides type errors that surface only at runtime. Props interfaces must be explicit because Server Components pass data across the server boundary where type safety is the only contract. `React.FC` is broadly discouraged in the React community because it adds an implicit `children` prop and obscures return types; explicit annotations are always clearer. Server Action params validated with zod provide runtime safety that TypeScript alone cannot guarantee, since actions receive raw form data.
- All props interfaces explicitly typed — no implicit `any`
- Use `React.FC` sparingly — prefer explicit return type annotations
- Server Action params must be validated with zod before use

---
description: "TypeScript strict mode conventions — no implicit any, exhaustive type guards, discriminated unions"
alwaysApply: false
globs: ["**/*.ts", "**/*.tsx"]
---

## Type Safety
TypeScript strict mode enforces a set of compiler options — `strictNullChecks`, `noImplicitAny`, `strictFunctionTypes`, and others — that together eliminate the most common categories of runtime type errors. When the AI generates code without these constraints in mind, it produces patterns that pass loose TypeScript checks but fail strict mode, requiring developers to fix type errors manually. The `any` type is the most damaging: it silently disables type checking for everything it touches. Using `unknown` with explicit type guards is the correct alternative — it forces the developer and the AI to account for every possible shape of data. Discriminated unions with exhaustive switch statements are the idiomatic TypeScript pattern for modeling states that have mutually exclusive shapes; the `satisfies never` default case catches unhandled variants at compile time, preventing silent runtime failures when new variants are added.
- Never use `any` — use `unknown` and narrow with type guards
- Exhaustive switch statements: add `satisfies never` default case for discriminated unions
- Prefer `type` over `interface` for data shapes; use `interface` only for extension points

## Patterns to Avoid
Certain TypeScript patterns represent shortcuts that erode type safety over time and signal that the AI is not respecting the project's type discipline. Non-null assertions (`!`) tell TypeScript to trust the developer that a value is not null or undefined — a promise that is frequently broken, especially in generated code where the AI does not have full context of initialization order. Suppression directives like `@ts-ignore` hide real errors from the compiler and make codebases harder to upgrade safely. Unsafe `as Type` casts bypass structural type checking entirely and are a common source of subtle bugs where data does not match the assumed shape. Each of these patterns is sometimes necessary, but only with explicit justification and only when a proper type guard or narrowing approach is genuinely not feasible in that specific context.
- No non-null assertions (`!`) except in test files
- No `@ts-ignore` or `@ts-expect-error` without an explaining comment
- No `as Type` casts without a guard function verifying the shape

---
description: "FastAPI 0.115+ with Python 3.11+ — async endpoints, Pydantic v2 models, dependency injection patterns"
alwaysApply: false
globs: ["**/*.py", "app/api/**/*.py", "routers/**/*.py"]
---

## Endpoint Conventions
FastAPI's design is built around async-first execution and Pydantic-based schema validation — deviating from these conventions produces endpoints that are harder to test, slower under load, and inconsistent with the rest of the codebase. Synchronous route handlers block the event loop and negate FastAPI's concurrency advantages; every endpoint should be `async def`. Raw dict inputs and outputs bypass Pydantic's validation and serialization, which means no automatic OpenAPI schema generation, no input coercion, and no response model enforcement. HTTP status codes embedded as magic numbers inside response bodies instead of using the `status_code=` parameter break HTTP semantics and make API clients harder to write correctly. The dependency injection system for database sessions ensures connection lifecycle is managed by FastAPI rather than scattered across individual route handlers, which simplifies testing and prevents connection leaks.
- All endpoints must be async — no synchronous route handlers
- Use Pydantic v2 BaseModel for request/response schemas — no raw dicts
- HTTP status codes explicit: use `status_code=` parameter, not magic numbers in body
- Dependency injection for DB sessions: `db: AsyncSession = Depends(get_db)`

## Error Handling
FastAPI provides a structured error handling system through `HTTPException` and custom exception handlers that should be the sole mechanism for surfacing errors to API consumers. Raising `HTTPException` with a meaningful `detail` string gives clients actionable information and keeps error responses consistent across the API. Registering exception handlers in `main.py` centralizes error logic so that all routes benefit from the same behavior without duplicating try/except blocks in every handler. Inline exception handling inside routes is acceptable only for business logic errors that require context from the route itself. Logging with structlog instead of print statements ensures errors are captured in a structured format that works with log aggregation systems, supports context fields like request ID and user ID, and is filterable in production without code changes. Print statements disappear in containerized environments where stdout is not captured.
- Raise `HTTPException` with detail str, not generic 500
- Custom exception handlers registered in `main.py` — not inline try/except in routes
- Log errors with structlog — no print statements

## Type Hints
Python type hints in FastAPI serve a purpose beyond documentation: FastAPI reads them at runtime to generate OpenAPI schemas, validate inputs, serialize outputs, and wire up dependency injection. Missing or incomplete type hints break these mechanisms silently — the endpoint still works but schema generation produces incomplete docs, validation is skipped, and dependency injection may fail. Full type hints on all function signatures means every parameter, every dependency, and every return type is explicitly annotated. The `Annotated[]` syntax introduced in Python 3.9 and standardized in 3.11 is the idiomatic way to attach FastAPI metadata — validators, dependencies, query parameter constraints — to a type annotation without losing the type information itself. Return type annotations on route handlers enable response model validation and ensure the serialized output matches the declared schema.
- Full type hints on all function signatures
- Use `Annotated[]` for dependency injection metadata
- Return type annotations on all route handlers

---
description: "Django 5.1+ conventions — class-based views, ORM patterns, migrations discipline"
alwaysApply: false
globs: ["**/models.py", "**/views.py", "**/serializers.py", "**/migrations/**"]
---

## ORM
Django's ORM is powerful but its default behavior — lazy evaluation and implicit related object loading — is the primary source of N+1 query bugs in Django applications. When the AI generates code that iterates over a QuerySet and accesses a related object inside the loop without explicit prefetching, each iteration triggers a separate database query. On small datasets this is invisible; on production datasets it causes severe performance degradation. The rule is simple: every access to a related object must be preceded by `select_related()` for foreign keys or `prefetch_related()` for many-to-many and reverse relations. QuerySets should be evaluated in views or serializers, not inside model methods, because model methods are called repeatedly in loops and should remain query-free. Bulk operations replace per-instance saves inside loops and reduce database round trips from N to 1.
- Use `select_related()` and `prefetch_related()` explicitly — never rely on lazy loading in loops
- QuerySets are lazy — don't evaluate in model methods, evaluate in views or serializers
- Bulk operations: use `bulk_create()` and `bulk_update()` for multi-record writes

## Migrations
Django migrations are the authoritative record of database schema history — editing a migration after it has been applied to any shared environment breaks the migration graph and can cause `migrate` to fail or silently skip changes on other developers' machines and deployment environments. Each migration should represent one logical schema change so that rollbacks are targeted and the migration history remains readable as a changelog of intentional decisions. Combined schema and data migrations are particularly dangerous because they cannot be rolled back atomically: if a data migration fails partway through, the schema change may already be applied. Reverse migrations — the `reverse_sql` or reverse `operations` list — are required for every migration so that `migrate --backwards` works predictably. Teams that skip reverse migrations accumulate technical debt that makes emergency rollbacks impossible.
- Never edit migrations after they've been applied to staging or prod
- Each migration does one logical thing — no combined schema + data migrations
- Reverse migration (`operations` list) required for every migration

## Security
Django ships with CSRF protection enabled globally by default, and this default must be preserved — disabling it per-view is a security vulnerability, not a convenience. When a view requires CSRF exemption (e.g., a webhook endpoint with its own signature verification), the exemption must be documented with a comment explaining the alternative protection mechanism. User input must flow through `ModelForm` or Django REST Framework serializers, which enforce field-level validation, type coercion, and model-level constraints before any data reaches the database or business logic layer. Raw `request.POST` access bypasses all of these protections and is a common vector for mass assignment vulnerabilities, where an attacker submits extra fields that modify sensitive model attributes the developer did not intend to expose through that endpoint.
- CSRF protection enabled globally — no per-view exemptions without comment
- User input through `ModelForm` or DRF serializer — no raw `request.POST` access

---
description: "Rule generator: create new .mdc rules when a recurring pattern or correction is identified in the current session"
alwaysApply: false
---

When you identify a pattern that has been corrected or enforced more than twice in this session:

1. Propose a new `.mdc` rule file with this structure:
   - Filename: `auto-{concern}.mdc` in `.cursor/rules/`
   - Activation: Auto Attached with appropriate glob if file-type specific, Agent Requested otherwise
   - Content: bullet points, under 200 words, most important constraint first

2. Explain why this pattern warrants a rule (recurrence count, scope, impact)

3. Ask the developer to confirm before saving the file

The "3 strikes" threshold: if the same correction appears 3 times, propose a rule automatically.