django

Django Cursor Rules

You are an expert Django developer (v4.2+/v5+). Follow these rules:

Structure

• App-based architecture — each app is independently testable and has a clear domain boundary
• Thin views — business logic belongs in service functions or model methods, not in view code. Views handle HTTP concerns only: parse request, call service, return response
• CBVs (Class-Based Views) for standard CRUD patterns, FBVs (Function-Based Views) for custom logic that doesn't fit CRUD
• Separate settings: base.py → development.py / production.py that import from base. Never put secrets in settings files — use environ or django-environ
• URL patterns: use path() with named URLs everywhere. reverse('app:name') in code, {% url 'app:name' %} in templates — never hardcode URLs

Models

• db_index=True on fields you filter, order, or join on frequently. Missing indexes are the #1 performance issue in Django apps
• CharField with TextChoices enum, not raw strings — catches typos at the Python level and gives you .label for display
• Override __str__ on every model — admin, shell, and logging become usable. UUIDField for public-facing IDs, auto-increment pk stays internal
• Always create data migrations when schema changes need data transformations — RunPython in migrations, not management commands that may not run
• constraints in Meta for database-level validation: UniqueConstraint, CheckConstraint — model-level unique_together is legacy, use Meta.constraints
• Set default_auto_field = 'django.db.models.BigAutoField' in settings — the default AutoField maxes out at ~2.1B rows

QuerySets

• select_related() for ForeignKey/OneToOne (SQL JOIN). prefetch_related() for ManyToMany and reverse FKs (separate query). Forgetting these is the N+1 problem
• F() for database-level field references (avoids race conditions in updates). Q() for complex OR/NOT filters
• .exists() not len(qs) > 0 (stops at first row). .count() not len(qs) (SQL COUNT vs loading all objects into memory)
• .only() / .defer() for models with large text/JSON fields you don't need — but accessing a deferred field triggers another query, so be deliberate
• .iterator() for processing large querysets — without it, Django caches the entire result set in memory
• Never evaluate querysets in loops that trigger more queries: for obj in queryset: obj.related.name is N+1. Profile with django-debug-toolbar or nplusone