django-playbook

Django Playbook

This is the literal procedure a frontier model follows on a Django/DRF codebase. Follow it in order; most Django defects come from skipping the reconnaissance steps and writing "generic Django" instead of THIS project's Django.

Operating loop

1. Pin the stack before writing a line. Read the dependency file (requirements.txt, pyproject.toml, Pipfile.lock, or poetry.lock):
   • Django version: the django / Django pin. Stay inside that version's API — no Django 5.x features (GeneratedField, db_default) in a 4.2 project. Mark any version-specific advice with the version.
   • DRF version: the djangorestframework pin, if present. If DRF is not in the deps, this is a plain-Django task — do not add serializers.
   • Test runner and lint: pytest/pytest-django + a pytest.ini/[tool.pytest] → pytest; otherwise python manage.py test. ruff/flake8/black in deps + a config → part of verification.
2. Read settings.py (or the settings/ package) before touching code.
   • INSTALLED_APPS: which of your apps exist, which third-party apps are wired (rest_framework, django_filters, debug_toolbar).
   • USE_TZ: if True (set in generated settings for years; the global default flipped to True in Django 5.0), all naive datetimes are a bug — see failure catalog #6.
   • AUTH_USER_MODEL: never hard-code auth.User; reference settings.AUTH_USER_MODEL in FKs and get_user_model() in code.
   • REST_FRAMEWORK: default permission/auth/pagination classes — they change what an omitted permission_classes actually does.
3. Detect the project's layout and MIRROR it, don't impose. Read one neighboring app's models.py, views.py, serializers.py, urls.py:
   • Fat models (logic on models/managers) vs a services.py/selectors.py split — match whichever this repo already uses (decision tree c).
   • App structure (apps/<name>/ vs flat), CBV vs FBV, viewsets+routers vs APIView. Convention in THIS repo beats convention in general.
4. Run python manage.py check early — before and after your change. It catches app-config, model, and admin errors that tests lazy-load past.
5. Build in this order: model (fields, on_delete, Meta.indexes, Meta.constraints) → makemigrations → manager/service → view → serializer → url wiring. Each layer is testable before the next exists.
6. Migration discipline:
   • One migration = schema change OR data change, never both.
   • After ANY model change, run makemigrations and read the generated file. A model edit without a migration is a runtime error waiting for deploy.
   • Data migrations use RunPython with a real reverse function (RunPython.noop only when truly irreversible — say so in a comment) and the historical model via apps.get_model('app', 'Model'), never the imported app.models class (it drifts).
7. Run the verification recipe (below) and paste real output before reporting. A diff without executed commands is a claim, not a result.