# AGENTS.md — Python

Drop this in your repository root and symlink CLAUDE.md to it:

    ln -s AGENTS.md CLAUDE.md

Then delete every line that is not true of YOUR repository, and add the
corrections you have had to make to an agent twice. Under 100 lines is the
target — every line competes for attention with every other line.

From Python at https://learn-python.com/ai/ — free to use, MIT.

---

Python 3.12. Package management is `uv` — never pip or poetry.

## Commands
- Install:    `make install`   (uv sync)
- Test:       `make test`      (pytest -q, fast tests only, under 5s)
- One test:   `uv run pytest tests/test_x.py::test_name -q`
- Lint + fmt: `make lint`      (ruff check --fix, ruff format)
- Types:      `make typecheck` (mypy src, strict)
- All of it:  `make check`     <- must pass before you say you are done

## Layout
- `src/core/`      pure domain logic. No I/O, no framework imports.
- `src/adapters/`  db, http clients, queues, object storage.
- `src/api/`       routers. Thin: parse, call core, serialise.
- `tests/`         mirrors src/. Anything needing a database is
                    marked @pytest.mark.integration and excluded by default.

## Conventions
- Money is `Decimal`, never float. Serialise as a string.
- All datetimes are timezone-aware UTC: `datetime.now(UTC)`, never `utcnow()`.
- No bare or broad `except`. Catch what you can act on; let the rest propagate.
- No `assert` for runtime validation — it vanishes under `python -O`.
- Async code uses httpx/asyncio. Never `requests` or `time.sleep` in a coroutine.
- `# type: ignore` needs a comment saying why.
- New dependencies need a sentence in the PR description. Prefer stdlib.

## Working style
- Small commits, one behavioural change each.
- Fix the code, not the test — unless the test is provably wrong, and say so.
- Over ~150 lines of diff: stop and describe the plan first.