Python project rules

Standing orders for AI agents working in this repository. Drop into AGENTS.md or your tool's rules file.

Environment & tooling

• Use uv for everything: uv run, uv add — never bare pip install or python.
• Target the Python version in .python-version. No syntax newer than it.
• Format with ruff format, lint with ruff check --fix before presenting code as done.

Style

• Type hints on every public function signature. Prefer X | None over Optional[X].
• Dataclasses (or Pydantic models at boundaries) over dict-shaped data. No stringly-typed payloads.
• f-strings only. No % or .format().
• Raise specific exceptions; never bare except:. Catch narrowly, re-raise with context.

Tests

• pytest, plain assert, no unittest classes. One behavior per test, named test_<behavior>.
• New code ships with tests in the same change. Bug fixes ship with a regression test that fails without the fix.

Boundaries

• No new dependencies without asking — prefer the standard library.
• Never touch files under migrations/ except by generating a new migration.
• Secrets come from the environment; never hardcode, never log them.