# CLAUDE.md - this project

Project instructions for Claude Code.

## Project

A Python + Django + pytest + Docker project.

Stack: Python + Django, pytest, Docker.

## Commands

- Dev server: `python manage.py runserver`
- Create migrations: `python manage.py makemigrations`
- Apply migrations: `python manage.py migrate`
- Tests: `python manage.py test`
- Tests: `uv run pytest -q`
- Local services: `docker compose up -d`

## Project structure

- One Django app per domain. Models, views, urls, admin and tests live inside each app.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## Python + Django

- Follow Django conventions first: fat models/managers, thin views.
- Every model change needs a migration. Never edit a migration that has already been applied in a shared environment.
- Avoid N+1 queries: use `select_related` for foreign keys and `prefetch_related` for reverse/many-to-many relations.
- Validate input with forms or DRF serializers, never by reading `request.POST` directly.
- Read `SECRET_KEY`, database URLs and API keys from env vars. `DEBUG` must be off in production.
- Use the ORM; if raw SQL is unavoidable, always pass parameters, never format strings.
- Keep CSRF protection on for all forms.

## pytest

- Tests live in `tests/` named `test_*.py`. Use plain `assert`.
- Share setup with fixtures in `conftest.py`; use `@pytest.mark.parametrize` for input tables.
- Mock external services (HTTP, LLM APIs, payment providers); tests must not hit the network.
- Every bug fix adds a regression test.

## Docker

- Use multi-stage builds and slim, pinned base images.
- Run the app as a non-root user in the final image.
- Keep a `.dockerignore` that excludes `.git`, `node_modules`, `.env` and build output.
- Never bake secrets into images; pass them at runtime.

## Reference docs

- [Django docs](https://docs.djangoproject.com)
- [pytest docs](https://docs.pytest.org)
- [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/)