Django Apps skill for Codex

Done well means: data rules live in the database (constraints) and in model methods, not scattered through views; migrations are reviewed SQL, not autogenerated surprises; settings come from the environment and pass check --deploy; the admin stays usable at a million rows; and every change ships with tests.

Inspect first

• Read AGENTS.md, then pyproject.toml/requirements*.txt for the Django version and tooling (pytest-django or manage.py test, ruff, mypy with django-stubs).
• Find settings: rg -n "DJANGO_SETTINGS_MODULE" . and read the settings module(s).
• Check AUTH_USER_MODEL. If it is unset on a project with production data, changing it later is a multi-step data migration: flag it, do not attempt it casually.
• python manage.py showmigrations | rg "\[ \]" to see unapplied migrations before adding new ones.

Project layout

config/
  settings.py        # one module, values from env (or base/dev/prod if the repo already splits)
  urls.py
  asgi.py / wsgi.py
apps/
  accounts/          # custom User lives here
  orders/
    models.py
    services.py      # multi-model writes, transactions, side effects
    selectors.py     # read queries reused by views/APIs (optional convention)
    views.py
    forms.py
    admin.py
    urls.py
    tests/
manage.py

Split an app when it has its own models and could be described in one sentence; do not create one app per model. Cross-app imports should flow one way; circular imports between models.py files signal a wrong boundary (use string references "orders.Order" in relations when needed).

New project checklist

- [ ] Custom user model before the first migrate: class User(AbstractUser) + AUTH_USER_MODEL
- [ ] Settings read from environment; SECRET_KEY, DEBUG, ALLOWED_HOSTS, DATABASES from env
- [ ] DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField" (the default from Django 6.0)
- [ ] PostgreSQL in dev and CI, not SQLite, if production is PostgreSQL
- [ ] pytest-django or the test runner wired into CI
- [ ] Static files: STORAGES + WhiteNoise or object storage
- [ ] python manage.py check --deploy passes with production settings

Models

from django.db import models
from django.db.models import Q, F

class Order(models.Model):
    class Status(models.TextChoices):
        PENDING = "pending"
        PAID = "paid"
        CANCELLED = "cancelled"

    customer = models.ForeignKey("accounts.User", on_delete=models.PROTECT, related_name="orders")
    status = models.CharField(max_length=16, choices=Status, default=Status.PENDING)
    total_cents = models.PositiveIntegerField()
    discount_cents = models.PositiveIntegerField(default=0)
    external_ref = models.CharField(max_length=64, blank=True)
    created_at = models.DateTimeField(auto_now_add=True, db_index=True)

    class Meta:
        constraints = [
            models.CheckConstraint(condition=Q(discount_cents__lte=F("total_cents")), name="order_discount_lte_total"),
            models.UniqueConstraint(fields=["external_ref"], condition=~Q(external_ref=""), name="order_external_ref_uniq"),
        ]
        indexes = [models.Index(fields=["customer", "-created_at"])]

    def cancel(self) -> None:
        if self.status == self.Status.PAID:
            raise ValueError("paid orders must be refunded, not cancelled")
        self.status = self.Status.CANCELLED
        self.save(update_fields=["status"])

• Money in integer cents or DecimalField, never FloatField.
• on_delete: PROTECT for business records, CASCADE for owned children, SET_NULL only with null=True and a reason.
• Use CheckConstraint(condition=...); the old check= keyword is deprecated since 5.1.
• save(update_fields=[...]) avoids overwriting concurrent changes to other columns.
• Use UniqueConstraint, not unique_together (legacy).

Migrations

python manage.py makemigrations orders
python manage.py sqlmigrate orders 0007       # read the SQL before applying
python manage.py migrate
python manage.py makemigrations --check --dry-run   # in CI: fails if models and migrations drift

• Review every generated migration: renames detected as drop + add lose data.
• Large tables: adding an index on PostgreSQL should use AddIndexConcurrently in a migration with atomic = False. For column changes under load, follow $zero-downtime-migrations.
• Data migrations use apps.get_model(), never direct model imports, and provide a reverse_code (or migrations.RunPython.noop with a comment why).
• Never edit a migration that has run in any shared environment; add a new one.
• Squash only when the team agrees; squashing touches every environment’s history.

Views and forms

• Function views for one-off logic, generic class-based views for standard CRUD; follow whatever the codebase already does.
• Validate input with forms (ModelForm with an explicit fields list, never exclude or "__all__", which expose new fields automatically).
• Put multi-model writes in a service function wrapped in transaction.atomic(), and trigger emails, webhooks or task enqueues with transaction.on_commit(...) so they never fire for a rolled-back transaction.
• Scope querysets to the user: Order.objects.filter(customer=request.user) then get_object_or_404(qs, pk=pk). Fetching by pk alone is an IDOR.
• For JSON APIs, use $django-rest-framework.

Admin that scales

@admin.register(Order)
class OrderAdmin(admin.ModelAdmin):
    list_display = ["id", "customer", "status", "total_cents", "created_at"]
    list_filter = ["status", ("created_at", admin.DateFieldListFilter)]
    search_fields = ["=id", "external_ref", "customer__email"]
    list_select_related = ["customer"]
    autocomplete_fields = ["customer"]          # requires search_fields on UserAdmin
    readonly_fields = ["created_at"]
    date_hierarchy = "created_at"
    show_full_result_count = False              # avoids COUNT(*) per page on big tables
    list_per_page = 50

Foreign keys in forms render every row as a <select> option; use autocomplete_fields or raw_id_fields for any relation with more than a few hundred rows. Admin actions that modify many rows should ask for confirmation through an intermediate page.

Settings

Read the production checklist in references/production-settings.md when touching settings, deploying, or when check --deploy reports warnings.

Background work

Django 6.0 ships a tasks API (django.tasks, @task and .enqueue()), but its built-in backends only run tasks immediately or not at all; production needs a worker backend from a third-party package. Celery, Dramatiq, RQ or django-q2 remain the common choices; see $background-jobs. Enqueue inside transaction.on_commit.

Testing

• pytest-django with @pytest.mark.django_db, or django.test.TestCase (wraps each test in a transaction). Use factories (factory_boy) over fixtures files.
• Test model constraints by asserting IntegrityError inside transaction.atomic().
• Assert query counts on hot views: django_assert_num_queries (pytest-django) or self.assertNumQueries(n). For N+1 fixes use $django-orm-performance.
• TestCase.captureOnCommitCallbacks(execute=True) to test on_commit side effects.

Upgrading Django

1. Run tests with python -Wa manage.py test (or -W error::DeprecationWarning in pytest) on the current version and fix deprecations first.
2. Upgrade one feature release at a time (5.2 to 6.0, not 4.2 to 6.0 in one jump).
3. Read the release notes’ “Backwards incompatible changes” section for each step; Django 6.0 requires Python 3.12+.
4. Check third-party apps support the target version before bumping.

Verification

python manage.py check
python manage.py makemigrations --check --dry-run
python manage.py test        # or pytest
DJANGO_SETTINGS_MODULE=config.settings python manage.py check --deploy   # with production env vars

All four must pass. If makemigrations --check fails, a model change has no migration.

Gotchas

• auto_now fields are not set by QuerySet.update(); set them explicitly there.
• bulk_create and update() skip save(), signals and model validation.
• full_clean() is not called by save(); constraints in Meta are your real guarantee.
• Signals hide control flow; prefer explicit service calls for business logic.
• Timezone: keep USE_TZ = True; compare with timezone.now(), never datetime.now().

Output template

## Django change: <summary>
- Apps/models: <added/changed fields, constraints>
- Migrations: <app.number, reviewed SQL, concurrent/online?>
- Views/forms/admin: <changes>
- Settings: <changes, env vars added>
- Tests: <cases>; checks: check, makemigrations --check, check --deploy