Cursor Rules for Django: Models, Views, and Tests

Cursor rules for a Django project tell the assistant how your app is organized, how to use the ORM correctly for your setup, how migrations are managed, how settings are structured, and which test command to run. Django has strong conventions, but every project adds its own decisions on top: a custom user model, a specific settings module structure, a preferred way to write views, or a migration policy that differs from the default. Without rules, the assistant follows generic Django patterns that may not fit your project. fenbs helps teams keep the project decisions and recurring lessons behind their Django conventions in one place, so every connected assistant starts from the same approved foundation.

The templates below are starting points. Replace app names, settings paths, and test runner details with your actual project values. Test each rule on a real file before using it, and remove any rule that contradicts how your project actually works.

App structure and responsibility

Django projects that have grown large benefit from a rule that names the apps and their responsibilities. An assistant that puts authentication logic in the products app, or a model query in a view that should use a service layer, creates a structure that is hard to maintain. A short structure rule prevents the most common mistakes.

Django apps in this project:
- accounts: custom user model, registration, authentication
- products: product catalog, categories
- orders: order creation, status, history
- api: REST API views and serializers (DRF)

Business logic goes in services.py within each app, not in views or models.
Views call service functions; they do not query the ORM directly.
Do not add Django admin registration without a corresponding admin.py entry.

ORM and query rules

Django's ORM makes it easy to write queries anywhere, including in templates and serializers, which leads to N+1 query patterns and untestable code. A rule that names where queries should live and which patterns to use prevents the most expensive mistakes.

ORM usage:
- Queries go in services.py or in a dedicated queries.py file per app
- Do not write ORM queries in views, serializers, or templates
- Use select_related() and prefetch_related() for related objects — do not loop
  over related objects without prefetching
- Use .only() or .values() when you do not need the full model instance
- Never use filter().update() without confirming the queryset scope

Migrations

Django migrations are easy to get wrong in a team environment: two developers create migrations with the same number, a migration references a model before it exists, or someone edits a migration that is already in production. A rule about migration conventions prevents the most common problems.

Migrations:
- Generate with: python manage.py makemigrations
- Do not edit an existing migration after it has been applied in production
- Do not squash migrations without team agreement
- Data migrations go in separate migration files (RunPython)
  Label them with _data suffix for clarity
- Check for migration conflicts before merging a branch: python manage.py migrate --check

Settings management

Django settings for a project that runs in multiple environments are typically split into a base settings file and environment-specific overrides. An assistant that adds a secret key or a database URL directly to settings.py rather than reading it from the environment creates a security problem. A rule that names your settings structure prevents this.

Settings:
- config/settings/base.py: shared settings
- config/settings/local.py: local development (not in version control)
- config/settings/production.py: production (imports from base)

Do not hardcode SECRET_KEY, DATABASE_URL, or any credential in a settings file.
Read secrets from environment variables using os.environ or django-environ.
SECRET_KEY must come from the environment, never from a default.

Testing conventions

Django projects can use the built-in test runner or pytest with pytest-django. A rule that names your actual setup, where test files live, and what command to run keeps new tests consistent with existing ones.

Tests:
- Framework: pytest with pytest-django
- Test files: tests/ directory within each app, named test_*.py
- Use pytest fixtures in conftest.py; do not use setUp/tearDown unless inheriting
  from existing TestCase classes
- Factory Boy for test data (factories.py per app)
- Run: pytest from the project root
- Run with coverage: pytest --cov=. --cov-report=term

How to do this with fenbs

1. Create a free account and add a project for your Django application.
2. Add a skill or prompt for each rule area: app structure, ORM usage, migrations, settings, and tests.
3. For any rule that came from a recurring mistake — an N+1 query pattern that was found in production, a migration conflict that caused a deployment rollback — record the lesson in fenbs: what happened, what the correct approach is, what to watch for next time.
4. Record the decisions behind non-obvious conventions in Decisions and rules: why the project uses a services.py layer, why migrations are not squashed, which settings structure is approved.
5. Connect your AI tools from Integrations so they read both the rules and the lessons before starting work on the project.

What rules cannot cover in a Django project

Rules describe coding conventions. They do not cover which features are in scope for a sprint, which API endpoints are approved, or the business logic behind a specific model field. That context belongs in your project and task notes in fenbs. When an assistant needs to understand why a model has a specific field or why a view returns a particular response format, the answer is in the project notes, not in a rule file.

fenbs does not run Django management commands or interact with the database. After the assistant makes changes, run python manage.py check and your test suite to verify the result. The cursor rules hierarchy article explains how to scope Django rules to specific apps if your project has apps with different conventions.

When the project upgrades Django — from 4.x to 5.x, for example — review the rule files for references to deprecated or removed features. The Django release notes list deprecated patterns explicitly. Rules that reference a deprecated template tag, a removed middleware, or an old signal handler will mislead the assistant instead of guiding it. A brief review at upgrade time keeps the rules accurate.

Django REST Framework adds its own conventions — serializer style, viewset routing, permission classes — that merit a separate rule file if the project has a significant API surface. Scoping that rule to api/**/*.py prevents the DRF-specific guidance from appearing when the assistant is working on admin views or management commands. See cursor rules globs for how to write that scope.

If the project uses Celery for background tasks, a short rule naming the task modules and the preferred patterns — which tasks are idempotent, how they handle retries — prevents the assistant from generating tasks that conflict with the project's reliability requirements. Background tasks interact with the database and the same ORM rules apply: keep queries out of the task function itself and delegate to service functions where the logic can be tested independently.