What should a CLAUDE.md for Django include?
A CLAUDE.md for Django should give Claude Code the exact manage.py commands for running, migrating and testing, describe your app layout, and state your rules for migrations, the ORM, settings and tests. Add the gotchas that are specific to your project, and keep the whole file under 200 lines, as Anthropic's memory docs recommend.
Django is a good fit for a short, strict CLAUDE.md because the framework already has strong conventions. Claude knows what a model or a view is. What it does not know is that your project uses uv, that every model change must ship with its migration, that tests touching the database must use Django's own TestCase, or which settings module production uses. Those are the lines that change its behavior.
The template below targets Django 6.1, the current release on docs.djangoproject.com, which supports Python 3.12 and newer. Commands and conventions come from the Django docs; the tooling choices (uv, Ruff, PostgreSQL) are common picks you can swap out. For the CLAUDE.md format itself, start with the CLAUDE.md guide.
The Django CLAUDE.md template
Save this as CLAUDE.md next to manage.py. Replace the angle-bracket placeholders and delete lines that do not apply.
# <Project name>
<One sentence: what this project does and who uses it.>
Stack: Django 6.1, Python 3.12+, PostgreSQL, uv. Settings package: `config/`.
## Commands
- Install: `uv sync`
- Dev server: `uv run python manage.py runserver` (http://127.0.0.1:8000)
- Make migrations: `uv run python manage.py makemigrations <app> --name <what_changed>`
- Apply migrations: `uv run python manage.py migrate`
- Check for missing migrations: `uv run python manage.py makemigrations --check`
- All tests: `uv run python manage.py test`
- One test: `uv run python manage.py test orders.tests.test_models.OrderTests.test_total`
- Reuse the test database: add `--keepdb`
- System checks: `uv run python manage.py check`
- Lint and format: `uv run ruff check .` then `uv run ruff format .`
- Shell: `uv run python manage.py shell`
- Done means: ruff, `check`, `makemigrations --check` and the tests for touched apps pass
## Project structure
- `manage.py`: entry point for every management command
- `config/`: `settings.py`, `urls.py`, `asgi.py`, `wsgi.py`
- One app per domain area: `accounts/`, `orders/`, `catalog/`
- Each app: `models.py`, `views.py`, `urls.py`, `admin.py`, `apps.py`, `migrations/`, `tests/`
- Templates: `<app>/templates/<app>/`. Static files: `<app>/static/<app>/`
- Business logic lives in `<app>/services.py`, not in views, forms or templates
## Models and migrations
- Every model change ships with its migration in the same commit
- Read the makemigrations output and open the new file before applying it
- Never edit a migration that is already pushed or applied elsewhere; write a new one
- Point foreign keys at `settings.AUTH_USER_MODEL`; in code use `get_user_model()`.
Never import `User` from `django.contrib.auth.models` directly
- Do not squash or delete migrations unless asked
## Queries, views and security
- Use the ORM. Raw SQL only when asked, always with query parameters, never string formatting
- Do not use `extra()` or `RawSQL`
- Use `select_related()` and `prefetch_related()` when a list touches related objects
- Keep CSRF protection on. Never add `@csrf_exempt` without asking
- Read settings with `from django.conf import settings`. Never change settings at runtime
- Secrets come from the environment: `SECRET_KEY = os.environ["SECRET_KEY"]`
- `DEBUG` is never True in production; `runserver` is for development only
## Testing
- Tests that use the database subclass `django.test.TestCase`, not `unittest.TestCase`
- Test files are named `test*.py` so the runner discovers them
- Tests run against a separate blank test database; never point them at real data
- View tests use `self.client`; build data in `setUpTestData`, not fixtures files
- Every bug fix comes with a test that failed before the fix
## Do not
- Do not run commands against the production database
- Do not commit `.env` files or local settings
- Do not add a third-party package without asking
- Do not put queries or business logic in templates
## Gotchas
- `DJANGO_SETTINGS_MODULE` picks the settings module; production uses `<config.settings.prod>`
- Before a deploy: `uv run python manage.py check --deploy` with production settings
- Generated migrations get formatted with black if black is on PATH; run ruff format after
- <Your project's own surprises: Celery workers, seeded data, external sandboxes>
What does each part of the template do?
Header and stack line. One sentence of purpose plus the versions tells Claude which Django APIs exist. Django 6.x requires Python 3.12 or newer, per the Django installation FAQ, so stating both avoids suggestions that do not run on your interpreter.
Commands. Every command is a standard django-admin and manage.py command, prefixed with uv run so it runs inside the project environment. Two flags do a lot of work for an agent: makemigrations --check exits with a non-zero status when model changes have no migration, and migrate --check does the same for unapplied migrations. Both turn "did I forget something?" into a command Claude can run. The single-test line uses the dotted label format from the testing overview, which accepts a module, a class or one method, so Claude can rerun only what it changed.
Project structure. The manage.py plus settings package layout matches what startproject creates in the Django tutorial, and the per-app files match startapp. The namespaced template folder (templates/<app>/) follows the tutorial's advice on template namespacing. The services.py line is a project convention, not a Django rule; keep it only if your team works that way.
Models and migrations. Django's migrations docs say migration files are designed to be committed as part of the codebase, and recommend committing the migration and the model change as a single commit. They also warn that makemigrations is "not perfect, and for complex changes it might not be detecting what you expect," which is why the template tells Claude to read the output. The user model rule comes from the auth customization docs: code that references User directly breaks in projects that set AUTH_USER_MODEL.
Queries, views and security. Django's security overview explains that querysets are protected from SQL injection through parameterization, while raw queries, extra() and RawSQL need care. The settings rules come from the settings docs, which say you shouldn't alter settings at runtime. The secret key and debug lines come from the deployment checklist, which states that you must never enable debug in production.
Testing. The most expensive Django testing mistake for an agent is using unittest.TestCase for database tests. The docs warn that their behavior then varies with test order, which produces tests that pass alone and fail in the suite. The discovery pattern and separate test database are also from the testing overview.
Gotchas. check --deploy automates part of the deployment checklist and should run against production settings. The black note comes from the django-admin reference: files created by startproject, startapp and makemigrations are formatted with black if it is on your PATH.
Which agent mistakes does the template prevent?
Each section answers a mistake that comes up when an agent works in a Django codebase:
| Without the rule | Line in the template that prevents it |
|---|---|
| A model change lands without its migration | "Every model change ships with its migration" and makemigrations --check |
| Database tests pass alone and fail in the full suite | "Tests that use the database subclass django.test.TestCase" |
| User input is formatted into a raw SQL string | "Raw SQL only when asked, always with query parameters" |
A foreign key points at auth.User in a project with a custom user model |
"Point foreign keys at settings.AUTH_USER_MODEL" |
| A list view runs one query per row | "Use select_related() and prefetch_related()" |
Use the same test for your own additions: name the mistake, then write the shortest line that prevents it.
How do you adapt it to your project?
- pip and venv instead of uv: drop the
uv runprefix and add an "activate the virtualenv first" line, or Claude will run the system Python. - Different settings package: replace
config/with the packagestartprojectcreated for you, often the project name. - Split settings: if you use
settings/base.py,dev.pyandprod.py, list them and say which one tests use. - Django REST framework or Django Ninja: add a short API section with your serializer or schema conventions and where endpoints live.
- pytest: replace the test commands with the ones you actually run. Keep the database-test rule in whatever form your plugin needs.
- App-specific rules: put them in
.claude/rules/orders.mdwithpaths: ["orders/**/*.py"]in the frontmatter so they load only when Claude touches that app.
Then start a session and run /context to confirm the file is listed under Memory files. If you have an existing project with no CLAUDE.md, /init will draft one from your code that you can merge with this template.
How do you share it with other agents through AGENTS.md?
Claude Code reads AGENTS.md on its own only when the project has no CLAUDE.md or CLAUDE.local.md, and that needs v2.1.277 or later. If your team also uses Codex or Cursor, move the template's content into AGENTS.md and make CLAUDE.md a two-part file:
@AGENTS.md
## Claude Code only
- Use plan mode before touching `payments/` or any migration
- Run `/doctor prompt-audit` after editing AGENTS.md or this file
The @AGENTS.md import expands the shared file into context first, and Claude-specific notes follow. Imports resolve relative to the file that contains them and can nest up to four hops. The AGENTS.md guide lists which tools read the file, and Claude Code memory explains how root and subfolder files combine.
How do you keep a Django CLAUDE.md from going stale?
Treat it like code. Add a line when Claude repeats a mistake, delete lines it follows without being told, and update commands when your tooling changes. /doctor prompt-audit (Claude Code v2.1.283 or later) looks for outdated or conflicting instructions and proposes edits without changing files until you agree. For rules that must never be broken, such as "never run migrate against production," a PreToolUse hook can block the command, because CLAUDE.md is guidance Claude reads, not configuration it enforces.
Python teams often reuse the same rules across services. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, so one option is to save this template there as a prompt with blanks such as {{settings_package:config}}, then fill it for each new project. Building an API instead? See the FastAPI CLAUDE.md template; for other stacks there are Next.js and Rails versions.