CLAUDE.md

Development Workflow

Always use uv run, not python.

# 1. Make changes.

# 2. Type check.
uv run ty check  # Fast
uv run pyright  # More thorough, but slower

# 3. Run tests.
uv run pytest tests/  # Single suite
uv run pytest tests/<test_file>.py  # Specific file

# 4. Format and lint before committing.
uv run ruff format
uv run ruff check --fix

We've bundled common commands into a Makefile for convenience.

make format     # Format and lint
make type       # Type-check
make check      # make format && make type
make test-fast  # Run tests excluding slow ones
make test       # Run the full test suite
make docs       # Build documentation

Before creating a PR, ensure all checks pass with make test.

Some style guidelines to follow:

• Avoid local imports unless they are strictly necessary (e.g. circular imports).
• Tests should follow these principles:
  • Use functions and fixtures; do not use test classes.
  • Favor targeted, efficient tests over exhaustive edge-case coverage.
  • Prefer running individual tests rather than the full test suite to improve iteration speed.