I got tired of setting up the same things every new Rust project. Clippy config, CI pipelines, linker flags, pre-commit hooks, cargo-nextest... all from scratch, every time. And then doing it again every time I switched AI coding tools β re-explaining the project structure, the lint rules, what's off-limits.
So I built rust-2026-template. Click "Use this template", point your agent at it, and you're coding β not configuring.
Version 0.3.2 is the current release. Here's what's in it.
The setup I always end up with anyway
Rust 2024 edition, MSRV 1.88 pinned via rust-toolchain.toml. Workspace layout from day one with resolver "3" β even for small projects. Refactoring a single-crate project into a workspace later is just pain you don't need:
crates/
example-crate/
sample-app/
actor-runtime-template/
checkpoint-template/
hybrid-storage-template/
mcp-server-template/
example-registry-pattern/
example-storage-pattern/
Rename those, done. The crates cover patterns you'll want anyway: actor runtime, checkpointing, MCP server, storage backends.
One script, full quality gate
./scripts/quality-gates.sh
This runs fmt, clippy, cargo nextest, cargo audit, cargo deny, and optionally cargo mutants. Same thing CI runs. I run it before every commit so there are no surprises.
There's also a Makefile for common tasks if you prefer that over the shell script.
The Clippy setup is worth calling out: the workspace Cargo.toml starts with pedantic = "allow" and then selectively promotes specific lints to warn. Things like float_cmp, cast_possible_truncation, redundant_clone, and missing_const_for_fn β correctness signals and free compile-time wins β are turned on. Template ergonomics like unwrap_used, panic, too_many_arguments stay allowed so you're not fighting the linter while scaffolding. You adjust as your project matures.
Mutation testing with cargo-mutants is the one I'd push people to try β it tells you whether your tests actually catch bugs or just touch code. Very different things.
Security defaults, not an afterthought
-
deny.tomlβ license policy and banned crates -
.gitleaks.tomlβ secret scanning before anything gets committed -
.pre-commit-config.yamlβ hooks run locally, not just in CI -
.shellcheckrcβ shell script quality gate -
SECURITY.mdβ vulnerability reporting process
The goal is that you never have to remember to do this. It just happens.
AI agents work out of the box
This is the part I use the most now. Every AI coding tool needs project context β and they all want it in a slightly different place. Instead of re-explaining conventions every session, it's all checked in:
.agents/ β skill definitions per agent + cross-repo context
context/ β context files for repositories derived from this template
skills/ β executable task knowledge and canonical workflows
.claude/ β Claude Code config
.cursor/ β Cursor rules
.gemini/ β Gemini CLI config
.mimocode/ β Mimocode config
.opencode/ β OpenCode config
.qwen/ β Qwen CLI config
.windsurf/ β Windsurf config
agents-docs/ β detailed documentation for AI agents
AGENTS.md β canonical project rules, read by every agent
llms.txt β machine-readable project overview
llms-full.txt β complete source context for deep analysis
AGENTS.md is the key file. It tells any agent: the workspace layout, the lint rules, commit conventions, and what to never touch. You switch from Claude Code to Codex to OpenCode mid-project β they all read the same rules. No re-onboarding.
The template uses a layered documentation strategy that makes the audience explicit:
| Layer | File / Directory | Audience | Purpose |
|---|---|---|---|
| Human Onboarding |
README.md, QUICKSTART.md
|
Humans | High-level overview and setup |
| Agent Contract | AGENTS.md |
AI Agents | Canonical rules (SSOT) |
| Reusable Procedures | .agents/skills/ |
AI Agents | Step-by-step executable task knowledge |
| Tool Adapters |
CLAUDE.md, .cursorrules, etc. |
Specific Tools | Tool-specific deltas |
.agents/context/ carries cross-repo context for projects that derive from the template. When you fork this and build on top of it, agents in the child repo can still pull structured knowledge about the base template's conventions.
llms-full.txt is auto-generated and contains the full source context for agents that need deep analysis. Regenerate both after significant architectural changes:
bash scripts/generate-llms-txt.sh
When you start a new project from this template, you can also just hand the repo URL directly to your agent as context:
"Use github.com/d-oit/rust-2026-template as the reference for this project."
It'll pick up the structure, the tooling choices, and the conventions without you writing a single prompt about them.
Performance defaults you forget to add
.cargo/config.toml sets the mold linker. One line, noticeably faster incremental builds. The dev profile is tuned to avoid the "my debug build takes forever" problem.
The release profile sets lto = "fat", codegen-units = 1, and strip = "symbols" β maximum runtime performance. There's also a release-full alias for backward compatibility and a bench profile with debug = true so Criterion can produce symbol-annotated flamegraphs.
Nix users get flake.nix with clang and mold in the devShell, plus .envrc for direnv/nix-direnv integration.
Benchmarks
The benchmarks/ workspace crate contains all Criterion harnesses under benchmarks/benches/:
-
end_to_end.rsβ end-to-end throughput scenarios -
memory_usage.rsβ allocation and memory pressure scenarios -
sanitization_bench.rsβ input sanitization pipeline benchmarks
It also includes a benchmarks/events/ directory and benchmarks/history.jsonl for tracking benchmark results over time.
cargo bench -p benchmarks
The fuzz crate is excluded from the workspace (exclude = ["fuzz"] in Cargo.toml) so it doesn't affect normal builds. The CI pipeline compile-checks benchmarks on every PR so they never silently break.
Fuzz Testing
A fuzz testing scaffold is included using cargo-fuzz with one target: fuzz_parse_input (in fuzz/fuzz_targets/).
# Install cargo-fuzz (nightly required)
cargo install cargo-fuzz
# Run the fuzz target
cargo fuzz run fuzz_parse_input -- -max_total_time=30
The fuzzer runs weekly via GitHub Actions (fuzz.yml).
Feature Flags
All features are opt-in (default = []). Enable what you need:
| Feature | Description |
|---|---|
cli |
CLI binary support (clap, anyhow, colored) |
persistence |
SQL persistence backend (libsql) |
parallel |
CPU parallelism via rayon |
wasm |
WASM build target support |
mcp |
MCP server support (requires cli) |
tracing-json |
JSON tracing output |
tracing-opentelemetry |
OpenTelemetry tracing backend |
Note: mcp has a declared dependency on cli in the feature graph β enabling mcp automatically enables cli.
Runtime Configuration
A config/profiles/ directory carries environment-specific JSON configuration files (default.json and others). The schema/ directory holds JSON Schema definitions for config and API contracts β keeps your config validated and agent-readable from day one.
VERSION file
A VERSION file at the repo root is the plain-text single source of truth for tooling that can't parse TOML. The CI pipeline verifies VERSION matches Cargo.toml on every push to main β no more version drift.
Note:
VERSIONtracks the generated project's starter version;.template/CHANGELOG-TEMPLATE.mdtracks internal template evolution separately (see issue #135).
GitHub Actions workflows
| Workflow | Trigger | Purpose |
|---|---|---|
ci.yml |
PR / push | Format, Clippy, tests, audit, deny, bench compile-check, VERSION check |
mutants.yml |
Periodic |
cargo-mutants mutation testing |
fuzz.yml |
Weekly |
cargo-fuzz fuzzing |
release.yml |
Tag push | cargo-dist release |
patch-release-on-label.yml |
PR label | Automated patch releases |
hotfix.yml |
Manual | Hotfix branch workflow |
dora-fdrt.yml / dora-report.yml
|
Events | DORA metrics tracking |
docs-check.yml |
PR | Documentation build check |
sync-labels.yml |
Push | Issue label sync |
Release engineering
-
dist-workspace.toml+release.tomlforcargo-distautomated releases -
cliff.tomlfor git-cliff changelog generation -
MIGRATION.mdfor upgrade guidance between template versions -
docflow.jsonandopencode.jsonfor AI-assisted doc and code workflows
Code quality integrations
-
Codecov (
.codecov.yml) β coverage gate enforcement -
Codacy (
.codacy.yml+.codacy/) β static analysis with agent review configs -
commitlint (
commitlint.config.cjs) β conventional commits enforced -
yamllint (
.yamllint.yml) β YAML quality gate -
markdownlint (
.markdownlint-cli2.jsonc) β Markdown quality gate
Output Artifacts
Generated output goes to predictable, git-ignored locations:
-
reports/β HTML reports for coverage, audit, benchmarks -
.agents/ci/β CI health artifacts (ci-status.json,ci-summary.md) -
analysis/andplans/β agent working directories
Use it
- Hit "Use this template" on GitHub β or tell your agent: use
github.com/d-oit/rust-2026-templateas the reference for this project - Follow
QUICKSTART.mdβ rename the crates, updateCargo.tomlmetadata - Run
./scripts/quality-gates.shonce locally
MIT licensed. PRs welcome.
β github.com/d-oit/rust-2026-template












