Imported from AratKruglik/antigravity-sdlc (plugins/django-plugin/skills/django-conventions/SKILL.md). Install upstream with npx skills add AratKruglik/antigravity-sdlc --skill django-conventions. Copyright stays with the author.

Django Conventions

This skill encodes the conventions used across modern Django projects (Django 4.x / 5.x). Apply alongside python-foundation:python-conventions (language idioms) and django-plugin:django-orm-patterns (model/query patterns) when implementing features.

1. Detection

Before writing code, read:

• manage.py — confirms this is a Django project.
• settings.py or settings/base.py — check DJANGO_VERSION, INSTALLED_APPS, REST_FRAMEWORK dict (DRF present?), AUTH_USER_MODEL.
• The project urls.py — understand the existing URL hierarchy and namespace conventions.
• requirements.txt or pyproject.toml — note the exact Django version and whether DRF, django-environ, django-filter, pytest-django, etc. are present.

2. Project and app layout

Prefer a dedicated apps/ directory for application modules and a config/ directory for project-level config. New apps are registered in INSTALLED_APPS using their AppConfig dotted path.

myproject/
  manage.py
  config/
    settings/
      base.py
      local.py
      production.py
    urls.py
    wsgi.py
    asgi.py
  apps/
    users/
      migrations/
      models.py
      views.py
      serializers.py
      urls.py
      admin.py
      apps.py
      signals.py
    orders/
      migrations/
      models.py
      views.py
      serializers.py
      urls.py
      admin.py
      apps.py

apps.py for each application:

from django.apps import AppConfig

class OrdersConfig(AppConfig):
    default_auto_field = 'django.db.models.BigAutoField'
    name = 'apps.orders'
    verbose_name = 'Orders'

    def ready(self) -> None:
        import apps.orders.signals  # noqa: F401 — registers signal handlers

3. Settings split

Production settings must never contain DEBUG = True or a hardcoded SECRET_KEY.

# config/settings/base.py
import environ

env = environ.Env()

SECRET_KEY = env('SECRET_KEY')
DEBUG = env.bool('DEBUG', default=False)
ALLOWED_HOSTS = env.list('ALLOWED_HOSTS')

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'corsheaders',
    'apps.users',
    'apps.orders',
]

DATABASES = {
    'default': env.db('DATABASE_URL'),
}

# config/settings/local.py
from .base import *  # noqa: F401, F403

DEBUG = True
ALLOWED_HOSTS = ['localhost', '127.0.0.1']

# config/settings/production.py
from .base import *  # noqa: F401, F403

SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True

4. URLconf

Project urls.py uses include() with app namespaces. DRF ViewSets are registered on a DefaultRouter in the app's urls.py.

# config/urls.py
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('apps.orders.urls', namespace='orders')),
    path('', include('apps.users.urls', namespace='users')),
]

# apps/orders/urls.py
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from . import views

app_name = 'orders'

router = DefaultRouter()
router.register(r'orders', views.OrderViewSet, basename='order')

urlpatterns = [
    path('', include(router.urls)),
    path('orders/<int:pk>/cancel/', views.OrderCancelView.as_view(), name='order-cancel'),
]

5. DRF ViewSets and serializers

ModelViewSet

from rest_framework import viewsets, permissions
from django_filters.rest_framework import DjangoFilterBackend
from .models import Order
from .serializers import OrderSerializer, OrderCreateSerializer

class OrderViewSet(viewsets.ModelViewSet):
    queryset = Order.objects.select_related('user').order_by('-created_at')
    permission_classes = [permissions.IsAuthenticated]
    filter_backends = [DjangoFilterBackend]
    filterset_fields = ['status']

    def get_serializer_class(self):
        if self.action == 'create':
            return OrderCreateSerializer
        return OrderSerializer

    def get_queryset(self):
        return super().get_queryset().filter(user=self.request.user)

    def perform_create(self, serializer):
        serializer.save(user=self.request.user)

Serializers

Use separate serializers when the create/update payload differs from the list/retrieve shape.

from rest_framework import serializers
from .models import Order

class OrderSerializer(serializers.ModelSerializer):
    class Meta:
        model = Order
        fields = ['id', 'status', 'product', 'qty', 'created_at']
        read_only_fields = ['id', 'status', 'created_at']


class OrderCreateSerializer(serializers.ModelSerializer):
    class Meta:
        model = Order
        fields = ['product', 'qty']

    def validate_qty(self, value: int) -> int:
        if value <= 0:
            raise serializers.ValidationError("Quantity must be positive.")
        return value

    def validate(self, attrs: dict) -> dict:
        # cross-field validation
        return attrs

Nested serializer

class OrderWithUserSerializer(serializers.ModelSerializer):
    user = UserSummarySerializer(read_only=True)

    class Meta:
        model = Order
        fields = ['id', 'user', 'status', 'created_at']

6. DRF permissions

Always declare permission_classes explicitly on every ViewSet and APIView. Do not rely on global defaults alone.

from rest_framework.permissions import BasePermission, IsAuthenticated, IsAuthenticatedOrReadOnly

# Default: require authentication for all methods
permission_classes = [IsAuthenticated]

# Public read, authenticated write
permission_classes = [IsAuthenticatedOrReadOnly]

# Custom permission
class IsOwner(BasePermission):
    def has_object_permission(self, request, view, obj) -> bool:
        return obj.user == request.user

Combine permissions with a list: permission_classes = [IsAuthenticated, IsOwner].

7. Class-based views (CBV)

Use LoginRequiredMixin and PermissionRequiredMixin for access control. Override get_queryset() to scope results to the requesting user. Keep views thin — delegate business logic to service functions.

from django.contrib.auth.mixins import LoginRequiredMixin, PermissionRequiredMixin
from django.views.generic import ListView, CreateView
from django.urls import reverse_lazy
from .models import Order
from .forms import OrderForm

class OrderListView(LoginRequiredMixin, ListView):
    model = Order
    template_name = 'orders/list.html'
    context_object_name = 'orders'
    paginate_by = 20

    def get_queryset(self):
        return Order.objects.filter(user=self.request.user).order_by('-created_at')

    def get_context_data(self, **kwargs):
        context = super().get_context_data(**kwargs)
        context['total'] = self.get_queryset().count()
        return context


class OrderCreateView(LoginRequiredMixin, CreateView):
    model = Order
    form_class = OrderForm
    template_name = 'orders/create.html'
    success_url = reverse_lazy('orders:list')

    def form_valid(self, form):
        form.instance.user = self.request.user
        return super().form_valid(form)

8. Forms

Use ModelForm for model-backed forms. Validate in clean_<field> or clean() — never in the view.

from django import forms
from .models import Order

class OrderForm(forms.ModelForm):
    class Meta:
        model = Order
        fields = ['product', 'qty', 'notes']
        widgets = {
            'notes': forms.Textarea(attrs={'rows': 3}),
        }

    def clean_qty(self) -> int:
        qty = self.cleaned_data['qty']
        if qty <= 0:
            raise forms.ValidationError("Quantity must be positive.")
        return qty

    def clean(self) -> dict:
        cleaned_data = super().clean()
        product = cleaned_data.get('product')
        qty = cleaned_data.get('qty')
        # cross-field validation example
        if product and qty and qty > 100:
            raise forms.ValidationError("Cannot order more than 100 units of a single product.")
        return cleaned_data

9. Signals

Register signal handlers in signals.py and connect them in AppConfig.ready(). Keep handlers thin — for heavy work, dispatch to a background task (Celery, Django Q, etc.).

# apps/orders/signals.py
from django.db.models.signals import post_save
from django.dispatch import receiver
from .models import Order

@receiver(post_save, sender=Order)
def notify_on_status_change(sender, instance: Order, created: bool, **kwargs) -> None:
    if not created and instance.tracker.has_changed('status'):
        # thin: just enqueue a notification task
        send_status_notification.delay(order_id=instance.pk, new_status=instance.status)

# apps/orders/apps.py
class OrdersConfig(AppConfig):
    name = 'apps.orders'

    def ready(self) -> None:
        import apps.orders.signals  # noqa: F401

Best practices:

• Never do database writes in post_save handlers without update_fields guards — it can cause infinite loops.
• Use transaction.on_commit() to enqueue async tasks only after the DB transaction commits.
• Prefer custom model methods or service functions over signals for logic that must be tested directly.

10. Django admin

Register models with @admin.register and provide useful list_display, list_filter, and search_fields.

from django.contrib import admin
from .models import Order

@admin.register(Order)
class OrderAdmin(admin.ModelAdmin):
    list_display = ['id', 'user', 'product', 'status', 'qty', 'created_at']
    list_filter = ['status', 'created_at']
    search_fields = ['user__email', 'product']
    readonly_fields = ['created_at', 'updated_at']
    ordering = ['-created_at']

11. Checklist before completing development phase

• All new ViewSets and APIView subclasses have explicit permission_classes
• Serializer validation uses validate_<field> / validate() — not view bodies
• CBVs use LoginRequiredMixin or permission_classes — no unprotected views
• get_queryset() scopes results to request.user where ownership applies
• Signal handlers are thin and registered in AppConfig.ready()
• Settings read secrets from env — no hardcoded SECRET_KEY or DATABASE_URL
• No makemigrations or migrate called — that is django-migrations-specialist
• python manage.py check passes with no errors
• ruff format . clean