# Rust + axum — Claude Code rules

## Cargo

- Rust 2024 edition. `clippy::pedantic` allowed with focused `#[allow(...)]` near the call site.
- One workspace crate per service. Shared types under `crates/<name>-types`.

## axum

- `Router::new()` per module, composed at `main`. No global mutable state.
- Use `axum::extract` types (`State`, `Path`, `Query`, `Json`) over manual deserialisation.
- Handler return type is `Result<impl IntoResponse, AppError>` where `AppError: IntoResponse`.
- Plug `tower_http::trace::TraceLayer` + `tower_http::cors::CorsLayer` at the root.

## Errors

- One application-level error enum via `thiserror`. Variants map to HTTP status codes through `IntoResponse`.
- `anyhow` is for bin/example crates only — never in library code that owns the error type.

## Async

- `tokio` as the runtime. No blocking I/O in async fns; wrap with `tokio::task::spawn_blocking` when needed.
- Persistent connections live in `AppState` (cloneable `Arc<…>` interior).

## Database

- `sqlx` with the `postgres` feature. Compile-time checked queries via `sqlx::query!`.
- Migrations under `migrations/` managed by `sqlx-cli`.