Systematic Guide: Context Engineering with Cursor AI and MDC Directives
Why unconstrained LLMs produce architectural drift and how to establish repository guardrails.
The Problem with Default AI Completions
Large language models are trained on historical code datasets spanning decades. As a result, when an engineer prompts Cursor without explicit rules, the assistant frequently outputs deprecated patterns:
- Suggesting Next.js Pages router idioms (
getStaticProps) inside modern App Router applications. - Generating legacy Pydantic v1 methods (
dict()) in modern FastAPI Python 3.12 services. - Introducing
anytypes and suppressive comments to bypass strict compiler checks.
MDC Architecture: Targeted Subtree Directives
Cursor's new .cursor/rules/*.mdc format enables granular glob matching. For example, a rule targeting app/**/*.tsx enforces React Server Component conventions, while a rule matching app/api/**/*.ts enforces strict runtime Zod validation and rate limiting.
Frequently Asked Questions
What is the difference between legacy .cursorrules and modern .cursor/rules/*.mdc files?
Legacy .cursorrules is a single markdown file placed in the repository root that applies globally to all files. Modern Cursor versions (2024+) support modular .cursor/rules/*.mdc files featuring YAML frontmatter with 'globs' matching specific subtrees, allowing specialized rules for frontend versus backend directories.
How do strict .cursorrules improve Cursor AI code generation?
Without explicit system guidelines, LLMs default to generic patterns, frequently generating deprecated syntax (e.g. Next.js Pages router, Pydantic v1), introducing 'any' types, and injecting noisy console.logs. Tailored rules constrain LLM outputs to modern architectural idioms.
Can I use these rules in Windsurf, Claude Code, or GitHub Copilot?
Yes! While formatted specifically for Cursor IDE's rule engine, the underlying directives can be used as system prompts in CLAUDE.md, GitHub Copilot instructions (.github/copilot-instructions.md), or Windsurf rules.