AGENTS.md for Django + DRF

An AGENTS.md for a service-layer Django REST API: uv commands, per-app structure, N+1 budgets, and migration review rules.

# Registry (Django + DRF)

## Project Overview
Django 5 + Django REST Framework, Postgres, Python 3.12 managed with uv.
Service-layer architecture: views stay thin, business logic lives in services.

## Setup & Commands
```bash
uv sync                                   # install from uv.lock
uv run python manage.py runserver         # dev on :8000
uv run pytest                             # full suite
uv run pytest apps/orders -k test_create  # scope to app or test
uv run ruff check . && uv run ruff format --check .
uv run python manage.py makemigrations && uv run python manage.py migrate
```

## Structure
- `apps/<name>/` - one Django app per bounded context; each contains
  `models.py`, `serializers.py`, `views.py`, `services.py`, `tests/`
- `config/` - settings (split by environment), urls, asgi
- Settings read from env via `django-environ`; no secrets in the repo

## Code Style
- Business logic in `services.py` functions; views orchestrate, models hold
  data + invariants. A view over ~40 lines is doing too much.
- All input crosses a DRF serializer; `request.data` is never read directly.
- Querysets: prefer `select_related`/`prefetch_related` at the view boundary;
  the N+1 check in CI fails PRs that regress query counts.

## Testing
- pytest-django with factory_boy factories (`apps/*/tests/factories.py`).
- Every endpoint tests: success, permission denial (403), validation error (400).
- DB-touching tests use the `db` fixture; no mocking the ORM.

## Migrations
- Generated migrations get reviewed like code - check for accidental drops and
  missing `db_index`. Data migrations are separate from schema migrations.

## Boundaries
- Never edit an applied migration; make a follow-up migration.
- Cross-app imports only via the other app's `services.py` - not its models.
- Raw SQL requires a comment naming why the ORM couldn't express it.

## PR Guidelines
- Ruff + pytest green; include new migrations in the PR body summary.

These examples are released under CC0. Use them freely, no attribution required. They are provided as is, without warranty of any kind: review and adapt them to your project before use, as you are responsible for the outcome of applying them.