Rust Axum + Docker rules for AI coding agents
Full stack: Rust + Axum + Docker
Ready-to-commit rules for Rust + Axum + Docker in every major format: AGENTS.md (Codex, Cursor, Copilot), CLAUDE.md (Claude Code), Cursor .mdc project rules, legacy .cursorrules, Copilot instructions, Windsurf rules and GEMINI.md. A Rust web service with Axum and Tokio.
Last reviewed 2026-10-21 · Customise in the generator · Raw: AGENTS.md, CLAUDE.md
The mistake agents make most on this stack
Agents `unwrap()` everywhere and block the async runtime with sync I/O.
Generated files
AGENTS.md
# AGENTS.md - this project
Instructions for AI coding agents working in this repository.
## Project
A Rust + Axum + Docker project.
Stack: Rust + Axum, Docker.
## Commands
- Run: `cargo run`
- Tests: `cargo test`
- Lint: `cargo clippy --all-targets -- -D warnings`
- Format: `cargo fmt`
- Local services: `docker compose up -d`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Rust + Axum
- Code must pass `cargo fmt` and `cargo clippy -- -D warnings`.
- No `unwrap()` or `expect()` outside tests and truly unreachable cases; propagate errors with `?`.
- Library errors use `thiserror`; application glue may use `anyhow`.
- Axum handlers return `Result<impl IntoResponse, AppError>` where `AppError` implements `IntoResponse`.
- Share state with `State<Arc<AppState>>`; do not use global mutable statics.
- Never block the async runtime; use `tokio::task::spawn_blocking` for CPU-heavy or blocking work.
- Prefer borrowing over cloning; justify each `.clone()` in hot paths.
## Docker
- Use multi-stage builds and slim, pinned base images.
- Run the app as a non-root user in the final image.
- Keep a `.dockerignore` that excludes `.git`, `node_modules`, `.env` and build output.
- Never bake secrets into images; pass them at runtime.
## Reference docs
- [Axum docs](https://docs.rs/axum)
- [Rust book](https://doc.rust-lang.org/book/)
- [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/)
CLAUDE.md
# CLAUDE.md - this project
Project instructions for Claude Code.
## Project
A Rust + Axum + Docker project.
Stack: Rust + Axum, Docker.
## Commands
- Run: `cargo run`
- Tests: `cargo test`
- Lint: `cargo clippy --all-targets -- -D warnings`
- Format: `cargo fmt`
- Local services: `docker compose up -d`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Rust + Axum
- Code must pass `cargo fmt` and `cargo clippy -- -D warnings`.
- No `unwrap()` or `expect()` outside tests and truly unreachable cases; propagate errors with `?`.
- Library errors use `thiserror`; application glue may use `anyhow`.
- Axum handlers return `Result<impl IntoResponse, AppError>` where `AppError` implements `IntoResponse`.
- Share state with `State<Arc<AppState>>`; do not use global mutable statics.
- Never block the async runtime; use `tokio::task::spawn_blocking` for CPU-heavy or blocking work.
- Prefer borrowing over cloning; justify each `.clone()` in hot paths.
## Docker
- Use multi-stage builds and slim, pinned base images.
- Run the app as a non-root user in the final image.
- Keep a `.dockerignore` that excludes `.git`, `node_modules`, `.env` and build output.
- Never bake secrets into images; pass them at runtime.
## Reference docs
- [Axum docs](https://docs.rs/axum)
- [Rust book](https://doc.rust-lang.org/book/)
- [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/)
.cursor/rules/project.mdc
---
description: "Core rules for this project"
alwaysApply: true
---
# this project
A Rust + Axum + Docker project.
Stack: Rust + Axum, Docker.
## Commands
- Run: `cargo run`
- Tests: `cargo test`
- Lint: `cargo clippy --all-targets -- -D warnings`
- Format: `cargo fmt`
- Local services: `docker compose up -d`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
.cursor/rules/rust.mdc
---
description: "Rust + Axum conventions: Rust web service with Axum and Tokio."
globs: **/*.rs
alwaysApply: false
---
# Rust + Axum
- Code must pass `cargo fmt` and `cargo clippy -- -D warnings`.
- No `unwrap()` or `expect()` outside tests and truly unreachable cases; propagate errors with `?`.
- Library errors use `thiserror`; application glue may use `anyhow`.
- Axum handlers return `Result<impl IntoResponse, AppError>` where `AppError` implements `IntoResponse`.
- Share state with `State<Arc<AppState>>`; do not use global mutable statics.
- Never block the async runtime; use `tokio::task::spawn_blocking` for CPU-heavy or blocking work.
- Prefer borrowing over cloning; justify each `.clone()` in hot paths.
Docs: https://docs.rs/axum, https://doc.rust-lang.org/book/
.cursor/rules/docker.mdc
---
description: "Docker conventions: Containerised builds and local services with Docker."
globs: Dockerfile, **/Dockerfile, compose.yaml, docker-compose.yml, .dockerignore
alwaysApply: false
---
# Docker
- Use multi-stage builds and slim, pinned base images.
- Run the app as a non-root user in the final image.
- Keep a `.dockerignore` that excludes `.git`, `node_modules`, `.env` and build output.
- Never bake secrets into images; pass them at runtime.
Docs: https://docs.docker.com/build/building/best-practices/
.cursorrules
# Cursor rules - this project
You are an expert Rust + Axum, Docker engineer working on this codebase. Follow these rules.
## Project
A Rust + Axum + Docker project.
Stack: Rust + Axum, Docker.
## Commands
- Run: `cargo run`
- Tests: `cargo test`
- Lint: `cargo clippy --all-targets -- -D warnings`
- Format: `cargo fmt`
- Local services: `docker compose up -d`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Rust + Axum
- Code must pass `cargo fmt` and `cargo clippy -- -D warnings`.
- No `unwrap()` or `expect()` outside tests and truly unreachable cases; propagate errors with `?`.
- Library errors use `thiserror`; application glue may use `anyhow`.
- Axum handlers return `Result<impl IntoResponse, AppError>` where `AppError` implements `IntoResponse`.
- Share state with `State<Arc<AppState>>`; do not use global mutable statics.
- Never block the async runtime; use `tokio::task::spawn_blocking` for CPU-heavy or blocking work.
- Prefer borrowing over cloning; justify each `.clone()` in hot paths.
## Docker
- Use multi-stage builds and slim, pinned base images.
- Run the app as a non-root user in the final image.
- Keep a `.dockerignore` that excludes `.git`, `node_modules`, `.env` and build output.
- Never bake secrets into images; pass them at runtime.
## Reference docs
- [Axum docs](https://docs.rs/axum)
- [Rust book](https://doc.rust-lang.org/book/)
- [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/)
.github/copilot-instructions.md
# Copilot instructions - this project
A Rust + Axum + Docker project.
Stack: Rust + Axum, Docker.
## Commands
- Run: `cargo run`
- Tests: `cargo test`
- Lint: `cargo clippy --all-targets -- -D warnings`
- Format: `cargo fmt`
- Local services: `docker compose up -d`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
.github/instructions/rust.instructions.md
---
applyTo: "**/*.rs"
---
# Rust + Axum
- Code must pass `cargo fmt` and `cargo clippy -- -D warnings`.
- No `unwrap()` or `expect()` outside tests and truly unreachable cases; propagate errors with `?`.
- Library errors use `thiserror`; application glue may use `anyhow`.
- Axum handlers return `Result<impl IntoResponse, AppError>` where `AppError` implements `IntoResponse`.
- Share state with `State<Arc<AppState>>`; do not use global mutable statics.
- Never block the async runtime; use `tokio::task::spawn_blocking` for CPU-heavy or blocking work.
- Prefer borrowing over cloning; justify each `.clone()` in hot paths.
.github/instructions/docker.instructions.md
---
applyTo: "Dockerfile,**/Dockerfile,compose.yaml,docker-compose.yml,.dockerignore"
---
# Docker
- Use multi-stage builds and slim, pinned base images.
- Run the app as a non-root user in the final image.
- Keep a `.dockerignore` that excludes `.git`, `node_modules`, `.env` and build output.
- Never bake secrets into images; pass them at runtime.
.windsurf/rules/project.md
---
trigger: always_on
---
# this project
A Rust + Axum + Docker project.
Stack: Rust + Axum, Docker.
## Commands
- Run: `cargo run`
- Tests: `cargo test`
- Lint: `cargo clippy --all-targets -- -D warnings`
- Format: `cargo fmt`
- Local services: `docker compose up -d`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
.windsurf/rules/rust.md
---
trigger: glob
globs: **/*.rs
---
# Rust + Axum
- Code must pass `cargo fmt` and `cargo clippy -- -D warnings`.
- No `unwrap()` or `expect()` outside tests and truly unreachable cases; propagate errors with `?`.
- Library errors use `thiserror`; application glue may use `anyhow`.
- Axum handlers return `Result<impl IntoResponse, AppError>` where `AppError` implements `IntoResponse`.
- Share state with `State<Arc<AppState>>`; do not use global mutable statics.
- Never block the async runtime; use `tokio::task::spawn_blocking` for CPU-heavy or blocking work.
- Prefer borrowing over cloning; justify each `.clone()` in hot paths.
.windsurf/rules/docker.md
---
trigger: glob
globs: Dockerfile, **/Dockerfile, compose.yaml, docker-compose.yml, .dockerignore
---
# Docker
- Use multi-stage builds and slim, pinned base images.
- Run the app as a non-root user in the final image.
- Keep a `.dockerignore` that excludes `.git`, `node_modules`, `.env` and build output.
- Never bake secrets into images; pass them at runtime.
GEMINI.md
# GEMINI.md - this project
Project context for Gemini CLI.
## Project
A Rust + Axum + Docker project.
Stack: Rust + Axum, Docker.
## Commands
- Run: `cargo run`
- Tests: `cargo test`
- Lint: `cargo clippy --all-targets -- -D warnings`
- Format: `cargo fmt`
- Local services: `docker compose up -d`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Rust + Axum
- Code must pass `cargo fmt` and `cargo clippy -- -D warnings`.
- No `unwrap()` or `expect()` outside tests and truly unreachable cases; propagate errors with `?`.
- Library errors use `thiserror`; application glue may use `anyhow`.
- Axum handlers return `Result<impl IntoResponse, AppError>` where `AppError` implements `IntoResponse`.
- Share state with `State<Arc<AppState>>`; do not use global mutable statics.
- Never block the async runtime; use `tokio::task::spawn_blocking` for CPU-heavy or blocking work.
- Prefer borrowing over cloning; justify each `.clone()` in hot paths.
## Docker
- Use multi-stage builds and slim, pinned base images.
- Run the app as a non-root user in the final image.
- Keep a `.dockerignore` that excludes `.git`, `node_modules`, `.env` and build output.
- Never bake secrets into images; pass them at runtime.
## Reference docs
- [Axum docs](https://docs.rs/axum)
- [Rust book](https://doc.rust-lang.org/book/)
- [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/)
Commands your agent should run
| Task | Command |
|---|---|
| Run | cargo run |
| Tests | cargo test |
| Lint | cargo clippy --all-targets -- -D warnings |
| Format | cargo fmt |
| Local services | docker compose up -d |
What the rules cover
Rust + Axum
Rust web service with Axum and Tokio. Scoped to **/*.rs in Cursor, Copilot and Windsurf.
- Code must pass
cargo fmtandcargo clippy -- -D warnings. - No
unwrap()orexpect()outside tests and truly unreachable cases; propagate errors with?. - Library errors use
thiserror; application glue may useanyhow. - Axum handlers return
Result<impl IntoResponse, AppError>whereAppErrorimplementsIntoResponse. - Share state with
State<Arc<AppState>>; do not use global mutable statics. - Never block the async runtime; use
tokio::task::spawn_blockingfor CPU-heavy or blocking work. - Prefer borrowing over cloning; justify each
.clone()in hot paths.
Docker
Containerised builds and local services with Docker. Scoped to Dockerfile, **/Dockerfile, compose.yaml, docker-compose.yml, .dockerignore in Cursor, Copilot and Windsurf.
- Use multi-stage builds and slim, pinned base images.
- Run the app as a non-root user in the final image.
- Keep a
.dockerignorethat excludes.git,node_modules,.envand build output. - Never bake secrets into images; pass them at runtime.
Source docs: Dockerfile best practices
How to install
- Copy
AGENTS.mdto your repo root. That covers Codex, Cursor, GitHub Copilot and most other agents. - Using Claude Code? Add a
CLAUDE.mdwith the single line@AGENTS.md, or use the standalone CLAUDE.md tab above. - Want rules that only load for certain files in Cursor? Add the
.cursor/rules/*.mdcfiles. - Commit the files so your whole team (and every agent) shares them.
FAQ
Where do I put the AGENTS.md for Rust + Axum + Docker?
Save it as AGENTS.md in the root of your repository, next to your main config file. Codex, Cursor and GitHub Copilot pick it up automatically. For Claude Code, add a CLAUDE.md containing @AGENTS.md (or use the standalone CLAUDE.md on this page).
What is the most common mistake AI agents make with Rust + Axum?
Agents unwrap() everywhere and block the async runtime with sync I/O.
Which commands should the agent run to check its work?
For this stack: cargo run, cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt. They are listed in the generated files so the agent runs them before finishing a task.
Do these Rust + Axum + Docker rules work with Cursor and Claude Code?
Yes. This page includes the same rules as AGENTS.md, CLAUDE.md, Cursor .mdc project rules, a legacy .cursorrules file, GitHub Copilot instructions, Windsurf rules and GEMINI.md.
Can I customise these rules?
Yes. Open this stack in the generator to add or remove libraries, set your project name and package manager, switch beginner explanations on, and download everything as a zip.
Related stacks
Node.js + Express + Prisma + Zod validation + Vitest + Docker
A TypeScript REST API with Express 5, Prisma and Zod.
Node.js + Express + Drizzle ORM + Zod validation + Docker
An Express API on Drizzle ORM, packaged with Docker.
Python + FastAPI + SQLAlchemy 2 + Alembic + pytest + Docker
A production-style Python API: FastAPI, SQLAlchemy 2 and Alembic, tested with pytest.
Python + Django + pytest + Docker
A Django app tested with pytest.
Ruby on Rails + Tailwind CSS v4 + Docker
Ruby on Rails 8 with Hotwire and Tailwind.
Go + Docker
A Go HTTP service using the standard library router.