Context
No automation for common developer actions. New contributors have to read through README and CLAUDE.md to piece together the setup steps. A Makefile provides discoverable, standardized entry points.
Proposed Targets
make setup # Create venv, install deps, start docker services, run migrations
make test # Run pytest with standard flags
make lint # Run ruff check + ruff format --check
make format # Run ruff format (auto-fix)
make dev # Start uvicorn with --reload on port 8000
make docker # Build and run full stack via docker-compose
make migrate # Run alembic upgrade head
make openapi # Export OpenAPI spec to docs/openapi.json
make clean # Remove __pycache__, .pytest_cache, etc.
Why
- Reduces onboarding friction from ~10 minutes to
make setup && make dev
- Standardizes commands across contributors
- Self-documenting —
make help lists all targets
Context
No automation for common developer actions. New contributors have to read through README and CLAUDE.md to piece together the setup steps. A Makefile provides discoverable, standardized entry points.
Proposed Targets
Why
make setup && make devmake helplists all targets