Skip to content

existential-birds/beagle / plugins/beagle-rust/skills/rust-best-practices

rust-best-practices

Verified

Development guidance for writing idiomatic Rust. Use when: (1) writing new Rust functions or modules, (2) choosing between borrowing, cloning, or ownership patterns, (3) implementing error handling with Result types, (4) optimizing Rust code for performance, (5) configuring clippy and linting for a project, (6) deciding between static and dynamic dispatch, (7) writing documentation or doc tests.

references/clippy-config.md

View on GitHub
# Clippy Configuration

## Daily Workflow Command

Run on every commit or PR:

```shell
cargo clippy --all-targets --all-features --locked -- -D warnings
```

- `--all-targets`: checks library, tests, benches, examples
- `--all-features`: enables all feature flags to catch conditional code
- `--locked`: requires Cargo.lock to be up-to-date (omit for library crates that don't commit `Cargo.lock`)
- `-D warnings`: treats warnings as errors

Add to your Makefile, Justfile, xtask, or CI pipeline.

## Workspace Lint Configuration

Configure in `Cargo.toml` for consistent enforcement:

```toml
[workspace.lints.rust]
future-incompatible = "warn"
nonstandard_style = "deny"

[workspace.lints.clippy]
all = { level = "deny", priority = 10 }
redundant_clone = { level = "deny", priority = 9 }
manual_while_let_some = { level = "deny", priority = 4 }
pedantic = { level = "warn", priority = 3 }
```

Individual crates inherit workspace lints:

```toml
[lints]
workspace = true
```

Higher priority numbers win when lints conflict.

## Key Lints to Enforce

| Lint | Why | Category |
|------|-----|----------|
| `redundant_clone` | Detects unnecessary clones with performance impact | perf |
| `large_enum_variant` | Warns about oversized variants -- consider Boxing | perf |
| `needless_collect` | Prevents unnecessary intermediate collection allocation | nursery |
| `needless_borrow` | Removes redundant `&` borrowing | style |
| `clone_on_copy` | Catches `.clone()` on Copy types like `u32` | complexity |
| `unnecessary_wraps` | Function always returns Some/Ok -- drop the wrapper | pedantic |
| `manual_ok_or` | Suggests `.ok_or_else()` over match | style |

Run the perf lint group specifically:

```shell
cargo clippy -- -D clippy::perf
```

## Lint Suppression

### Use `#[expect]` as the Default

`#[expect]` (stable since Rust 1.81) is the standard for lint suppression. It warns when the lint no longer triggers, preventing stale suppressions from accumulating. Always use `#[expect]` instead of `#[allow]`:

```rust
// BAD - stale allow stays forever unnoticed
#[allow(clippy::large_enum_variant)]
enum Message { /* ... */ }

// GOOD - compiler warns when lint is no longer needed
#[expect(clippy::large_enum_variant)]
enum Message { /* ... */ }
```

When migrating an existing codebase, replace all `#[allow(lint)]` with `#[expect(lint)]`. The compiler will immediately flag any suppressions that are no longer needed, letting you clean up dead lint suppression.

For crate-level suppression where `#![expect(...)]` is not practical (e.g., generated code), `#![allow(...)]` remains acceptable with a comment explaining why.

### Always Add Justification

```rust
// Intentionally large for cache-line alignment
#[expect(clippy::large_enum_variant, reason = "cache-line alignment")]
enum Packet {
    Header(u8),
    Payload([u8; 1024]),
}
```

The `reason` parameter (stable since 1.81) documents intent inline and shows up in compiler output when the expect becomes unfulfilled.

### Handling False Positives

1. Try refactoring to satisfy the lint
2. If the code is genuinely correct, suppress **locally** with `#[expect]` and a reason
3. Avoid global suppression unless it is a known framework issue (e.g., Bevy engine patterns)

## CI Integration

Add clippy to your CI pipeline:

```yaml
# GitHub Actions (application/binary crates that commit Cargo.lock)
- name: Clippy
  run: cargo clippy --all-targets --all-features --locked -- -D warnings

# Library crates (Cargo.lock not committed — omit --locked)
- name: Clippy
  run: cargo clippy --all-targets --all-features -- -D warnings
```

Consider adding pedantic and nursery for stricter checks:

```shell
cargo clippy -- -W clippy::pedantic -W clippy::nursery
```

## Optional Stricter Lints

| Group | When to Use |
|-------|-------------|
| `pedantic` | Strict style checks, occasional false positives |
| `nursery` | New lints under development, may be noisy |
| `perf` | Performance-focused checks (always recommended) |
| `restriction` | Very strict, use selectively (e.g., `clippy::unwrap_used`) |
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall