Skip to content

existential-birds/beagle / plugins/beagle-rust/skills/rust-code-review

rust-code-review

Verified

Reviews Rust code for ownership, borrowing, lifetime, error handling, trait design, unsafe usage, and common mistakes. Use when reviewing .rs files, checking borrow checker issues, error handling patterns, or trait implementations. Covers Rust 2024 edition patterns and modern idioms.

references/interface-design.md

View on GitHub
# Interface Design

The four high-level principles — unsurprising, flexible, obvious, constrained — are summarized in [api-design.md](../../rust-best-practices/references/api-design.md) along with the builder pattern, sealed-trait introduction, `#[non_exhaustive]`, and generic SemVer rules. This file is reviewer-actionable depth: the exact mechanics that turn each principle into a finding, in the format `[FILE:LINE] ISSUE_TITLE — short description and the fix.` See also [types-layout.md](types-layout.md) for `Send`/`Sync`/`PhantomData` mechanics, and [error-handling.md](error-handling.md) for `Error` trait expectations referenced by destructor and fallibility checks.

## Object Safety Mechanics

A trait is object-safe (dyn-compatible) only if every method obeys all of:

1. **No `Self` by value.** `fn into_inner(self) -> Self::Output` cannot dispatch through `&dyn Trait` — the vtable has no size for `Self`. `Clone::clone(&self) -> Self` is the canonical violator.
2. **No generic methods.** Each instantiation needs its own vtable slot, so `fn extend<I: IntoIterator>(&mut self, iter: I)` is rejected. `Extend` is non-object-safe.
3. **No associated constants.** They have no receiver, so the vtable cannot dispatch to a specific impl.
4. **No `self`-less methods.** A method without `self`/`&self`/`&mut self`/`Box<Self>`/`Pin<&mut Self>` cannot be virtually dispatched. `FromIterator::from_iter` is non-object-safe for this reason.
5. **`Self: Sized` cannot be a supertrait** if you want `dyn Trait` to exist. `trait Foo: Sized` deliberately bans trait objects.

Escape hatch — `where Self: Sized` on an individual method exempts that method from object-safety checks but disables it for `dyn Trait` callers. `Iterator::collect`, `Read::bytes`, and `Iterator::sum` all use this trick.

```rust
trait Storage {
    fn get(&self, key: &str) -> Option<&[u8]>;
    fn collect_into<C: FromIterator<Vec<u8>>>(&self) -> C
    where
        Self: Sized;
}
```

`Drop` is the exception: it is object-safe by design so every vtable carries a drop slot — every `dyn Trait` is implicitly `dyn Drop`. **SemVer trap:** adding a method to a published trait that takes `Self` by value, returns `Self`, or is generic silently flips the trait to non-object-safe — a major-version break even with a default impl.

**Real-world examples to recognize on sight.** `Clone` is non-object-safe because `clone(&self) -> Self`. `Extend` is non-object-safe because `extend<T: IntoIterator>(&mut self, iter: T)` is generic. `FromIterator` is non-object-safe because `from_iter(iter)` has no `self`. `Iterator` itself *is* object-safe — its generic methods (`collect`, `sum`, `map`, etc.) all carry `where Self: Sized`. `std::io::Read` and `std::io::Seek` are individually object-safe so `Box<dyn Read + Seek>` works for the common "I have a reader that can also seek" case.

When a generic method on your trait is unavoidable, three options preserve object safety:

1. **Lift the generic to the trait** — `trait Foo<I> { fn extend(&mut self, iter: I); }`. Each `I` is a distinct trait; loses some flexibility.
2. **Use dynamic dispatch in the signature** — `fn extend(&mut self, iter: &mut dyn Iterator<Item = X>)`. Forces dynamic dispatch on every caller.
3. **`where Self: Sized` exemption** — disables the method through `dyn Trait` but keeps the trait object-safe overall.

## Ergonomic Trait Impls

Rust does not auto-implement traits for references. `fn run<T: Worker>(w: T)` rejects `&Worker` even when `Worker` is implemented for the pointee — the trait's `&mut self` or `self` methods cannot dispatch through `&T`. When you define a new trait whose receivers permit it, provide blanket forwarding impls:

```rust
impl<T: Worker + ?Sized> Worker for &T { /* &self only */ }
impl<T: Worker + ?Sized> Worker for &mut T { /* &self + &mut self */ }
impl<T: Worker + ?Sized> Worker for Box<T> { /* all receivers */ }
impl<T: Worker + ?Sized> Worker for Arc<T> { /* &self only */ }
```

Pick the impls that match your method receivers. `&T` forwards `&self`-only traits; `&mut T` adds `&mut self`; `Box<T>` and `Rc<T>`/`Arc<T>` can additionally forward methods on owned receivers via `*self`-style dispatch. Standard library trait hierarchies follow this pattern precisely — that is why generic code "just works" with smart pointers.

For iterable collections, implement `IntoIterator` for `&MyType` and `&mut MyType` (in addition to `MyType`) so `for x in &c` and `for x in &mut c` work, matching `Vec`, `HashMap`, and `BTreeMap`. Missing either is a real friction point users notice immediately.

## Wrapper Types and Deref Discipline

A **transparent wrapper** is one whose entire purpose is to add a small piece of behavior around an inner type: `Arc<T>`, `MutexGuard<'_, T>`, `Cow<'_, T>`. For these, provide:

- `Deref` (and `DerefMut` where applicable) so dot-method dispatch forwards
- `AsRef<Inner>` so `&Wrapper` can be passed where `&Inner` is accepted
- `From<Inner>` and a corresponding `Into<Inner>` for wrapping/unwrapping

An **opaque wrapper** intentionally hides the inner type. Do not implement `Deref` — users would expect cheap, transparent forwarding and you would surprise them.

**Deref must be cheap.** If accessing the target requires non-trivial work (allocation, locking, hashing), give it an explicit method instead. `Deref` is invoked implicitly through the dot operator; users will not suspect a `.field` access of doing real work.

**Deref-as-OOP anti-pattern.** When `T: Deref<Target = U>` and both `T` and `U` carry inherent methods, `t.foo()` is unambiguous to the compiler but ambiguous to the reader. `Vec::push` is safe because slices will not gain `push`; an inherent method on a wrapper around a *user-controlled* type may clash with one the user later adds. Mitigations: prefer static/associated functions (`Wrapper::foo(t)`) on the wrapper, or avoid inherent methods on the wrapper entirely.

**`Borrow` vs `AsRef` vs `Deref`.**

- `AsRef<T>` — "I can cheaply produce a `&T`." Many-to-many relationship; no semantic requirements beyond "reference conversion."
- `Borrow<T>` — `AsRef<T>` plus identical `Hash`, `Eq`, and `Ord` between wrapper and inner. That is why `HashSet<String>::get` accepts `&str` via `Borrow`. Wrong if your wrapper changes those semantics (e.g., case-insensitive string).
- `Deref<Target = T>` — implicit, dot-operator forwarding. Used for smart pointers and transparent wrappers.

Use `Borrow` for keyed lookup, `AsRef` for cheap conversion-style API arguments, `Deref` only for transparent pointer-shaped wrappers. A common review mistake: implementing `Borrow<str>` for a wrapper around `String` that normalizes the inner string before hashing — `Borrow` requires identical hash output between wrapper and inner; this is a latent bug that produces silent hash-map lookup misses.

The `Borrow` blanket impl exists for `T`, `&T`, and `&mut T`, which is why bounds like `K: Borrow<Q>` accept whichever form the caller has on hand. That is the mechanism behind `HashMap::get` accepting either `&String` or `&str` when keys are `String`. Do not use `Borrow` as a generic "can be referenced as" trait — that role is `AsRef`'s.

## Borrowed vs Owned in APIs

Three signatures, none strictly better — each shifts cost between caller and callee:

```rust
fn frobnicate1(s: String) -> String;
fn frobnicate2(s: &str) -> Cow<'_, str>;
fn frobnicate3(s: impl AsRef<str>) -> impl AsRef<str>;
```

The first demands an owned `String` (caller may have to allocate) and promises an owned `String` back. The second borrows but locks the return to `Cow` forever — moving away from `Cow` is a breaking change. The third hides the most and constrains the caller the least, but also promises the least — downstream code cannot rely on receiving a `String` or `&str` specifically.

Decision rule for argument shape:

1. If the body needs to own the value (store it as `self`, send across threads, return it), accept `T` — not `&T` + clone inside. Cloning inside hides allocation cost from the caller.
2. If the body only reads, accept `&T`. Exception: small `Copy` scalars (`i32`, `bool`) cost the same by value; pass by value for readability.
3. Large `Copy` arrays (`[u8; 8192]`) are still expensive — flag pass-by-value.
4. If sometimes ownership, sometimes not — return `Cow<'_, T>` (`String::from_utf8_lossy` is the prototype: borrows on success, allocates only on the error path).
5. If lifetimes are making an API painful for cheap-to-clone data, take ownership deliberately.

**Push allocation to the caller.** A function that needs ownership should accept `T` and let the caller decide whether they have a fresh value or need to clone. Hidden internal cloning makes profiling lie.

**`impl Into<String>` argument pattern** is justified only when the function actually moves the string into `self`. Using it on a function that immediately calls `.as_ref()` is a misleading signature — switch to `&str`.

Symmetric trap: returning `String` when the function sometimes already has a borrowed slice forces an unnecessary allocation on the happy path. `Cow<'_, str>` is the right answer when the borrowed case is common.

## Fallible and Blocking Destructors

`Drop::drop(&mut self)` cannot return `Result`, cannot `.await`, and cannot reliably spawn async work because the executor may be shutting down. For I/O-flavored types whose cleanup can fail:

- Provide best-effort `Drop` that swallows errors and does what it can synchronously
- Provide an explicit destructor — `fn close(self) -> Result<(), CloseError>` (or `async fn close(self)`) — and **document it prominently**

```rust
impl Connection {
    pub fn close(self) -> Result<(), CloseError> {
        // graceful shutdown, surfaces errors
    }
}
```

**The move-out trap.** Once you implement `Drop`, you cannot move fields out of `&mut self` in another method, because the destructor still runs and requires all fields intact. Three workarounds in increasing complexity:

1. **`Option`-wrapped inner.** `pub struct Outer(Option<Inner>);` — both `close` and `Drop` use `Option::take`. Inner has no `Drop`. Tax: every method unwraps the `Option`.
2. **Per-field `Option` or `std::mem::take`.** Replace each field with `Option<F>` or swap a default in during destruction. Works when fields have cheap defaults. Tax: every access becomes `.as_ref().unwrap()`. Jon recommends this as the default.
3. **`ManuallyDrop<Inner>`.** Derefs to `Inner` cleanly (no unwraps). `Drop` calls `ManuallyDrop::take`. **Unsafe** — taking twice or using after take is UB. Use only when the type is small enough to verify by reading.

**Async destructor caveats.** Do not call `block_on(async_close())` inside `Drop` — it deadlocks single-threaded executors and panics on multi-threaded runtimes mid-shutdown. Provide `async fn close(self)` and document the leak risk if it is not awaited.

## Naming Conventions as Review Checks

Users guess behavior from names. Mismatches are real bugs.

- **Iteration.** `iter(&self)` returns an iterator. `iter_mut(&mut self)`. `into_iter(self)` consumes. A method called `iter` that takes `self` is a bug.
- **Getters.** A plain getter is `fn name(&self) -> &T`, never `get_name`. Reserve `get_` for interesting behavior — `HashMap::get` returns `Option<&V>` because the key may be missing; that is non-trivial.
- **Conversion cost taxonomy.**
  - `as_*` — cheap, borrowed-to-borrowed reference conversion. `Vec::as_slice`, `String::as_str`. **No allocation.**
  - `to_*` — possibly expensive, borrowed-to-owned. `str::to_string`, `Path::to_owned`. May allocate.
  - `into_*` — consuming, owned-to-owned. `String::into_bytes`.
- **`try_` prefix.** A normally-infallible operation that may fail (`Vec::try_reserve`, `BufWriter::try_into_inner`). Always returns `Result`.
- **`SomethingError`.** A type with this suffix is expected to `impl std::error::Error` and appear in `Result`s. Conversely, anything implementing `Error` should be named `*Error`.
- **`new`, `with_*`, `from_*`.** `new` is the unsurprising primary constructor. `with_capacity(n)` configures one knob. `from_*` is an infallible conversion-as-constructor (`String::from_utf8` is fallible, hence the variant `from_utf8_unchecked`).
- **Pairs.** `is_empty()` is paired with `len()`. `contains_key()` is paired with `get()`. Inconsistent pairs (`empty()` returning a bool, `length()` instead of `len()`) violate intuition.
- **Unchecked / dangerous variants.** Suffixes like `_unchecked` or `_dangerous` signal "skips a check the safe version performs" and demand `unsafe`. Standard examples: `slice::get_unchecked`, `str::from_utf8_unchecked`. Use these names deliberately as a documentation hint — they make readers stop and consult the safety contract.

Corollary: reusing a familiar name with mismatched semantics is worse than inventing a fresh name. A method named `iter` that takes `self` will cause users to write `for x in c.iter() { ... }` followed by a second call that fails because `c` was moved.

## Standard Derive Priority

Implement these eagerly on public types because foreign users cannot add them later (coherence). Jon's ordered priority:

1. **`Debug`** — every public type. Hand-write the impl if `#[derive(Debug)]` would propagate `T: Debug` to a phantom generic. Use `f.debug_struct`, `f.debug_tuple`, `f.debug_list` helpers.
2. **`Send`, `Sync`, `Unpin`** — these are auto-traits, but if your type is *not* one of them, document why prominently. A non-`Send` type cannot live in `Mutex` or in async runtimes.
3. **`Clone`** — most types should clone. If yours cannot, document.
4. **`Default`** — when "zero-state" is obvious.
5. **`PartialEq`** — gates `assert_eq!` in tests. Worth deriving even when equality is rare.
6. **`Eq`, `Hash`** — for collection keys; `Eq` carries reflexivity, so only derive when semantics agree.
7. **`PartialOrd`, `Ord`** — only when meaningful ordering exists. Don't derive on enums where variant order is arbitrary.
8. **`Serialize`, `Deserialize`** — gate behind a `serde` cargo feature: `#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]`. Forcing the dependency is rude.

**`Copy` is deliberately absent from the priority list.** It changes move semantics, surprises users who expected `.clone()`, and is brittle: adding any non-`Copy` field later (a `String`, an `Arc`) silently removes `Copy` and breaks every caller relying on it. Reserve `Copy` for plain scalar-like newtypes where it is genuinely natural.

## Hidden Contracts

Two categories of subtle SemVer hazards.

**Re-exports.** Any foreign type appearing in your public interface — return type, argument, associated type — makes that crate's major version part of your contract:

```rust
// your crate
pub fn iter<T>() -> itercrate::Empty<T> { /* ... */ }
// downstream wires it into:
struct Wrapper { inner: itercrate::Empty<()> }
```

When you bump `itercrate` from 1.x to 2.x, *your* crate still compiles, but downstream code holding `itercrate1::Empty` cannot accept your new `itercrate2::Empty` — they are different types. **Bumping a major version of a re-exported dependency is a breaking change for you.** Mitigations:

- Wrap the foreign type in a newtype, exposing only the operations you want
- Return `impl Trait` with a narrow bound so the concrete type is invisible
- Use David Tolnay's "SemVer trick" when one foreign type genuinely did not change across the boundary

The newtype mitigation looks like:

```rust
pub struct Iter<T>(itercrate::Empty<T>);
impl<T> Iterator for Iter<T> { /* forward */ }
pub fn iter<T>() -> Iter<T> { Iter(itercrate::empty()) }
```

Downstream now depends on `Iter`, not on `itercrate::Empty` directly — you can swap `itercrate` for a different implementation without breaking anyone. The `impl Trait` variant pushes this even further: `pub fn iter<T>() -> impl Iterator<Item = T>` exposes nothing about the underlying type.

The SemVer trick (David Tolnay): if a foreign type genuinely did not change between *its* 1.0 and 2.0, you can release a 1.x patch of your own crate that depends on the *foreign* 2.0 and re-exports the type from 2.0. Both `foreign1.x::Type` and `foreign2.x::Type` then resolve to the same item, even though other things in the foreign crate did break.

**Auto-trait propagation.** `Send`, `Sync`, `Unpin`, `UnwindSafe`, and `RefUnwindSafe` are inferred from fields. They also propagate through `-> impl Trait` and `async fn` return types — callers can rely on the returned future being `Send` even though its concrete type is hidden. Result: changing a private field's type can silently flip a public type's auto-trait set.

```rust
// Before: A: Send because B: Send
pub struct A { private: B }
// After: B now holds Rc<T>, so A: !Send. SILENT BREAKING CHANGE.
```

**Compile-time auto-trait test** is the standard defense — a zero-cost test that fails to compile when a public type loses an expected auto-trait:

```rust
fn is_normal<T: Sized + Send + Sync + Unpin>() {}

#[test]
fn assert_normal() {
    is_normal::<MyType>();
    is_normal::<MyFuture>();
}
```

Run it in CI. Variants for `!Send` types replace the bounds with `Sized + Unpin` only, etc.

The same pattern applies to futures returned from `async fn` — if your public API returns a `Send` future today, a test like the following catches the day someone adds a non-`Send` local across an `.await`:

```rust
fn assert_send_future<F: Future + Send>(_: F) {}
#[test]
fn future_is_send() {
    assert_send_future(my_async_fn(/* args */));
}
```

**`#[doc(hidden)]` does not hide auto-traits.** Hidden items that user code can produce (via macros or sealed-trait helper types) still propagate `Send`/`Sync`/`Unpin` observably. Hidden inherent methods are usually fine to change; hidden auto-trait status is not. The same applies to sealed-trait method signatures: even though no one can implement the trait, the signatures appear in the vtable / generic instantiations of downstream code.

## Generic Arguments and Dispatch

Generic arguments relax the caller's requirements: instead of demanding a specific type, accept anything that satisfies the bounds. Start fully generic with no bounds; add bounds only when the body actually needs an operation. Make an argument generic if you can imagine multiple types a user would reasonably pass; keep it concrete otherwise.

Costs to weigh:

- **Monomorphization bloat.** Each instantiation gets its own codegen copy. Worry in hot code or when many concrete types instantiate the same generic.
- **Dynamic dispatch trade-off.** For arguments already taken by reference, swapping `impl Trait` for `&dyn Trait` cuts code size but forces vtable dispatch on every caller. The decision is made on the caller's behalf — fine for code paths that are never perf-sensitive, painful for library hot loops.
- **Dynamic dispatch is limited.** It works for single-trait bounds (`T: AsRef<str>`) but not compound bounds (`T: Hash + Eq`) — there is no single vtable shape for two traits. Compound bounds must stay generic.
- **Asymmetry.** Generic callers can opt into dynamic dispatch themselves by passing `&dyn Trait`. The reverse is not true — if you take a trait object, callers cannot recover static dispatch.

**Migrating concrete to generic is not free.** Changing `fn foo(v: &Vec<usize>)` to `fn foo(v: impl AsRef<[usize]>)` looks backward-compatible, but callers using inference (`foo(&things.iter().collect())`) break: previously the compiler could infer `Vec`; now it knows only "some `T: AsRef<[usize]>`" and has many candidates. Treat such migrations as semver-minor with a deprecation period.

Practical rule for reviewers: prefer `impl Trait` in argument position for simple bounds, generic parameters when the same type is referenced twice or the caller needs turbofish, and `&dyn Trait` only when you can demonstrate the call site is never performance-sensitive. Take a trait object as an argument only as a deliberate choice — it removes the caller's ability to opt back into static dispatch.

## Review Checks

Format: `[FILE:LINE] ISSUE_TITLE — short description and the fix.` See [api-design.md](../../rust-best-practices/references/api-design.md) for higher-level SemVer rules referenced below.

Object safety:

- `[FILE:LINE] Trait method returns Self — breaks object safety` — add `where Self: Sized` if `dyn Trait` is intended, or rewrite to take `Box<Self>` and return `Box<dyn Trait>`.
- `[FILE:LINE] Trait method has generic parameter — breaks object safety` — lift the generic to the trait, accept `&mut dyn Iterator<Item = X>`, or add `where Self: Sized`.
- `[FILE:LINE] Trait method takes Self by value — breaks object safety` — gate with `where Self: Sized` or accept `Box<Self>`.
- `[FILE:LINE] Trait has associated constant — breaks object safety` — convert to a method with a default impl.
- `[FILE:LINE] Trait method has no self receiver — breaks object safety` — `fn from_x(x: X) -> Self` cannot dispatch via vtable. Add `where Self: Sized` or move to a free function.
- `[FILE:LINE] Trait uses Sized as supertrait — disables all dyn usage` — drop the supertrait unless you genuinely want to forbid trait objects.
- `[FILE:LINE] New trait method returns Self with default impl — silent SemVer-major break` — flag as breaking even though existing impls compile; object-safety changes.
- `[FILE:LINE] Adding non-defaulted method to published trait — breaks downstream impls` — provide a default or bump major.

Ergonomic impls:

- `[FILE:LINE] Trait with &self methods lacks blanket impl for &T` — add `impl<T: Foo + ?Sized> Foo for &T` so generic callers accept references.
- `[FILE:LINE] Trait lacks blanket impl for Box<T>/Arc<T>` — provide where receivers allow; missing means `Box<dyn Foo>` doesn't satisfy `T: Foo` bounds.
- `[FILE:LINE] Trait forwarding impl missing ?Sized` — `impl<T: Foo + ?Sized> Foo for &T` should accept `&dyn Foo`. Without `?Sized` it does not.
- `[FILE:LINE] Iterable type lacks IntoIterator for &Self` — `for x in &collection` should compile.
- `[FILE:LINE] Iterable type lacks IntoIterator for &mut Self` — `for x in &mut collection` should compile.

Wrappers and Deref:

- `[FILE:LINE] Deref on wrapper does non-trivial work (lock/allocate)` — switch to an explicit method; Deref must be cheap.
- `[FILE:LINE] Wrapper has inherent method shadowing Deref::Target method` — clash risk on user-controlled targets; prefer `Wrapper::method(w)` static form.
- `[FILE:LINE] Transparent wrapper missing From<Inner>/Into<Inner>` — add to let users freely wrap and unwrap.
- `[FILE:LINE] Transparent wrapper implements Deref but not AsRef<Inner>` — add `AsRef` for callers using `impl AsRef<Inner>`.
- `[FILE:LINE] Borrow<T> implemented but Hash/Eq differ from inner` — Borrow requires identical hash/eq. Use AsRef instead.
- `[FILE:LINE] Opaque wrapper implements Deref` — Deref should be reserved for transparent wrappers; provide named accessors instead.

Borrowed vs owned:

- `[FILE:LINE] Function takes &T then clones internally — push allocation to caller` — accept `T` so the caller controls allocation.
- `[FILE:LINE] Function accepts String where &str suffices` — caller forced to allocate. Switch to `&str` unless the value is stored.
- `[FILE:LINE] impl Into<String> argument never moved into self` — misleading signature; switch to `&str`.
- `[FILE:LINE] Function returns String where Cow<'_, str> fits` — the function sometimes can return borrowed data; consider Cow.
- `[FILE:LINE] Large [u8; N] array passed by value` — flag bulk Copy arrays moved by value; pass by reference.

Destructors:

- `[FILE:LINE] Drop impl performs fallible I/O — errors silently lost` — provide `fn close(self) -> Result<...>` and keep best-effort logic in Drop.
- `[FILE:LINE] Drop impl calls block_on(...)` — async destructors deadlock or panic. Provide `async fn close(self)`.
- `[FILE:LINE] Explicit close()/shutdown() not surfaced in module docs` — users will not find it. Add documentation pointer to the explicit destructor.
- `[FILE:LINE] Type implements Drop and attempts to move out of self in another method` — won't compile or uses workarounds; require Option/take/ManuallyDrop pattern.
- `[FILE:LINE] ManuallyDrop::take used without safety comment` — unsafe; document why double-take and use-after-take are impossible.

Naming:

- `[FILE:LINE] iter takes self instead of &self — violates convention` — `iter` should take `&self`. `into_iter` consumes.
- `[FILE:LINE] Getter named get_foo() — drop the get_ prefix` — plain getters are `fn foo(&self) -> &T`.
- `[FILE:LINE] as_* allocates — should be to_*` — `as_*` is cheap reference conversion; allocation belongs in `to_*`.
- `[FILE:LINE] to_* returns borrowed data — should be as_*` — borrowed-to-borrowed is `as_*`, borrowed-to-owned is `to_*`.
- `[FILE:LINE] Fallible operation lacks try_ prefix` — name it `try_foo` and return `Result`.
- `[FILE:LINE] Error type missing "Error" suffix` — types implementing `std::error::Error` should be named `SomethingError` (see [error-handling.md](error-handling.md)).
- `[FILE:LINE] Type named FooError does not implement std::error::Error` — implement Error or rename.

Standard derives:

- `[FILE:LINE] Public type missing Debug` — derive Debug or hand-write; document if intentionally absent.
- `[FILE:LINE] derive(Debug) adds spurious T: Debug bound on phantom generic` — hand-write Debug to skip the bound.
- `[FILE:LINE] Public type !Send/!Sync with no documented reason` — add a `// Not Send because ...` comment or rustdoc note.
- `[FILE:LINE] Type missing Clone in a domain where users will clone` — derive Clone or document why missing.
- `[FILE:LINE] Type missing Default where construction is obvious` — derive Default.
- `[FILE:LINE] Type missing PartialEq — blocks assert_eq!` — derive at minimum.
- `[FILE:LINE] derive(Copy) chosen for convenience` — Copy is a long-term commitment; removing it is a breaking change. Reconsider unless the type is plainly scalar.
- `[FILE:LINE] serde derive not gated behind a feature flag` — gate with `#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]`.

Hidden contracts:

- `[FILE:LINE] Re-exported foreign type in public API` — bumping that dependency's major becomes your breaking change. Consider newtype wrapping or returning `impl Trait`.
- `[FILE:LINE] Public type missing compile-time auto-trait test` — add `fn is_normal<T: Sized + Send + Sync + Unpin>() {}` and call it from a test.
- `[FILE:LINE] Public type silently became !Send by changing private field` — flag as breaking; add or update auto-trait test.
- `[FILE:LINE] async fn returns non-Send future from a public API marked .await-able across threads` — annotate the future's `Send` requirement or fix the offending field.
- `[FILE:LINE] doc(hidden) item in user-reachable position` — auto-traits and sealed-trait signatures are still observable through it; document.
- `[FILE:LINE] Sealed trait not documented as sealed` — users will try to implement it; document the seal in rustdoc.
- `[FILE:LINE] Public crate adds prelude with new trait method` — risks wildcard-import ambiguity; flag and consider versioning the prelude.
- `[FILE:LINE] -> impl Trait return type leaks an auto-trait change` — auto-traits propagate through `impl Trait`; verify Send/Sync expectations are preserved.

Generic arguments and dispatch:

- `[FILE:LINE] Public API takes &dyn Trait — forces dynamic dispatch on all callers` — prefer `impl Trait` or a generic parameter so callers may choose.
- `[FILE:LINE] Concrete Vec<T> argument where &[T] or impl AsRef<[T]> fits` — flag with caveat that switching to generic can break caller inference.
- `[FILE:LINE] Single-use-site generic` — unnecessary generics inflate codegen with no flexibility benefit.
- `[FILE:LINE] impl Trait used in argument position when turbofish is needed at call sites` — switch to an explicit generic parameter so callers can `foo::<T>(...)`.
- `[FILE:LINE] Generic with no bounds in body of function — body uses methods` — compile error, but flag intent: are bounds missing or is the generic unused?

Documentation expectations:

- `[FILE:LINE] Function panics but lacks # Panics rustdoc section` — document panic conditions.
- `[FILE:LINE] Function returns Result but lacks # Errors rustdoc section` — document each error variant and trigger condition.
- `[FILE:LINE] unsafe fn lacks # Safety section` — caller preconditions must be spelled out.
- `[FILE:LINE] Crate root lacks an end-to-end usage example` — module-level examples beat per-method examples for new users.
- `[FILE:LINE] Builder/Result-returning function lacks #[must_use]` — annotate so ignoring the result triggers a warning.

## Anti-Patterns to Flag

- Reusing a familiar name with mismatched semantics (`iter` taking `self`)
- `get_foo()` for plain getters; reserve `get_` for `Option`-returning or fallible reads
- `as_*` that allocates, `to_*` that returns borrowed data
- Deriving `Copy` reflexively to "save a clone"
- `serde` derives without a feature flag
- New trait without blanket impls for `&T`, `&mut T`, `Box<T>`
- Iterable type without `IntoIterator` for `&Self` and `&mut Self`
- `Deref` on a wrapper whose target work is expensive
- Inherent methods on a wrapper whose `Deref::Target` is user-controlled
- `Borrow<T>` used as a generic "I behave like `&T`" when `AsRef<T>` is the correct trait
- Trait method that returns `Self` or takes a generic — silently kills object safety
- Adding a method to a published trait that flips it to non-object-safe
- Internal cloning that hides allocation cost from the caller
- `block_on(async_cleanup())` inside `Drop`
- Silent error-swallowing in `Drop` with no explicit `close()` alternative
- Re-exporting foreign types and treating dependency major bumps as internal-only
- No compile-time auto-trait test for important public types
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 321kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall