ADR-023: Make for development automation

Category: development Provenance: human

Decision

Use Make as the primary interface for all development tasks. All common workflows (testing, quality checks, deployment, cluster management) must have corresponding Make targets.

Rationale

Make provides a standardized, discoverable interface for all development tasks. Developers and AI agents can run 'make help' to see all available commands. Make targets abstract away complexity (uv, pytest flags, cluster setup) into simple, memorable commands. Documentation stays in sync because commands are defined once in Makefile. Cross-platform compatibility - Make works on Linux, macOS, Windows (WSL). CI/CD uses same Make targets as local development, ensuring consistency.

Agent Instructions

Always check the Makefile for existing targets before running commands directly. Use 'make help' to see available targets. When adding new development workflows, create corresponding Make targets with descriptive help text. Never document raw commands in guides - reference Make targets instead (e.g., 'make test-integration' not 'uv run pytest tests/integration'). Make targets provide consistent interface across different environments.

Rejected Alternatives

Use shell scripts in scripts/ directory

Less discoverable, no built-in help system, harder to compose tasks. Make provides dependency management and built-in help.

Use task runners like Taskfile or Just

Make is universally available, well-understood, and doesn't require additional tooling. Taskfile/Just add dependencies.

Document raw commands

Commands change (different flags, tools, paths). Make targets provide stable interface even as underlying commands evolve.