Django Ninja CLAUDE.md Template - Copyable CLAUDE.md Template for Django Ninja Stack

Overview

The CLAUDE.md template is a copyable Claude Code blueprint tailored for Django Ninja stack projects. It provides a structured set of rules, file layout, and expectations so Claude can generate consistent code, tests, docs, and deployment steps for Django Ninja APIs built with Python and Django ORM.

When to Use This CLAUDE.md Template

• Kickstart new Django Ninja API projects with a standardized architecture.
• Provide Claude Code with clear project role, constraints, and validation rules.
• Enforce authentication/authorization patterns (JWT or session-based) across endpoints.
• Ensure consistent validation, error handling, and testing strategies.
• Bridge design between frontend and backend teams with reproducible scaffolding.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role: Django Ninja API Engineer

Architecture Rules:
- Build a clean Django project using Django Ninja to expose a RESTful API.
- Use Django ORM for data access; keep domain logic in models and services.
- Place API surface behind routers in api/router.py.

File Structure Rules:
- Root contains manage.py and requirements.txt.
- All Django settings live in django_project/settings.py.
- Apps live under api/ with a dedicated router and schemas.
- Tests live under tests/.

Authentication Rules:
- Implement JWT-based auth using djangorestframework-simplejwt; endpoints must require authentication by default.
- Public endpoints (e.g., /auth/login) must be explicit.

Database Rules:
- Use PostgreSQL in production; sqlite3 for local development is acceptable but avoid in prod.
- Use migrations for schema changes; seed initial data in fixtures or migrations.

Validation Rules:
- Use Pydantic models (via Django Ninja) for request validation.
- Validate all input types; enforce required fields and constraints.

Security Rules:
- Disable CSRF for API views; enforce HTTPS in production.
- Do not expose sensitive fields in responses; use serializers to shape outputs.
- Store secrets in environment variables, not in code.

Testing Rules:
- Use pytest-django; include unit tests for models and validators.
- Include integration tests for key endpoints (auth, resource CRUD).
- Run tests as part of CI on push or PR.

Deployment Rules:
- Deploy with Gunicorn + Django ASGI support if possible; ensure static files are served correctly.
- Use environment-based settings; never commit production secrets.

Things Claude Must Not Do:
- Do not generate brittle ORM hacks or raw SQL prone to SQL injection.
- Do not bypass authentication or authorization checks.
- Do not rely on in-memory databases for production logic.

Recommended Project Structure

django-ninja-django-project/
├── manage.py
├── requirements.txt
├── django_ninja_project/
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   └── urls.py
├── api/
│   ├── __init__.py
│   ├── models.py
│   ├── schemas.py
│   ├── views.py
│   ├── router.py
│   └── apps.py
├── tests/
│   ├── test_endpoints.py
│   └── conftest.py
├── templates/
└── static/

Core Engineering Principles

• Explicit over implicit: every behavior and rule is documented in CLAUDE.md.
• Single source of truth: one template drives code generation for the stack.
• Testability: design for unit and integration tests from day one.
• Security by default: enforce auth, input validation, and secure defaults.
• Maintainability: clear separation of concerns and predictable file structure.

Code Construction Rules

• All API endpoints must live under api/router.py and be discoverable via Django Ninja.
• Use Pydantic-based schemas for requests and responses; keep models lean.
• Authentication is required by default on protected endpoints; public auth endpoints are explicit.
• Use environment variables for secrets; read them via Django settings.
• Validate inputs at both endpoint and model levels; never trust client data.
• Avoid direct SQL; rely on Django ORM unless a performance-critical path necessitates raw SQL with parameter binding.

Security and Production Rules

• Enable HTTPS in production; set SECURE_SSL_REDIRECT = True.
• Disable CSRF for API routes; use proper authentication schemes.
• Limit allowed hosts; configure ALLOWED_HOSTS.
• Do not expose debug information in production.
• Rotate and manage secrets via a vault or environment vars.

Testing Checklist

• Unit tests for models and validators.
• Integration tests for login, token refresh, and protected endpoints.
• API contract tests to ensure request/response shapes remain stable.
• CI workflow runs tests on push/PRs.

Common Mistakes to Avoid

• Relying on SQLite in production tests without migration concerns.
• Nesting business logic in views; extract to services.
• Overexposing model fields in responses; use serializers to shape output.
• Skipping authentication on endpoints that should be protected.

FAQ