GitHub rust-2026-template — my Rust starter in 2026

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:

.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:

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: VERSION tracks the generated project's starter version; .template/CHANGELOG-TEMPLATE.md tracks internal template evolution separately (see issue #135).

GitHub Actions workflows

Release engineering

• dist-workspace.toml + release.toml for cargo-dist automated releases
• cliff.toml for git-cliff changelog generation
• MIGRATION.md for upgrade guidance between template versions
• docflow.json and opencode.json for 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/ and plans/ — agent working directories

Use it

1. Hit "Use this template" on GitHub — or tell your agent: use github.com/d-oit/rust-2026-template as the reference for this project
2. Follow QUICKSTART.md — rename the crates, update Cargo.toml metadata
3. Run ./scripts/quality-gates.sh once locally

MIT licensed. PRs welcome.

→ github.com/d-oit/rust-2026-template