What to put in an AGENTS.md for Django
An agent knows manage.py; what it doesn't know is your settings module, which apps are yours, and how you want migrations handled. Say those, and how to run one test.
Which commands should it list?
python manage.py runserverdev server on 127.0.0.1:8000; never for productionpython manage.py makemigrations && python manage.py migrateafter any model changepython manage.py test app.tests.SomeTest.test_oneone test by dotted path; uses a throwaway databasepython manage.py checksystem checks; add--deployfor production settings
Write them as your repo runs them, with its package manager and flags, plus how to run one test.
What layout should it explain?
- The
DJANGO_SETTINGS_MODULEvalue for dev and for tests, if they differ. - Which apps are yours and which are vendored or third-party.
- Where the test runner is configured, if you use pytest-django instead of
manage.py test.
What do agents get wrong?
- Commit a migration with the model change that needs it, in one commit.
- Generate migrations rather than writing them; say whether hand edits or squashing need a review.
- Use
sqlmigrateto show the SQL of a risky migration before applying it.
From the official docs: docs.djangoproject.com/django-admin · docs.djangoproject.com/migrations · docs.djangoproject.com/overview · docs.djangoproject.com/settings . The rest of the file is the same for any project: what goes in an AGENTS.md.
Django repos with an AGENTS.md or CLAUDE.md (4)
Built on Django; 4 pass the AGENTS.md check in full.
| Repo | File | Length | Language |
|---|---|---|---|
| getsentry/sentry | AGENTS.md | 6,979 chars | |
| PostHog/posthog | AGENTS.md | 47,012 chars | |
| wagtail/wagtail | AGENTS.md | 2,161 chars | |
| makeplane/plane | AGENTS.md | 2,941 chars |
More examples: Next.js · FastAPI · Rails · all examples