agentleFS
Sign inStart free
JSBtechnologiesJSBtechnologies/rustkb/skills/rust-architecture/SKILL.md

rust-architecture

Skill0 starsChanged 43 days agoMITView on GitHub

Project and system design for Rust. Use when starting a new Rust project or crate (cargo new, scaffolding, "set up a Rust service/CLI/library"), deciding bin vs lib vs workspace, designing crate and module structure or visibility, applying layered/hexagonal (ports and adapters) architecture or dependency injection, structuring an axum/tokio web service (state, errors, graceful shutdown, timeouts, health checks), a clap CLI (exit codes, stdout/stderr, config precedence), or a publishable library (semver, feature flags, MSRV, no_std); for configuration and secrets, tracing/metrics/OpenTelemetry setup, and CI/CD, release (release-plz, cargo-dist) and copy-paste templates (Cargo.toml with workspace lints, clippy.toml, deny.toml, GitHub Actions workflow, rust-toolchain.toml).

  • Reads credentials

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. dawidpereira/rust-skills★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository4 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    ARCH-02: Start with one package; binaries get a thin main.rs over a lib.rs.

    line 25
  2. Distinctive:

    ARCH-09: No global mutable state: main is the composition root and passes dependencies down.

    line 30
  3. Very specific:

    Read project-kickoff.md; write the ADR block with the chosen defaults.

    line 76
  4. Very specific:

    Add CI (ci-cd-release.md) in the first commit, then run cargo clippy --all-targets -- -D warnings and cargo test locally before handing …

    line 81

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

rust-architecture

Opinionated defaults for shaping Rust projects. Language-level idioms (errors, async, traits, testing) live in rust-idioms; crate choices in rust-ecosystem; supply chain and secure coding in rust-security. Every rule has a stable ID — cite it in reviews and plans.

Core rules

  1. ARCH-01 Answer the kickoff questions (shape, edition, MSRV, async, errors, config, observability, targets) before scaffolding; state the defaults you picked.
  2. ARCH-02 Start with one package; binaries get a thin main.rs over a lib.rs.
  3. ARCH-03 / WS-06 Split crates only for separate deployables, reuse, heavy-dependency isolation, enforced dependency direction, or proc-macros — never one crate per layer.
  4. ARCH-06 Async only for concurrent network IO; sync + rayon for CPU work; never start a runtime inside a library.
  5. ARCH-09 No global mutable state: main is the composition root and passes dependencies down.
  6. WS-02 A virtual workspace manifest must say resolver = "3".
  7. WS-04 / WS-05 Versions once in [workspace.dependencies]; lints once in [workspace.lints] with [lints] workspace = true in every member.
  8. MOD-01 / MOD-05 Modules by domain concept; no utils/helpers/common dumping grounds.
  9. MOD-03 / MOD-04 Private by default, pub(crate) in binaries, lib.rs re-exports a curated facade.
  10. HEX-01 Concrete types by default; a trait only at an external boundary that needs a second implementation (e.g. a test fake).
  11. HEX-05 / HEX-07 Inject with generics that stop at the composition root; no DI containers or service locators; dyn/enums only for runtime choice.
  12. SVC-04 One ApiError: IntoResponse maps domain errors to HTTP; 5xx bodies are generic.
  13. SVC-05 / SVC-06 SIGTERM + Ctrl-C graceful shutdown with cancellation of background tasks; request timeout, body limit and outbound timeouts everywhere.
  14. CLI-02 / CLI-04 main returns ExitCode and prints error: {err:#}; data to stdout, diagnostics to stderr; never unwrap() in main.
  15. LIB-04 Cargo features are strictly additive (std, never no-std); test with cargo hack --feature-powerset.
  16. LIB-02 / LIB-05 Semver-check every library PR; libraries never init loggers, read env vars or call process::exit.
  17. CFG-01 / CFG-04 One typed, validated Settings loaded once at startup; secrets are SecretString; no env::var outside the config module.
  18. OBS-01 tracing in every crate; the subscriber is installed only in binaries.
  19. OBS-04 / OBS-06 #[instrument(skip_all, fields(..))]; never log secrets or bodies.
  20. CI-01 / CI-03 CI runs fmt, clippy -D warnings, test, doc, cargo-deny with --locked; Cargo.lock is committed.

Routing table

SituationRead
"Start/scaffold/set up a new Rust project"; choosing bin vs lib vs workspace, edition, MSRV, asyncreferences/project-kickoff.md
Workspace manifests, crates/ layout, shared deps/lints, when to split crates, xtask, build timesreferences/workspace-layout.md
Module tree, visibility, pub(crate), re-export facade, god-modules, dependency directionreferences/modules-and-boundaries.md
Ports & adapters, clean/hexagonal architecture, DI, traits vs generics vs dyn, fakes vs mocksreferences/layered-hexagonal.md
axum/tokio HTTP service: state, handlers, error mapping, graceful shutdown, timeouts, health, DB poolreferences/web-services.md
clap CLI: structure, exit codes, stdout/stderr, broken pipe, config precedence, progressreferences/cli-apps.md
Publishable library: API surface, semver, feature flags, docs.rs, MSRV policy, no_stdreferences/library-design.md
Config files, env vars, secrets, validation, .envreferences/configuration.md
Logging, spans, #[instrument], log levels, OpenTelemetry, Prometheus metricsreferences/observability.md
GitHub Actions CI, MSRV/semver/feature jobs, caching, release-plz, cargo-dist, cross-compilingreferences/ci-cd-release.md
Copy-paste workspace/member Cargo.toml with lints, rust-toolchain.toml, rustfmt.toml, clippy.toml, release profilereferences/templates.md
Copy-paste deny.toml, .github/workflows/ci.yml, axum service and clap CLI main.rs skeletonsreferences/templates-ci-and-skeletons.md

Workflow for a new project

  1. Read project-kickoff.md; write the ADR block with the chosen defaults.
  2. Scaffold manifests from templates.md, then deny.toml, CI and the service (TPL-11) or CLI (TPL-12) skeleton from templates-ci-and-skeletons.md.
  3. Lay out modules per modules-and-boundaries.md; add ports only per HEX-01.
  4. Wire config (configuration.md) and telemetry (observability.md) in main before features.
  5. Add CI (ci-cd-release.md) in the first commit, then run cargo clippy --all-targets -- -D warnings and cargo test locally before handing back.

Versions and live data

Crate versions in these references were verified against crates.io on 2026-09-29 (see each file's crates: frontmatter). When the rustkb MCP tools are available, prefer them for anything version-sensitive: crate_info (current versions, features, MSRV), search/get_item (versioned API docs), check_advisories (RustSec), explain_lint (rustc/clippy lint docs) and rust_release (what changed in a Rust release). Never write a dependency version from memory.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free