Django app rules

# AGENTS.md: Django app

Django project managed with uv. Supported Django: 5.2 LTS or 6.x; check `pyproject.toml` before using a newer API.

## Commands
- Run: `uv run python manage.py runserver`. Shell: `uv run python manage.py shell`.
- Tests: `uv run pytest -q` (pytest-django) or `uv run python manage.py test`.
- Checks before saying done: `uv run python manage.py check`, `uv run python manage.py makemigrations --check --dry-run`
  (must report no changes), tests, and `uv run ruff check .`.
- Deployment settings: `uv run python manage.py check --deploy` with production settings.

## Models and migrations
- Every model change ships with its migration in the same commit. Use the `safe-migration` skill.
- Never edit or delete a migration that may have run anywhere else. Add a new one.
- In data migrations use `apps.get_model("app", "Model")`, never import the model class.
- Read the SQL of risky migrations with `uv run python manage.py sqlmigrate <app> <number>` and show it to the human.

## Queries
- No N+1: `select_related` for foreign keys, `prefetch_related` for reverse and many-to-many. Prove it with
  `assertNumQueries` (or `django_assert_num_queries` in pytest-django) when you touch a list view.
- Writes that must succeed together go in `transaction.atomic()`.
- Never build SQL with string formatting. Use the ORM, or `raw()` and `cursor.execute()` with parameters.

## Security
- `SECRET_KEY`, `DEBUG`, `ALLOWED_HOSTS` and database credentials come from the environment, never hard-coded.
- Never add `@csrf_exempt` to a view that uses session auth. Never mark user input `mark_safe` or `|safe`.
- Validate input with forms or serializers, not by reading `request.POST` directly.
- Views that need a login use `LoginRequiredMixin` or `@login_required`; check object ownership in the queryset.

## Style
- Fat models, thin views: business rules on the model or in a service module, not in templates.
- Settings changes go in the settings module the project already uses; do not add a second settings system.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `safe-migration`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Django app rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/django-app/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `safe-migration`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Django app rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/django-app/ -->

---
name: safe-migration
description: Make a Django model change with a reviewed migration, a zero-downtime path for destructive changes and a query-count test. Use when adding, renaming or removing fields or models.
---

# Safe migration

1. Change the model. Run `uv run python manage.py makemigrations <app>` and read the generated file.
2. Show the SQL: `uv run python manage.py sqlmigrate <app> <number>`. Flag to the human anything that rewrites or locks a
   large table (adding a non-null column with a default on old databases, new indexes on big tables, type changes).
3. Destructive changes take two releases:
   - Remove a field: release 1 stops using it in code (and makes it nullable if needed); release 2 drops the column.
   - Rename: add the new field, copy data in a data migration, switch code, drop the old field later.
     Never rely on `makemigrations` guessing a rename on a production table without checking the SQL.
4. Data migrations: `RunPython(forwards, backwards)` using `apps.get_model`. Batch large updates. Always give a
   `backwards` function, or `migrations.RunPython.noop` if reversing is genuinely safe to skip.
5. Run `uv run python manage.py migrate` locally, then `makemigrations --check --dry-run` (no changes left) and tests.
6. If a list view or API touches the changed model, add a query-count test like `references/test_query_count.py`.
7. Report: migration file, SQL summary, whether it is safe to run on a live database, and the follow-up release if any.

"""Query-count test: a list of books with authors must not issue one query per book (N+1).

Adapt the app, model and function names. Uses Django's TestCase.assertNumQueries.
"""

from django.test import TestCase

from shop.models import Author, Book
from shop.queries import book_titles_with_authors


class BookListQueries(TestCase):
    @classmethod
    def setUpTestData(cls):
        for i in range(5):
            author = Author.objects.create(name=f"Author {i}")
            Book.objects.create(title=f"Book {i}", author=author)

    def test_one_query_for_any_number_of_books(self):
        with self.assertNumQueries(1):
            rows = book_titles_with_authors()
        self.assertEqual(len(rows), 5)
        self.assertEqual(rows[0], ("Book 0", "Author 0"))