Django Project Skill 🧩

This skill scaffolds new Django projects or upgrades existing ones with a production-ready layout and operational practices suitable for large systems.

Scope and alignment 🧭

Mandatory reads (must be loaded before using this skill):

• •Python instructions — use its identifiers when describing compliance.
• •Local-first dev baseline
• •Quality gates baseline
• •Observability logging baseline
• •AI-assisted change baseline

Inputs to confirm ✅

• •Project name and Python version
• •Database (SQLite/PostgreSQL) and cache (Redis/none)
• •API surface (Django REST Framework, HTML templates, or both)
• •Background jobs (Celery/none) and async worker needs
• •Deployment target (container, PaaS, serverless)
• •Environment split (local/staging/prod) and secrets strategy

Quick reference 🧠

Capabilities 🧰

1. Project scaffold (foundation)

Use this for new projects or to align an existing project with the standard layout.

Core requirements:

• •Use pyproject.toml as the single source of truth. If available, start from the template and set:
  • •project metadata (name, version, requires-python)
  • •dependency groups for dev tooling
  • •ruff, mypy, pytest configuration
• •Use uv for deterministic installs and lockfile management.
• •Pin Python in .python-version and requires-python.
• •Scaffold with a src/ layout so imports are explicit and testable.
• •Split settings into base.py, local.py, production.py, and test.py.
• •Provide a minimal apps/ structure for domain growth.
• •Ensure manage.py defaults to local settings and can switch via DJANGO_SETTINGS_MODULE.

Recommended layout:

.
├── .python-version
├── manage.py
├── pyproject.toml
├── src/
│   ├── config/
│   │   ├── __init__.py
│   │   ├── asgi.py
│   │   ├── urls.py
│   │   ├── wsgi.py
│   │   └── settings/
│   │       ├── __init__.py
│   │       ├── base.py
│   │       ├── local.py
│   │       ├── production.py
│   │       └── test.py
│   └── apps/
│       ├── core/
│       ├── health/
│       └── users/
└── tests/

Dependency defaults (adjust to requirements):

• •Django
• •django-environ (or a small local env parser if you want to avoid extra deps)
• •pytest, pytest-django
• •ruff, mypy, django-stubs

2. Large-system structure and boundaries

Use these patterns when the system is expected to grow:

• •Group code by domain in src/apps/<domain>; avoid a single monolithic app.
• •Keep views thin; put business logic in services and selectors.
• •Use serializers/forms as boundary validators; keep DB access inside selectors or repositories.
• •Separate external integrations behind adapters to allow testing and swapping implementations.
• •Avoid global mutable state; wire dependencies explicitly.

3. Observability baseline

Observability is non-negotiable for production workloads:

• •Configure structured logging and include required fields from the structured logging baseline.
• •Add request ID/correlation ID middleware and propagate IDs into logs.
• •Provide health endpoints (/healthz, /readyz) with clear dependency checks.
• •Add optional hooks for metrics and tracing (Prometheus or OpenTelemetry) but keep them toggled by configuration.
• •Never log secrets or raw personal data.

4. Security baseline

Protect data and enforce secure defaults:

• •Load secrets from environment or a secret manager; never commit or log secrets.
• •Enable Django security middleware and set production hardening settings (DEBUG=false, explicit ALLOWED_HOSTS, SECURE_SSL_REDIRECT, SECURE_HSTS_SECONDS, secure cookies).
• •Keep CSRF and CORS explicit; avoid permissive wildcards in production.
• •Use dependency pinning and vulnerability scanning; keep lock files updated.
• •Ensure audit/access logs follow the structured logging baseline without sensitive data.

5. Resilience and availability baseline

Build for failure and recovery:

• •Set explicit timeouts on all outbound HTTP/DB calls; never rely on defaults.
• •Use retries with bounded backoff and jitter for transient failures; avoid retrying non-idempotent operations without safeguards.
• •Use transaction boundaries for multi-step writes; prefer idempotent background jobs.
• •Provide graceful shutdown and ensure long-running tasks are interruptible.
• •Use caching for hot paths and provide safe fallbacks when caches fail.

6. Quality gates and verification

Align with Python quality gates:

• •Prefer make format, make lint, make typecheck, make test when Makefile targets exist.
• •Otherwise use uv run ruff format ., uv run ruff check ., uv run mypy ., uv run pytest.
• •Add python manage.py check to validate Django configuration before shipping.

Output expectations 📦

When executing this skill, produce:

• •A scaffolded Django project or a concrete refactor plan for an existing codebase
• •A list of decisions made for observability, security, resilience, and availability
• •A short validation checklist using the canonical quality gates

When information is missing, record Unknown from code – {suggested action} instead of guessing.

Version: 1.0.0 Last Amended: 2026-01-18