rust-cargo-workspace-designer

Design a Cargo workspace that builds fast, layers cleanly and publishes without surprises: decide where crate boundaries pay for themselves, pick a layout, put every shared setting in the root manifest exactly once (package metadata, dependency versions, lints, profiles), keep features additive, and make CI prove it with --locked. Review existing workspaces the same way: three small std-only Rust programs in scripts/ read every manifest (they never run cargo), flag 20 mechanical mistakes and print the internal dependency graph by layer.

#Trigger Conditions

Activate this skill when the user:

• Starts a multi-crate Rust project, converts a single crate into a workspace, or asks "how should I split this into crates?", "monorepo layout", "virtual manifest or root package?"
• Edits a root Cargo.toml with [workspace], [workspace.package], [workspace.dependencies], [workspace.lints], resolver, members, exclude, default-members, or [profile.*]
• Sees warning: profiles for the non root package will be ignored, virtual workspace defaulting to resolver = "1", cyclic package dependency, current package believes it's in a workspace when it's not, default-features is ignored for ..., or cargo publish failing on a path dependency without a version
• Has the same dependency at different versions across crates, two copies of a crate in cargo tree -d, features that work with cargo build --workspace but not with cargo build -p one-crate
• Wants faster builds (cargo build --timings), CI for a workspace, an MSRV policy, a Cargo.lock policy, an xtask crate, proc-macro crate placement, or a release/publishing flow for several crates

#Workflow

0. BUILD     -> once: for t in crate_graph manifest_lint dep_audit; do
                  rustc -O --edition 2021 "$SKILL/scripts/$t.rs" -o "/tmp/$t"; done
1. INVENTORY -> /tmp/crate_graph .                  (crates, layers, internal edges, cycles, membership)
                cargo tree --workspace -e normal -d (duplicates), cargo build --timings (if a toolchain exists)
2. AUDIT     -> /tmp/manifest_lint . --strict; /tmp/dep_audit . --strict   (file:line + fix)
3. BOUNDARIES-> decide split/merge with the table below; target layering domain <- app <- infra <- bin
4. ROOT      -> one virtual manifest: resolver, [workspace.package], [workspace.dependencies],
                [workspace.lints], profiles; members inherit with `x.workspace = true`
5. FEATURES  -> additive only, defaults off at the root, dep:/?/ syntax; test each crate alone (cargo hack)
6. CI        -> fmt, clippy, nextest + doctests with --workspace --all-targets --locked; MSRV job;
                cargo deny; semver-checks for published crates
7. VERIFY    -> all three scripts with --strict exit 0; the graph has no cycles

#When to Split a Crate

Costs of splitting: more manifests, orphan-rule friction (impl ForeignTrait for ForeignType is forbidden, so trait impls must live next to the type or the trait), non-generic functions are not inlined across crates without #[inline] or LTO, and every boundary is a public API you have to maintain. Start with modules; promote a module to a crate when one of the reasons above is real. Detail: crate-boundaries-and-layouts.md.

#Layouts

shop/
├── Cargo.toml            # virtual manifest: [workspace] only, resolver, shared tables, profiles
├── Cargo.lock            # committed, one for the whole workspace
├── .cargo/config.toml    # aliases (xtask), no global rustflags
├── apps/shop-server/     # bin, publish = false
├── crates/shop-domain/   # pure types + rules, no IO          (layer 0-1)
├── crates/shop-macros/   # proc-macro = true                 (layer 0)
├── crates/shop-app/      # use cases, port traits            (layer 2)
├── crates/shop-infra/    # adapters: sqlx, reqwest, tokio     (layer 3)
└── xtask/                # cargo xtask codegen|dist|ci, publish = false

Name folders exactly like the crates (crates/shop-domain holds name = "shop-domain") and prefix every crate with the project name: crates.io has one global namespace and use shop_domain::Order reads clearly.

#Root Manifest

[workspace]
members = ["crates/*", "apps/*", "xtask"]
default-members = ["apps/shop-server"]      # what plain `cargo build` / `cargo run` at the root builds
exclude = ["fuzz"]
resolver = "3"                              # required in a virtual manifest; "2" if MSRV < 1.84

[workspace.package]
version = "0.3.0"
edition = "2024"
rust-version = "1.85"
license = "MIT OR Apache-2.0"
repository = "https://github.com/acme/shop"

[workspace.dependencies]
shop-domain = { path = "crates/shop-domain", version = "0.3.0" }   # path + version: publishable
serde = { version = "1.0.200", default-features = false }           # defaults off; members opt in
tokio = { version = "1.38", default-features = false }
thiserror = "2"

[workspace.lints.rust]
unsafe_code = "forbid"
[workspace.lints.clippy]
all = { level = "warn", priority = -1 }     # groups need a lower priority than single lints
unwrap_used = "warn"

[profile.release]
lto = "thin"
codegen-units = 1
[profile.dev.package."*"]
opt-level = 2                               # fast dependencies, debuggable own code

#Member Manifest

[package]
name = "shop-infra"
description = "Database and HTTP adapters for shop-app"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
repository.workspace = true

[dependencies]
shop-domain = { workspace = true, features = ["serde"] }   # features are ADDED to the workspace entry
tokio = { workspace = true, features = ["rt-multi-thread", "fs"] }

[lints]
workspace = true

A member may add features, optional = true (and default-features = false only if the workspace entry also disables defaults); it can never change the version, path or source. Full key reference: manifest-and-inheritance.md.

#Core Rules

1. Virtual manifest with an explicit resolver. A virtual manifest has no edition, so without resolver it silently uses resolver 1. Use "3" for edition 2024 / MSRV >= 1.84, else "2".
2. Root-only sections live in the root. [profile.*], [patch], [replace] in a member are ignored.
3. One version per dependency. Every external dependency used by two or more crates goes into [workspace.dependencies]; members write dep.workspace = true.
4. Inherit metadata and lints. edition, rust-version, license, repository, version via .workspace = true; every member has [lints] workspace = true.
5. Layers point one way. domain <- app <- infra <- bin; no cycles; shared types sink to the lowest crate; upper layers depend on traits defined below (ports), not the other way round.
6. Internal deps carry path AND version if anything that depends on them is published; everything else is publish = false (apps, xtask, test-support, benchmarks).
7. Features are additive. Defaults off at the root, std as an opt-out-able default, dep: for optional deps, pkg?/feat for weak features, no mutually exclusive features. Test each crate alone.
8. Commit Cargo.lock (binaries and libraries alike, per the 2023 Cargo guidance) and build CI with --locked; declare rust-version and test it in CI.
9. No global rustflags in .cargo/config.toml for things that change codegen of every crate unless you mean it: they invalidate caches, do not reach users of published crates, and are overridden by RUSTFLAGS.
10. Measure before restructuring for speed. cargo build --timings shows the critical path; split the crate on it, not the crates that are already parallel.

#Features and Unification

Cargo builds one copy of each dependency per build with the union of features requested by every package selected for that build. cargo build --workspace and cargo build -p shop-app can therefore compile tokio with different features: one passes, the other fails ("works in CI, fails when built alone"), and switching between them rebuilds. Resolver 2+ keeps build-dependency/proc-macro features, dev-dependency features (unless tests/examples are built) and other-platform dependencies out of the union.

[features]
default = ["std"]
std = ["serde?/std"]          # weak: enables serde/std only if serde is already on
serde = ["dep:serde"]         # namespaced: no implicit "serde" feature is created
[dependencies]
serde = { workspace = true, optional = true, features = ["derive"] }

Check every crate with its own features: cargo hack check --workspace --each-feature --no-dev-deps. Pitfalls, cargo tree -e features -i, workspace-hack crates: features-and-unification.md.

#Symptom -> Cause -> Fix

#Version Notes

Full history: version-history.md.

#Output Format

When designing or reviewing a workspace, answer with:

1. Graph - crates by layer (from crate_graph), proposed moves/splits/merges and why.
2. Findings - rule id, file:line, what breaks and when (now, on publish, on a fresh lockfile).
3. Manifests - complete root Cargo.toml and one representative member, not fragments.
4. Features - per crate: defaults, optional deps, what each feature enables; unification risks.
5. CI and policy - the commands (--workspace --all-targets --locked), MSRV, Cargo.lock, release flow.
6. Verification - the three scripts exit 0 with --strict, plus the cargo commands to run.

#Scripts

Small, standard-library-only Rust programs: they read TOML and never run cargo. Build each once with rustc -O --edition 2021 scripts/<name>.rs -o /tmp/<name>. Input is a workspace directory, any Cargo.toml in it (the whole workspace is checked), or - for one manifest on stdin (no file-system checks).

/tmp/crate_graph .                                  # layered graph + membership findings
/tmp/crate_graph . --dot | dot -Tsvg > crates.svg   # cycle edges drawn in red
/tmp/crate_graph . --json
/tmp/manifest_lint crates/core/Cargo.toml           # a member: checks its whole workspace
/tmp/dep_audit . --json                             # machine-readable findings
/tmp/manifest_lint . --strict                       # exit 1 on any finding (CI gate)
/tmp/dep_audit . --select CW003,CW007 --ignore CW014
cat Cargo.toml | /tmp/manifest_lint -               # one manifest from stdin
/tmp/dep_audit --list-rules                         # each script lists its rules with why and fix

Members are found like Cargo does: members globs minus exclude, plus path dependencies of a root package (implicit members); nested workspaces, hidden directories and target/ are skipped. Exit codes: 0 clean (or findings without --strict), 1 findings with --strict, 2 usage error or missing/invalid root manifest; crate_graph also exits 1 whenever there is a dependency cycle. Unparsable member manifests are warned about and skipped.

#Additional Resources