---

name: django description: | Django batteries-included Python framework. Covers models, views, templates, ORM, and admin. Use when building full-featured Python web applications.

USE WHEN: user mentions "django", "django orm", "django admin", "django templates", asks about "python cms", "django rest framework", "drf", "django models", "django migrations", "django channels", "django forms"

DO NOT USE FOR: FastAPI projects - use fastapi instead, Flask projects - use flask instead, async-first Python APIs, microservices without admin panel allowed-tools: Read, Grep, Glob, Write, Edit

Django Core Knowledge

Full Reference: See advanced.md for Django Channels setup, WebSocket consumers, JWT authentication middleware, broadcasting from views, room management, and WebSocket testing.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: django for comprehensive documentation.

Model Definition

from django.db import models

class User(models.Model):
    name = models.CharField(max_length=100)
    email = models.EmailField(unique=True)
    created_at = models.DateTimeField(auto_now_add=True)
    is_active = models.BooleanField(default=True)

    class Meta:
        ordering = ['-created_at']

    def __str__(self):
        return self.name

Views (Class-Based)

from django.views.generic import ListView, DetailView, CreateView
from django.urls import reverse_lazy

class UserListView(ListView):
    model = User
    template_name = 'users/list.html'
    context_object_name = 'users'
    paginate_by = 20

class UserDetailView(DetailView):
    model = User
    template_name = 'users/detail.html'

class UserCreateView(CreateView):
    model = User
    fields = ['name', 'email']
    success_url = reverse_lazy('user-list')

Django REST Framework

from rest_framework import viewsets, serializers

class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ['id', 'name', 'email', 'created_at']

class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

Key Commands

python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

Project Structure

myproject/
├── manage.py
├── myproject/
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
└── users/
    ├── models.py
    ├── views.py
    ├── urls.py
    └── admin.py

When NOT to Use This Skill

• FastAPI projects - FastAPI is async-first with automatic OpenAPI docs
• Flask microservices - Django is heavyweight for simple APIs
• Non-Python backends - Use language-appropriate frameworks
• Real-time only apps - Consider Node.js or Go for WebSocket-heavy apps
• Serverless functions - Django startup time is too slow

Anti-Patterns

Anti-Pattern	Why It's Bad	Solution
N+1 queries	Slow performance	Use select_related() and prefetch_related()
No index on frequently queried fields	Slow queries	Add db_index=True to model fields
Using .filter() in loops	Multiple DB hits	Use .filter(id__in=list)
Storing sensitive data in settings.py	Security risk	Use environment variables
Missing CSRF protection	XSS vulnerability	Keep CsrfViewMiddleware enabled
Fat models	Hard to test	Move business logic to services

Quick Troubleshooting

Problem	Diagnosis	Fix
"No such table" error	Migrations not applied	Run python manage.py migrate
Static files not loading	STATIC_URL misconfigured	Run collectstatic in production
CSRF verification failed	Missing CSRF token	Add {% csrf_token %} to forms
"OperationalError: database is locked"	SQLite concurrency	Use PostgreSQL in production
Circular import errors	Models importing each other	Use get_model() or string references
Slow admin interface	No list_select_related	Add list_select_related to ModelAdmin

Production Readiness

Security Configuration

# settings/production.py
DEBUG = False
ALLOWED_HOSTS = env.list('ALLOWED_HOSTS')
SECRET_KEY = env('SECRET_KEY')

# Security headers
SECURE_SSL_REDIRECT = True
SECURE_HSTS_SECONDS = 31536000
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_CONTENT_TYPE_NOSNIFF = True
X_FRAME_OPTIONS = 'DENY'

# Session security
SESSION_COOKIE_SECURE = True
SESSION_COOKIE_HTTPONLY = True
CSRF_COOKIE_SECURE = True

Caching

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
        'LOCATION': env('REDIS_URL'),
    }
}

# Usage
from django.views.decorators.cache import cache_page

@cache_page(60 * 15)  # 15 minutes
def my_view(request):
    ...

Health Checks

from django.http import JsonResponse
from django.db import connection

def health_check(request):
    return JsonResponse({'status': 'healthy'})

def ready_check(request):
    try:
        connection.ensure_connection()
        return JsonResponse({'status': 'ready', 'database': 'connected'})
    except Exception as e:
        return JsonResponse({'status': 'not ready', 'error': str(e)}, status=503)

Gunicorn Configuration

# gunicorn.conf.py
import multiprocessing

workers = multiprocessing.cpu_count() * 2 + 1
worker_class = 'uvicorn.workers.UvicornWorker'  # For async
bind = '0.0.0.0:8000'
max_requests = 1000
timeout = 30

Testing

import pytest
from django.test import Client

@pytest.fixture
def authenticated_client(django_user_model):
    user = django_user_model.objects.create_user(
        username='test', password='test123'
    )
    client = Client()
    client.force_login(user)
    return client

@pytest.mark.django_db
class TestUserAPI:
    def test_create_user(self, api_client):
        response = api_client.post('/api/users/', {
            'name': 'John', 'email': 'john@example.com'
        }, content_type='application/json')
        assert response.status_code == 201

Monitoring Metrics

Metric	Target
Response time (p99)	< 200ms
Error rate (5xx)	< 0.1%
Database connections	< pool size
Cache hit ratio	> 80%

Checklist

• DEBUG=False in production
• Security headers enabled
• HTTPS enforced (SSL redirect)
• Database connection pooling
• Redis caching configured
• Structured JSON logging
• Health/readiness endpoints
• Gunicorn with workers
• Static files on CDN
• pytest with fixtures

Reference Documentation

• Models & ORM
• Views Patterns