Cursor Agent Django: practical guide for Django developers

Cursor Agent is a terminal coding agent that can work inside an existing Django project. Run it from the project root with cursor-agent. This guide covers setup with AGENTS.md, a safe edit-test loop, Django-specific pitfalls, and verification with pytest-django.

Why Cursor Agent suits Django work

Cursor Agent suits Django work because Django has strong conventional boundaries. Apps, models, managers, querysets, forms, serializers, URLs, and templates all have predictable homes. Once those conventions are written into AGENTS.md or .cursor/rules, the agent can make multi-file changes consistently: adding a model, updating a serializer, registering a route, and editing a template in one pass. It can also run Django management commands and pytest, which closes the loop between code generation and verification. The key is not to treat it as an autopilot, but as a fast junior engineer who needs explicit commands.

Setting up a Django project for the agent

Before starting, commit a clean state and add project instructions to AGENTS.md or .cursor/rules. The agent reads these at the start of a session. Keep the file short and actionable. Include the exact commands for install, runserver, tests, lint, and migrations. Then add folder conventions and Django-specific rules. A realistic AGENTS.md for a Django REST framework project looks like this:

# AGENTS.md

## Commands
- Install: uv sync
- Run server: python manage.py runserver
- Test: pytest -q
- Test one file: pytest apps/orders/tests/test_views.py
- Lint: ruff check . && ruff format --check .
- Make migrations: python manage.py makemigrations
- Apply migrations: python manage.py migrate
- Django system check: python manage.py check

## Folder conventions
- Project settings live in `config/`, apps in `apps/<app>/`.
- Models belong in `apps/<app>/models.py`.
- DRF serializers and views live in `apps/<app>/api/`.
- Templates live in `apps/<app>/templates/<app>/`.

## Django rules
- Use `django.contrib.auth.get_user_model()` instead of importing User.
- Prefer DRF ViewSets with explicit serializer classes.
- After model changes, run `makemigrations --dry-run` and show the diff.
- Never edit files in `*/migrations/` by hand.
- Use `select_related` and `prefetch_related` to avoid N+1 queries.
- Add or update pytest-django tests for every behavior change.

If you are moving from the Cursor IDE to the terminal, see How to use Cursor CLI: a step-by-step guide. Put this file at the repository root. Do not hide local settings inside it; store secrets in environment variables.

A working loop for Django changes

Use a short loop: plan, implement, verify, review. Start each task on a new git branch. Ask Cursor Agent to read the relevant files first and list the changes it will make. Then let it edit, but require it to run the test command and Django checks before considering the task done. After the agent finishes, review git diff yourself, especially models, settings, and migrations. Example prompts for typical Django work:

• In apps/inventory/models.py, add a stock PositiveIntegerField to the Product model. Update the admin, serializer, and test fixture. Run python manage.py makemigrations and show the generated migration before applying it.
• Refactor apps/orders/views.py to remove an N+1 in OrderViewSet.list. Use select_related('customer') and prefetch_related('line_items__product'). Show the query count before and after with pytest-django.
• Add a pytest-django test for the password reset flow in apps/accounts/api.py: POST to the endpoint, assert an email is sent, and verify the token works once.
• In templates/registration/login.html, replace the hardcoded form with Django form rendering and keep the CSRF token. Make sure field errors appear per field.
• Upgrade the project from Django 4.2 to 5.0. First list every file that uses removed settings or imports, then update them and run the full test suite.

After each prompt, run pytest -q and python manage.py check yourself if the agent did not. For ORM changes, use django_assert_num_queries in tests to catch regressions.

Where Cursor Agent shines and where to watch closely

Cursor Agent handles routine Django tasks well when patterns already exist: adding a new model plus admin, serializer, and view; writing tests with pytest-django fixtures; refactoring querysets; fixing lint errors. It also does well with template changes when told to use Django template tags and form rendering. The places to watch closely are migrations, settings, ORM performance, and DRF serializer depth. The table lists concrete pitfalls.

| Area | What the agent does well | Where to watch closely | | Models and migrations | Adds fields, creates migrations with manage.py | May edit migration files by hand or generate wrong dependencies; inspect every migration | | Settings | Updates INSTALLED_APPS when adding apps | May put local or test settings into base settings.py; require separate settings modules | | ORM | Refactors views to reduce queries | May still produce N+1 or use objects.all() without filtering; require select_related/prefetch_related | | Django REST framework | Creates serializers and ViewSets quickly | May set depth=1 and expose too much or miss queryset optimization; review serializer fields | | Templates | Uses Django form rendering when instructed | May add raw HTML or ignore template inheritance; require {% csrf_token %} and {{ form.field.errors }} |

The agent can also miss app label namespacing in templates or reverse URL names. Always ask for python manage.py check after template changes.

Testing and verification with Cursor Agent

Testing is where Cursor Agent earns its keep if you configure pytest-django correctly. Put DJANGO_SETTINGS_MODULE in pytest.ini, and tell the agent to use fixtures like db, client, django_user_model, and settings instead of manual database setup. For speed, use pytest -q --reuse-db in local runs, but disable reuse in CI to avoid stale schemas. For DRF, use APIClient and force authentication with client.force_authenticate(user=user). For query count assertions, use django_assert_num_queries in tests. After each task, run pytest -q, python manage.py check, and python manage.py makemigrations --check --dry-run to catch missing migrations. If the agent changes a model, ask for the migration file path and include it in the diff review. Use python manage.py migrate --plan to preview applied migrations. Lint with ruff as defined in AGENTS.md.

Running several agents on one Django project with AgentVera

AgentVera is a desktop app that runs Cursor Agent and other coding agents side by side in one window. For Django work the most useful parts are parallel git worktrees, so each agent edits its own branch without clobbering another agent’s migrations or settings; automatic code review after each turn, which catches broken imports or missing migration entries; checkpoints for undoing a bad migration or view change; and token budgets so long pytest and makemigrations loops do not exhaust your plan. This matters because Django codebases often have many independent apps, and several agents can work on separate apps at once if their work is isolated.

Wrap-up

Cursor Agent is a practical addition to Django development when the project gives it clear commands and verification guardrails. Keep tasks small, review every migration, and run the test suite often. For a broader safe workflow, see How to vibe code safely: a practical workflow. With those habits, Cursor Agent can handle much of the routine model, view, serializer, and template work.