Skip to content
Skills Library
Programming · Building & coding

django

/django

Django 5+ framework guardrails, patterns, and best practices for AI-assisted development. Use when working with Django projects, or when the user mentions Django. Provides ORM patterns, views, templates, DRF, admin, and security guidelines.

Repository
samuel ↗
Licence
MIT
Last repository change
29.04.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 29.04.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Django 5+ framework guardrails, patterns, and best practices for AI-assisted development. Use when working with Django projects, or when the user mentions Django. Provides ORM patterns, views, templates, DRF, admin, and security guidelines.

Original author description

Django 5+ framework guardrails, patterns, and best practices for AI-assisted development. Use when working with Django projects, or when the user mentions Django. Provides ORM patterns, views, templates, DRF, admin, and security guidelines.

How it works

  1. Core Principles
  2. When to Use Django
  3. Project Structure
  4. Guardrails
  5. Views and URLs
  6. ORM Essentials
  7. Admin Configuration
  8. Django REST Framework (DRF)
  9. Security Essentials
  10. Testing
Original SKILL.md headings · 472 lines, 1,539 words
SKILL.md preview
---
name: django
description: |
  Django 5+ framework guardrails, patterns, and best practices for AI-assisted development.
  Use when working with Django projects, or when the user mentions Django.
  Provides ORM patterns, views, templates, DRF, admin, and security guidelines.
license: MIT
metadata:
  author: samuel
  version: "1.0"
  category: framework
  language: python
  extensions: ".py"
---

# Django Framework Guide

> Applies to: Django 5+, Django REST Framework, Django Channels
> Language: Python 3.10+

## Core Principles

1. **Batteries Included**: Leverage Django's built-in features before adding third-party packages
2. **DRY**: Don't Repeat Yourself -- use abstract models, mixins, and shared utilities
3. **Fat Models, Thin Views**: Keep business logic in models and services, not views
4. **Explicit Over Implicit**: Use clear URL patterns, explicit imports, named relationships
5. **Security by Default**: CSRF, XSS protection, SQL injection prevention are built in

## When to Use Django

**Good fit:**
- Full-stack web applications with templates
- Admin interface needed out of the box
- Content management systems
- Session-based authentication
- ORM with built-in migrations

**Consider alternatives:**
- Pure APIs with async-first needs (FastAPI)
- Minimal framework overhead (Flask)
- Real-time heavy workloads without Channels

## Project Structure

```
myproject/
├── manage.py
├── pyproject.toml
├── requirements/
│   ├── base.txt
│   ├── dev.txt
│   └── prod.txt
├── config/                    # Project configuration
│   ├── __init__.py
│   ├── settings/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── dev.py
│   │   └── prod.py
│   ├── urls.py
│   ├── wsgi.py
│   └── asgi.py
├── apps/                      # Django applications
│   ├── users/
│   │   ├── __init__.py
│   │   ├── admin.py
│   │   ├── apps.py
│   │   ├── models.py
│   │   ├── views.py
│   │   ├── urls.py
│   │   ├── forms.py
│   │   ├── serializers.py     # If using DRF
│   │   ├── services.py        # Business logic
│   │   └── tests/
│   │       ├── __init__.py
│   │       ├── test_models.py
│   │       ├── test_views.py
│   │       └── test_services.py
│   └── core/                  # Shared utilities
│       ├── __init__.py
│       ├── models.py          # Abstract base models
│       └── mixins.py
├── templates/
│   ├── base.html
│   └── components/
├── static/
│   ├── css/
│   └── js/
└── tests/
    └── conftest.py
```

- Split settings into `base.py`, `dev.py`, `prod.py`
- Group apps under `apps/` directory
- Keep `core/` app for shared abstract models and utilities
- Place business logic in `services.py`, not in views
- Co-locate tests inside each app under `tests/` directory

## Guardrails

### Settings

- Never hardcode `SECRET_KEY` -- use `python-decouple` or environment variables
- Split settings: `base.py` (shared), `dev.py` (debug), `prod.py` (secure)
- Always define `AUTH_USER_MODEL` before first migration
- Set `DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"`
- Use `ALLOWED_HOSTS` in production (never `["*"]`)

### Models

- Always define `__str__` on every model
- Always set `class Meta` with `db_table`, `ordering`, and `indexes`
- Use abstract base models for shared fields (`TimeStampedModel`, `UUIDModel`)
- Use `TextChoices`/`IntegerChoices` for status fields (not raw strings)
- Add `related_name` to all ForeignKey and OneToOneField relationships
- Use `on_delete` explicitly: `CASCADE`, `PROTECT`, `SET_NULL`, `SET_DEFAULT`
- Add database indexes for frequently queried fields
- Use `validators` at model level for domain constraints

### Abstract Base Models

```python
# apps/core/models.py
from django.db import models
import uuid


class TimeStampedModel(models.Model):
    """Abstract base with created/updated timestamps."""
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True


class UUIDModel(models.Model):
    """Abstract base with UUID primary key."""
    id = models.UUIDField(
        primary_key=True, default=uuid.uuid4, editable=False
    )

    class Meta:
        abstract = True
```

### Custom User Model

- Always create a custom user model before the first migration
- Extend `AbstractUser` (not `AbstractBaseUser` unless you need full control)
- Set `AUTH_USER_MODEL = "users.User"` in settings

```python
# apps/users/models.py
from django.contrib.auth.models import AbstractUser
from django.db import models
from apps.core.models import TimeStampedModel, UUIDModel


class User(AbstractUser, UUIDModel, TimeStampedModel):
    email = models.EmailField(unique=True)
    USERNAME_FIELD = "email"
    REQUIRED_FIELDS = ["username"]

    class Meta:
        db_table = "users"
        ordering = ["-created_at"]
        indexes = [models.Index(fields=["email"])]

    def __str__(self) -> str:
        return self.email
```

## Views and URLs

### Class-Based Views (CBVs)

- Use `ListView`, `DetailView`, `CreateView`, `UpdateView` for CRUD
- Use `LoginRequiredMixin` for authenticated views
- Override `get_queryset()` to add filtering and `select_related`/`prefetch_related`
- Override `form_valid()` to inject the current user

```python
from django.views.generic import ListView
from django.db.models import Q
from .models import Product


class ProductListView(ListView):
    model = Product
    template_name = "products/list.html"
    context_object_name = "products"
    paginate_by = 20

    def get_queryset(self):
        qs = Product.objects.filter(
            status=Product.Status.PUBLISHED
        )
        search = self.request.GET.get("q")
        if search:
            qs = qs.filter(
                Q(name__icontains=search)
                | Q(description__icontains=search)
            )
        return qs.select_related("category")
```

### URL Configuration

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

urlpatterns = [
    path("admin/", admin.site.urls),
    path("api/", include("apps.api.urls")),
    path("", include("apps.products.urls")),
]
```

- Use `include()` for app-level URL namespaces
- Use `app_name` in each app's `urls.py` for reverse resolution
- Serve media files in DEBUG mode only

## ORM Essentials

### Query Optimization

- Always use `select_related()` for ForeignKey/OneToOne (SQL JOIN)
- Always use `prefetch_related()` for ManyToMany/reverse FK (separate query)
- Use `only()` or `defer()` to limit fields when not all columns needed
- Never call `Model.objects.all()` without pagination or limits
- Use `F()` expressions for database-level operations
- Use `Q()` objects for complex lookups

### Avoiding N+1 Queries

```python
# BAD: N+1 queries
for product in Product.objects.all():
    print(product.category.name)  # Extra query per product

# GOOD: Single JOIN query
for product in Product.objects.select_related("category"):
    print(product.category.name)  # No extra queries
```

### Transactions

- Use `@transaction.atomic` for multi-step writes
- Use `select_for_update()` for optimistic locking

```python
from django.db import transaction

@transaction.atomic
def transfer_stock(source_id, dest_id, qty):
    source = Product.objects.select_for_update().get(id=source_id)
    dest = Product.objects.select_for_update().get(id=dest_id)
    source.stock -= qty
    dest.stock += qty
    source.save(update_fields=["stock"])
    dest.save(update_fields=["stock"])
```

## Admin Configuration

```python
from django.contrib import admin
from .models import Product

@admin.register(Product)
class ProductAdmin(admin.ModelAdmin):
    list_display = ["name", "category", "price", "status"]
    list_filter = ["status", "category", "created_at"]
    search_fields = ["name", "description"]
    prepopulated_fields = {"slug": ("name",)}
    readonly_fields = ["created_at", "updated_at"]
    ordering = ["-created_at"]

    fieldsets = (
        (None, {"fields": ("name", "slug", "description")}),
        ("Pricing", {"fields": ("price", "stock")}),
        ("Classification", {"fields": ("category", "status")}),
        ("Timestamps", {
            "fields": ("created_at", "updated_at"),
            "classes": ("collapse",),
        }),
    )
```

- Always register models with `@admin.register(Model)`
- Use `list_display` for useful columns, `list_filter` for filtering
- Use `prepopulated_fields` for slug generation
- Group fields with `fieldsets` for organized admin forms

## Django REST Framework (DRF)

### Settings

```python
REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework.authentication.SessionAuthentication",
        "rest_framework_simplejwt.authentication.JWTAuthentication",
    ],
    "DEFAULT_PERMISSION_CLASSES": [
        "rest_framework.permissions.IsAuthenticated",
    ],
    "DEFAULT_PAGINATION_CLASS": (
        "rest_framework.pagination.PageNumberPagination"
    ),
    "PAGE_SIZE": 20,
    "DEFAULT_THROTTLE_RATES": {
        "anon": "100/hour",
        "user": "1000/hour",
    },
}
```

### ViewSets and Routers

- Use `ModelViewSet` for full CRUD
- Use `@action(detail=True/False)` for custom endpoints
- Override `get_serializer_class()` for different read/write serializers
- Override `get_queryset()` to add `select_related`/`prefetch_related`

```python
from rest_framework import viewsets
from rest_framework.decorators import action
from rest_framework.response import Response


class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.select_related("category")
    permission_classes = [IsAuthenticatedOrReadOnly]

    def get_serializer_class(self):
        if self.action in ["create", "update", "partial_update"]:
            return ProductCreateSerializer
        return ProductSerializer

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

    @action(detail=True, methods=["post"])
    def publish(self, request, pk=None):
        product = self.get_object()
        product.status = Product.Status.PUBLISHED
        product.save(update_fields=["status"])
        return Response({"status": "published"})
```

### Serializers

- Use `ModelSerializer` for standard CRUD
- Add `read_only_fields` for computed/auto fields
- Validate in `validate_<field>()` or `validate()` methods
- Use nested serializers for read, flat IDs for write

## Security Essentials

- CSRF: Enabled by default for forms; use `@csrf_exempt` sparingly
- XSS: Django templates auto-escape by default; never use `|safe` with user data
- SQL Injection: ORM uses parameterized queries; never use raw SQL with string formatting
- Clickjacking: `X-Frame-Options` middleware enabled by default
- HTTPS: Set `SECURE_SSL_REDIRECT = True` in production
- HSTS: Set `SECURE_HSTS_SECONDS` in production
- Cookies: Set `SESSION_COOKIE_SECURE = True` and `CSRF_COOKIE_SECURE = True`
- Passwords: Use `AUTH_PASSWORD_VALIDATORS` (enabled by default)
- CORS: Use `django-cors-headers` with explicit allowed origins (never `CORS_ALLOW_ALL_ORIGINS` in production)

## Testing

### Standards

- Use `pytest` with `pytest-django` (not Django's built-in test runner)
- Mark database tests with `@pytest.mark.django_db`
- Use `factory-boy` or fixtures for test data
- Use `APIClient` for DRF endpoint testing
- Coverage target: >80% for business logic
- Test file naming: `test_models.py`, `test_views.py`, `test_services.py`

### Fixtures

```python
# conftest.py
import pytest
from rest_framework.test import APIClient
from apps.users.models import User


@pytest.fixture
def api_client():
    return APIClient()


@pytest.fixture
def user(db):
    return User.objects.create_user(
        username="testuser",
        email="test@example.com",
        password="testpass123",
    )


@pytest.fixture
def authenticated_client(api_client, user):
    api_client.force_authenticate(user=user)
    return api_client
```

## Commands Reference

```bash
# Development
python manage.py runserver
python manage.py shell_plus          # django-extensions

# Migrations
python manage.py makemigrations
python manage.py migrate
python manage.py showmigrations

# Testing
pytest
pytest -v --cov=apps --cov-report=html
pytest apps/products/ -k "test_create"

# Database
python manage.py dbshell
python manage.py dumpdata products > fixtures/products.json
python manage.py loaddata fixtures/products.json

# Static files
python manage.py collectstatic

# Celery
celery -A config worker -l info
celery -A config beat -l info
```

## Dependencies

**Base**: `Django>=5.0`, `djangorestframework`, `django-cors-headers`, `django-filter`, `djangorestframework-simplejwt`, `python-decouple`, `psycopg2-binary`, `whitenoise`

**Dev**: `pytest`, `pytest-django`, `pytest-cov`, `factory-boy`, `django-debug-toolbar`, `django-extensions`, `black`, `ruff`, `mypy`, `django-stubs`

## Best Practices

### Do

- Use `select_related` and `prefetch_related` for every queryset
- Create indexes for frequently queried fields
- Use `@transaction.atomic` for multi-step operations
- Validate at both model level and serializer level
- Write services for business logic (not in views)
- Use signals sparingly (prefer explicit service calls)
- Cache expensive queries with Django cache framework
- Use environment variables for all configuration

### Don't

- Put business logic in views
- Use raw SQL without parameterization
- Ignore N+1 query problems
- Store sensitive data in settings files
- Use `Model.objects.all()` without limits
- Skip migrations in production
- Use `CORS_ALLOW_ALL_ORIGINS = True` in production
- Use `|safe` template filter with user-provided data

## Advanced Topics

For detailed code examples and advanced patterns, see:

- [references/patterns.md](references/patterns.md) -- DRF serializers, middleware, services, signals, Celery tasks, management commands, deployment, and testing patterns

## External References

- [Django Documentation](https://docs.djangoproject.com/)
- [Django REST Framework](https://www.django-rest-framework.org/)
- [Two Scoops of Django](https://www.feldroy.com/books/two-scoops-of-django-3-x)
- [Django Best Practices](https://django-best-practices.readthedocs.io/)
Files in this package (2)
  • SKILL.md 14 KB
  • references/patterns.md 25 KB

Versions

RepositoryScoreLicence
This page · ar4mirez/samuel100MIT
ericrisco/rsc-harness100MIT
TerminalSkills/skills100Apache-2.0
nimadorostkar/Claude-Skills-collection100MIT
claude-dev-suite/claude-dev-suite100MIT
G1Joshi/Agent-Skills100MIT
chrishuffman5/domain-expert100MIT
clawic/skills90MIT
dkbnull/hello-skill90MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version d06b9c341eb3 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95django-patterns
    Django architecture patterns, REST API design with DRF, ORM best practices, caching, signals, middleware, and production-grade Django apps. Use when building or reviewing Django apps, DRF APIs, ORM queries, or caching.
  • 95django-patterns
    Django architecture patterns, REST API design with DRF, ORM best practices, caching, signals, middleware, and production-grade Django apps. Use when building or reviewing Django apps, DRF APIs, ORM queries, or caching.
  • 91django-patterns
    Django 架构模式、使用 DRF 的 REST API 设计、ORM 最佳实践、缓存、信号、中间件和生产级 Django 应用。
  • 100python-django-drf
    Use this skill when developing database-driven backends using Django ORM, migrations, and Django REST Framework viewsets.
  • 91django-patterns
    Django架构模式,使用DRF设计REST API,ORM最佳实践,缓存,信号,中间件,以及生产级Django应用程序。
  • 100django-idioms
    Django and Django REST Framework (DRF) patterns: ORM queries, model managers, class-based views, serializers, migrations, and pytest-django testing. Use when building or maintaining Django backend applications. Pair with python-idioms.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.