django-drf-scaffold

---
name: django-drf-scaffold
description: Scaffold or improve a secure, production-oriented Django and Django REST Framework backend. Use when creating a Django project, starting a DRF API, configuring a custom user model, adding Djoser or Simple JWT authentication, defining authorization, setting up multi-tenancy, or establishing maintainable Django backend architecture and tests.
license: MIT
---

# /django-drf-scaffold

Scaffold or improve a secure, production-oriented Django and Django REST Framework backend.

## Activation

Use this skill when:

- Creating a new Django project
- Starting a Django REST Framework API
- Configuring a custom user model
- Adding Djoser or Simple JWT authentication
- Setting up Django authorization or RBAC
- Configuring multi-tenancy
- Establishing production-ready Django settings
- Setting up Django testing infrastructure
- Improving Django backend architecture

## Workflow

### Step 1: Inspect

Inspect the current directory:

- Detect existing Django project (`manage.py`, settings modules)
- Detect Python project (`pyproject.toml`, `requirements*.txt`)
- Detect existing user model and migrations
- Detect authentication configuration
- Detect DRF configuration
- Detect dependency manager (uv, pip, poetry)
- Detect existing steering files

If a Django project exists, enter **augment mode** — propose only missing or necessary improvements rather than rebuilding.

### Step 2: Ask

Ask one compact group of high-impact questions. Infer answers from existing files where possible. Accept "Use recommended defaults" to skip all questions.

**Question 1 — Project identity:**
- Project name (infer from directory name)
- Optional one-sentence purpose

**Question 2 — Login identifier:**
- Email (default)
- Username
- Email or username

**Question 3 — Authentication:**
- Djoser with Simple JWT (default)
- Simple JWT without Djoser
- Django session authentication
- Custom authentication

**Question 4 — Authorization and tenancy:**
- Django groups and permissions (default)
- Simple role field
- Custom RBAC
- Tenant-scoped RBAC
- Single tenant (default) or Multi-tenant

**Question 5 — Optional infrastructure:**
- Docker
- Redis and Celery
- CORS
- Object storage
- None (default)

**Question 6 — Dependency workflow:**
- Detect automatically (default)
- uv
- pip
- Poetry

### Step 3: Generate

Based on answers and project state:

**New project:** Generate the complete scaffold with selected components.

**Existing project (augment mode):**
- Propose only missing improvements
- Preserve existing conventions unless unsafe
- Explain conflicts before changing architecture
- Never replace user model after migrations without warning

### Step 4: Install Steering

Customize and install steering files into `<project>/.kiro/steering/`:
- `project.md` — Project context
- `architecture.md` — Code conventions
- `security.md` — Security rules
- `testing.md` — Test standards

Inspect existing steering files first. Do not silently overwrite.

### Step 5: Verify

Run available checks:
- Django system checks
- Migration creation and consistency
- Test suite
- Ruff linting
- Production deployment checks (if applicable)
- Scaffold validator script

Report all results honestly. Do not claim success if a check fails.

## Generated Structure (New Project)

```
project-name/
├── .kiro/steering/
│   ├── project.md
│   ├── architecture.md
│   ├── security.md
│   └── testing.md
├── config/
│   ├── settings/
│   │   ├── base.py
│   │   ├── local.py
│   │   ├── test.py
│   │   └── production.py
│   ├── urls.py
│   ├── asgi.py
│   └── wsgi.py
├── apps/
│   ├── common/
│   └── users/
├── tests/
├── manage.py
├── pyproject.toml
├── .env.example
├── .gitignore
└── README.md
```

Added only when selected: `Dockerfile`, `docker-compose.yml`, Celery config, CORS config, `apps/tenants/`.

## Defaults

Unless the user chooses otherwise, generate:

- Django + Django REST Framework
- PostgreSQL production configuration
- Custom user model with email login
- Djoser + Simple JWT with rotation
- Django groups and permissions
- Single-tenancy
- pytest + pytest-django
- Ruff linting
- DRF Spectacular for API schema
- Environment-based settings with `.env.example`
- API versioning, health endpoint, structured errors
- Explicit permission classes, pagination
- Secure production settings
- Project steering files

## Constraints

- Inspect existing files before writing
- Do not silently overwrite user files
- Do not modify unrelated files
- Do not force a package manager change in an existing project
- Do not replace a user model after migrations without explicit warning
- Do not generate Docker/Redis/CORS/storage unless selected
- Do not create empty applications
- Do not expose internal exception details in production
- Do not commit secrets or populated `.env`
- Do not use wildcard production hosts
- Do not disable CSRF without justification

## References

Consult these references when additional detail is needed:

- `references/discovery.md` — Load when inspecting existing projects or deciding questions
- `references/architecture.md` — Load when making structural decisions about views, serializers, services
- `references/authentication.md` — Load when implementing user models, Djoser, JWT, or session auth
- `references/security.md` — Load when configuring production settings, CORS, CSRF, or deployment
- `references/verification.md` — Load when running checks or reporting results

## Verification

After completion, verify:

- Django system checks pass
- Migrations can be created without errors
- Test suite passes
- No secrets are committed
- Steering files are installed
- Custom user model is properly configured

Report:
- Selected configuration
- Files created and modified
- Successful and failed checks
- Security-sensitive decisions
- Remaining manual steps

## Limitations

- Does not deploy to production servers
- Does not create or connect to real databases
- Does not install system packages
- Cannot reverse a previously applied scaffold
- Multi-tenancy uses row-level scoping only (not schema-per-tenant)
- Static validation cannot guarantee complete security