AGENTS.md template for Django

# Project instructions

This repository is a Django application. Preserve its app boundaries, settings structure, URL conventions, ORM patterns, and existing test strategy. Keep changes narrow and treat database and authorization behavior as public contracts.

## Start here

- Read the target app's models, views, URLs, forms or serializers, templates, and tests before editing.
- Use the Python version, virtual environment, and dependency manager already configured in the repository.
- Reuse shared mixins, managers, services, permissions, and template components before adding new abstractions.
- Preserve user changes and never reveal values from environment or local settings files.

## Commands

- `python -m pip install -r requirements.txt`: install dependencies when this repository uses requirements files.
- `python manage.py runserver`: start the development server.
- `python manage.py check`: run Django system checks.
- `python manage.py test`: run the Django test suite.
- `python -Wa manage.py test`: run tests with deprecation warnings visible.

Replace these commands when the repository uses uv, Poetry, pip-tools, pytest, Docker, or project-specific scripts.

## Repository map

- Project package: settings, root URLs, ASGI, and WSGI configuration.
- Django apps: domain models, views, forms, admin, tasks, and app-level URLs.
- `templates/` and `static/`: rendered UI and browser assets.
- `migrations/`: ordered schema history; never treat generated migrations as disposable.
- `tests/` or `test*.py`: unit, request, permission, and integration coverage.

## Django rules

- Keep business rules out of templates and thin request handlers when an established service or model method owns them.
- Use forms or serializers for client-controlled data and return validation errors through the existing interface.
- Enforce authorization on the server for every object-level action; hiding a control in the UI is not authorization.
- Avoid N+1 queries. Use `select_related` and `prefetch_related` only when supported by the access pattern and tests.
- Preserve transaction boundaries and make background jobs safe to retry when the project uses queues.
- Keep settings environment-specific and never hard-code secrets, hosts, storage credentials, or production flags.

## Database changes

- Do not create, edit, squash, or apply migrations unless the task explicitly requires a schema change.
- Review defaults, nullability, indexes, data backfills, locks, and rollback behavior before accepting a migration.
- Do not run migrations against shared or production databases from a development task.
- Add focused model and migration tests when a data invariant changes.

## Testing and validation

- Run the narrowest affected test label first, then the full required suite.
- Cover success, invalid input, unauthenticated, unauthorized, and missing-object branches for request changes.
- Assert query counts for performance-sensitive list or detail views when the repository already does so.
- Run system checks and tests with warnings before completing framework or settings changes.

## Definition of done

- The changed flow works through its public URL, command, task, or model boundary.
- Required tests and Django system checks pass.
- Authorization, query behavior, and migration safety were considered explicitly.
- No secrets, unrelated settings, generated migrations, or user changes were modified accidentally.
- The handoff states the behavior changed, checks run, and any schema or deployment risk.