existential-birds/beagle / plugins/beagle-rust/skills/rust-best-practices
rust-best-practices
VerifiedDevelopment 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.2 KB |
| references/api-design.md | markdown | 15.3 KB |
| references/clippy-config.md | markdown | 4.0 KB |
| references/coding-idioms.md | markdown | 13.7 KB |
| references/documentation.md | markdown | 5.5 KB |
| references/ecosystem-patterns.md | markdown | 5.5 KB |
| references/generics-dispatch.md | markdown | 9.9 KB |
| references/performance.md | markdown | 10.5 KB |
| references/pointer-types.md | markdown | 5.1 KB |
| references/type-state-pattern.md | markdown | 3.5 KB |
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`) |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |