Quick Start (Production Root .cursorrules Template)

Drop this battle-tested .cursorrules file into the root of your project to immediately eliminate AI laziness, prevent fake package hallucinations, and stop the model from leaving unfinished // TODO blocks:

# Autonomous AI Coding Assistant Directives

You are an expert senior software engineer. Strictly adhere to these rules across all suggestions, diffs, and terminal commands:

## 1. Code Integrity & Completeness
- NEVER output placeholder comments like "// ... rest of code unchanged" or "// TODO: implement later". Output fully functional, complete snippets.
- Do NOT delete existing comments, docstrings, or type definitions unless explicitly instructed.
- When modifying an existing function, preserve unaffected parameters, interfaces, and error handling.

## 2. Dependencies & Framework Standards
- Do NOT invent or import third-party packages that are not listed in package.json or pyproject.toml without asking first.
- Prefer built-in language primitives and standard library tools before introducing new dependencies.
- Use explicit type annotations everywhere (no `any` in TypeScript, no bare `except:` in Python).

## 3. Terminal & Execution Safety
- Run non-destructive commands automatically (tests, builds, linters).
- NEVER execute destructive commands (`rm -rf`, `git reset --hard`, `DROP TABLE`) without explicit user confirmation.
- Format all terminal commands to run in non-interactive, headless modes (e.g., pass `-y` or `--non-interactive`).

---

1. Root .cursorrules vs Modern Scoped .cursor/rules/*.mdc

Cursor updated its rule system to support modular, glob-scoped rule files located under .cursor/rules/. Instead of stuffing 2,000 tokens of rules into a single root file that consumes context on every query, scoped rules activate only when relevant files are edited:

Feature	Legacy Root .cursorrules	Modern Scoped .cursor/rules/*.mdc
File Location	/.cursorrules	/.cursor/rules/<name>.mdc
Trigger Mechanism	Always loaded on every prompt	Loaded only when matching glob patterns
Token Efficiency	Low (Consumes 500–2,000 tokens constantly)	High (Loaded selectively per active file)
Team Organization	Monolithic single file	Modular files per tech stack (frontend, backend, db)

---

2. Production Scoped Rule Templates

Template A: Strict TypeScript & React (.cursor/rules/typescript.mdc)

Apply to files matching: **/*.{ts,tsx}

---
description: Strict TypeScript and modern React engineering standards
globs: **/*.{ts,tsx}
---

# TypeScript & React Rules

- Always enable and write code adhering to `strict: true`.
- Never use `any`. Use `unknown` with type narrowing or generic constraints.
- Prefer `type` over `interface` for union types and primitive aliases; prefer `interface` for extensible object contracts.
- React components:
  - Write pure functional components with explicit Props typing (`interface Props { ... }`).
  - Do not use `useEffect` for data synchronization that can be computed during render.
  - Wrap database or external network calls in React Server Components or dedicated server actions.

---

Template B: Modern Python & FastAPI (.cursor/rules/python.mdc)

Apply to files matching: **/*.py

---
description: Modern Python 3.12+ and FastAPI architecture rules
globs: **/*.py
---

# Python Engineering Rules

- Target Python 3.12+ syntax (use native `list[str]`, `dict[str, int]`, and `T | None` instead of `typing.Union`).
- Enforce strict typing with Pydantic v2 `BaseModel` for all request/response schemas.
- Async by default: Use `async def` for I/O-bound route handlers; use standard `def` for CPU-bound utility functions.
- Never catch bare `Exception` unless re-raising; catch specific error classes (`KeyError`, `ValueError`, `httpx.HTTPStatusError`).

---

3. Anti-Hallucination Checklist

Add these five defensive constraints to your prompt files to guard against model regressions:

1. Verify Before Suggesting: Require the model to run git status or grep existing files before assuming a file or directory does not exist.
2. Deterministic Imports: Instruct the model to inspect existing source files to determine whether your codebase uses ES Module syntax (import) or CommonJS (require).
3. No Phantom APIs: Force the model to query local docstrings or package versions rather than guessing deprecated method names from older framework versions.
4. Clean Diffs: Mandate that diffs modify only contiguous blocks rather than scattering small whitespace changes across entire files.
5. Linting Verification: Instruct the assistant to run npm run lint or ruff check . immediately after applying edits.

---

Summary Reference

• Use root .cursorrules for repository-wide behavior (terminal safety, communication style, git workflow).
• Migrate framework-specific guidelines into .cursor/rules/<tech>.mdc with targeted globs to save context window tokens.
• Explicit negative constraints (“NEVER do X”) are significantly more reliable at stopping AI regressions than positive suggestions.