Home › Django › Django CLAUDE.md

Django CLAUDE.md

CLAUDE.md for Django 5 projects with DRF, pytest-django and PostgreSQL.

Claude Code (CLAUDE.md)Django

How to use

Save this as CLAUDE.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# CLAUDE.md — Django

## Commands
- Run: `uv run python manage.py runserver` · Tests: `uv run pytest` · Lint: `uv run ruff check . && uv run ruff format --check .`
- Migrations: `uv run python manage.py makemigrations <app>` then review the generated file before `migrate`.

## Conventions
- One Django app per bounded domain under `apps/`. Business logic in `services.py`/`selectors.py`, not in views or serializers.
- Fat models are fine for invariants; complex workflows go in services.
- DRF: explicit serializers with `fields = [...]` (never `"__all__"`), permission classes on every view.
- Query hygiene: `select_related`/`prefetch_related` for relations; check with `django-debug-toolbar` or `assertNumQueries` in tests.
- Settings split: `config/settings/{base,dev,prod}.py`; secrets from environment via `django-environ`.
- Never edit an applied migration; add a new one. Data migrations use `RunPython` with a reverse function.

## Don't
- Don't use raw SQL without parameters. Don't disable CSRF. Don't put logic in signals unless decoupling is required.