settings
Organize Django Settings
When modifying src/project/settings.py, enforce this structure.
Section Format
Every logical group of settings gets a banner header:
# =============================================================================
# SECTION NAME
# =============================================================================
- Banner lines are exactly 77 characters (
#+ 75=characters) - Section name is UPPERCASE
- One blank line before each banner (except at top of file)
- No blank lines between the banner and the first setting in that section
- No inline comments explaining what standard Django settings do — the section header is enough
Section Order
Settings must appear in this order. Omit sections that have no settings.
- Imports and
BASE_DIR(no banner — these are preamble) - LOGGING
- SECURITY —
SECRET_KEY,DEBUG,ALLOWED_HOSTS, CORS, CSRF, cookie settings - APPLICATION DEFINITION —
INSTALLED_APPS,MIDDLEWARE - URLS AND WSGI —
ROOT_URLCONF,WSGI_APPLICATION - TEMPLATES
- AUTH —
AUTH_USER_MODEL,AUTH_PASSWORD_VALIDATORS,LOGIN_URL - DATABASE
- SESSIONS
- CACHING
- INTERNATIONALIZATION —
LANGUAGE_CODE,TIME_ZONE,USE_I18N,USE_TZ - STATIC FILES —
STATIC_URL,STATIC_ROOT,DEFAULT_AUTO_FIELD - CELERY — all
CELERY_*settings - Any additional project-specific sections in alphabetical order
INSTALLED_APPS Sub-grouping
Within INSTALLED_APPS, group entries with inline comments:
INSTALLED_APPS = [
# Django core
"django.contrib.admin",
...
# Third-party
"corsheaders",
...
# Project apps
"products.apps.ProductsConfig",
"orders.apps.OrdersConfig",
]
Project apps must use the dotted path to their AppConfig subclass (e.g., "myapp.apps.MyAppConfig"), not the short app name.
Rules
- Do NOT add Django docs URLs as comments (e.g.,
# https://docs.djangoproject.com/...) - Do NOT add "Quick-start" or "Generated by" boilerplate comments
- Keep
AUTH_PASSWORD_VALIDATORScompact — one dict per line when the only key is"NAME" - When adding a new setting, place it in the correct existing section. Create a new section only if none fit.
More from dvf/opinionated-django
services
Structure Django business logic as plain services that receive their dependencies via constructor injection, and wire them through an svcs registry so they can be resolved anywhere — views, Celery tasks, management commands, tests. Use when adding a new service, refactoring fat views or model methods into a service, wiring a service into the registry, or explaining where business logic should live in this project.
11architecture
Implement a Django feature following the opinionated architecture — prefixed ULID IDs, repository pattern, Pydantic DTOs, svcs service locator, project-scoped django-ninja API, Celery reliable signals, and layered tests. Use when the user asks to add a new entity, endpoint, app, or business logic in a Django project that follows these conventions.
11lint
Run linting, formatting, and static type checks on a Django project using ruff and pyrefly, and fix any issues found. Use after making code changes, before committing, or whenever the user asks to lint, format, or type-check the codebase.
10pytest
Set up and write pytest tests for an op-django project — pytest-django configuration, Celery eager mode for reliable-signal tests, freezegun for time-sensitive logic, shared conftest fixtures for DTOs and svcs overrides, and the three-layer test convention (repository against a real DB, service against mocked repos, API through HTTP). Use when adding tests to a new project, writing tests for a new feature, setting up test infrastructure, or explaining how tests should be organized.
10scaffold
Set up a Django project into the op-django layout so the architecture, signals, and settings skills have a foundation to build on. Use when starting a new project from scratch, or when converting an existing Django project to follow this opinionated structure. Creates the src/project/ shell (ids, services registry, api, reliable signals), installs dependencies with uv, and establishes the per-app directory conventions.
10signals
Add reliable signals (async side-effects via Celery) to a Django feature. Use when a business operation needs to trigger post-commit work like notifications, cache invalidation, analytics, or cross-service coordination — any time the user mentions side-effects, events, or async processing tied to a business action.
10