Claude Code Django: practical setup and workflows

This guide explains how to use Claude Code effectively on a Django project: what to put in CLAUDE.md, how to structure a working loop, where Django-specific pitfalls hide, and how to run several agents when one is not enough. Claude Code (started with claude in the project folder) works well with Django’s explicit files, ORM, and testable boundaries, but it needs a project-specific contract to avoid migration and ORM mistakes.

Why Django’s structure makes Claude Code effective

Django projects reward structure and punish hidden side effects. Claude Code can read the project layout, trace URL confs to views, inspect models, and write tests against pytest-django. The agent is strongest on tasks that have a clear local scope: adding a model and migration, implementing a serializer and viewset, optimizing a queryset, or extending an admin. Because Django separates models, views, templates, and serializers, prompts can point at one layer without the agent rewriting the whole app. The main risk is not code syntax but state: database schema, migrations, and querysets. That is why the CLAUDE.md and the loop below matter more than a clever prompt.

Give the agent a project contract: CLAUDE.md for Django

The highest-leverage file is CLAUDE.md at the repo root. Claude Code reads it at the start of a session, so it should contain the commands the agent is allowed to run, the folder conventions, and rules that prevent common Django mistakes. Keep it short enough to be read every time, but explicit about migrations and tests.

# CLAUDE.md

## Commands
- Install: `uv sync`
- Run server: `python manage.py runserver`
- Run tests: `pytest`
- Run a single test: `pytest apps/orders/tests/test_views.py -k test_order_total`
- Lint: `ruff check .`
- Format check: `ruff format --check .`
- Check Django config: `python manage.py check`
- Make migrations: `python manage.py makemigrations`
- Check missing migrations: `python manage.py makemigrations --check --dry-run`
- Apply migrations: `python manage.py migrate`

## Layout
- Project settings live in `config/settings/` with `base.py`, `dev.py`, `test.py`, and `prod.py`.
- Reusable apps live in `apps/<app_name>/`; each app has `models.py`, `views.py`, `serializers.py` if it exposes an API, `admin.py`, and a `tests/` directory.
- Business logic goes in `services.py` or model methods, not in views or serializers.

## Django rules
- Never edit an existing migration file. Always create a new migration with `makemigrations` and review the generated diff.
- Run migrations only against local or test databases, never against production.
- Use explicit `select_related` and `prefetch_related` for querysets used in list views or serializers.
- For DRF, keep serializers in the app’s `serializers.py` and use `ModelSerializer` by default; switch to `Serializer` only when the API shape differs from the model.
- Prefer `pytest` with pytest-django; use `django_assert_num_queries` or `assertNumQueries` whenever query count matters.
- After any model or migration change, run `pytest` and `python manage.py makemigrations --check --dry-run`.

Beyond CLAUDE.md, these files give the agent enough context to stay consistent:

If the project has multiple settings modules, tell the agent which one pytest-django should use; the default DJANGO_SETTINGS_MODULE can otherwise point at the wrong environment.

The plan-small-test-review loop for Django changes

The most reliable workflow is the same one you would use with a human teammate: plan, make a small change, run the fast tests, review the diff, then repeat. Do not ask for a large feature in one prompt and then run the entire test suite at the end. Start most tasks in plan mode so the agent proposes file edits and migration steps before touching code. The Claude Code best practices checklist applies directly here: small diffs are easier to review, and a failing test tells you immediately whether an ORM or settings change is wrong.

Example prompts for typical Django tasks:

• “Add a Book model with a title, a foreign key to Author, a published_date, and a unique isbn. Create the migration, register the model in admin, and add a basic test that creates and retrieves a book.”
• “Write a DRF ModelViewSet and ModelSerializer for Book with list, create, and retrieve. Add pytest-django tests for filtering by author and for the response fields.”
• “The dashboard view has an N+1 query. Rewrite the queryset with select_related and prefetch_related as needed, add a test with django_assert_num_queries, and run the dashboard app tests.”
• “Change User.email to be unique and case-insensitive. Add a data migration for existing duplicates, write a test for the migration, and explain the rollback plan before running it.”
• “Split the order total calculation out of the view into a model method, update the template, and run the relevant pytest file. Show me the git diff after the tests pass.”

After each prompt, ask the agent to run the specific test file rather than the full suite until the change is stable. Then run python manage.py check and python manage.py makemigrations --check --dry-run before final review. Review the diff yourself, especially migration files and settings changes.

Delegate models and DRF; inspect migrations and querysets

Tasks that fit the agent well:

• Adding models, fields, and migrations, plus admin registration.
• Building DRF serializers, viewsets, routers, and permission classes.
• Writing form or serializer validation and unit tests.
• Optimizing querysets with select_related and prefetch_related.
• Extending class-based views and template context.

Pitfalls to watch closely:

• Generated migrations: Claude Code can produce an AlterField or a rename when you expected a simple add. Always open the migration file and ask the agent to explain every operation. Run makemigrations --check --dry-run after the fact.
• Settings changes: The agent may make a change to a settings file that affects local only or all environments. Keep settings split and ask for a diff of any settings edit.
• Circular imports: Django apps can import models from each other in ways that break app loading. Keep app dependencies one-way, and if the agent adds a cross-app import, run python manage.py check immediately.
• Lazy querysets: The agent may return a queryset from a view or serializer without evaluating it at the right time. A test that asserts the number of queries, such as django_assert_num_queries, catches this.
• DRF contract drift: A serializer can expose fields the client didn’t expect, or a permission class can block a legitimate request. Ask for tests that cover the API response body and status codes.
• Templates and escaping: Django templates autoescape by default; if the agent uses safe or mark_safe, ask why and require a test. Avoid introducing arbitrary JavaScript in template filters.

Testing Django changes with pytest-django

Make pytest-django the single source of truth. The agent should run pytest after every small change, but you can keep the loop fast by pointing it at a single module: pytest apps/orders/tests/test_views.py. Use -k to select one test while iterating. For DRF work, use APIClient or APITestCase so the agent verifies the HTTP layer, not just serializers in isolation. When a change touches the ORM, ask for a test that asserts query counts with django_assert_num_queries or Django’s assertNumQueries. This is the only reliable way to catch an accidental N+1 in a view that still returns the right JSON.

Before a task is complete, ask the agent to run:

• pytest for the affected app or the full suite if the change is cross-cutting.
• python manage.py check for system checks.
• python manage.py makemigrations --check --dry-run to catch missing migrations.

Then review git diff yourself. For model and migration changes, read the generated migration file line by line. The agent can summarize the diff, but the final call on schema changes is yours.

Parallel Django work with AgentVera

For larger Django efforts, AgentVera runs several Claude Code sessions in parallel, each in its own git worktree, so model or serializer changes don’t overwrite each other. When a turn ends, a second model reviews the diff with file:line findings, which catches N+1 queries and serializer mistakes. Checkpoints let you undo a bad migration in one click, and token budgets stop a runaway agent from burning a whole day on one stuck task. See how to run multiple Claude Code agents.

Conclusion: keep Django safe with Claude Code

Claude Code becomes much more useful on Django when you treat it like a sharp junior developer with fast fingers: give it a precise CLAUDE.md, keep tasks small, run the test suite after every step, and inspect every migration. The same discipline scales to multiple agents with separate worktrees and code review. With that setup, you can use Claude Code for the repetitive parts of Django development while keeping the database schema and API contract under your control.