Rust Patterns

Prescriptive. Follow these when writing Rust code.

A pattern is a reusable solution to a recurring problem. Each one has:

• When to use — the problem it solves
• When NOT to use — where it causes harm
• Why — the reasoning, not just the rule
• Source citations — permalink to the exact source location

These are derived from what the Rust standard library actually does, not opinions or blog posts.

Structure

• patterns/ — what to do (error handling, ownership, traits, concurrency, unsafe, macros, etc.)
• smells/ — what NOT to do (anti-patterns, common mistakes)

Pattern Files

File	Patterns	Key Topics
error-handling.md	10	Result, ?, Error trait, From, panic!
traits.md	10	Small traits, derive, From/Into, Iterator, Deref
ownership.md	10	Borrowing, Clone/Copy, Cow, Arc, Drop, lifetimes
documentation.md	10	Doc comments, # Safety, # Examples, doc tests
concurrency.md	10	Send/Sync, Mutex, atomics, channels, scoped threads
testing.md	10	cfg(test), assert_eq!, should_panic, property tests
unsafe-patterns.md	10	// SAFETY:, unsafe fn, MaybeUninit, FFI
api-design.md	10	Naming, #[non_exhaustive], newtype, typestate
module-organization.md	10	File structure, pub use, prelude, workspaces
macros.md	10	macro_rules!, derive, attribute macros, hygiene

How to use

Give your agent these instructions depending on the task:

Solving a problem

You have access to a patterns repo containing proven solutions to recurring Rust problems. When I describe a problem:

1. Identify which pattern files are relevant (read them)
2. Check if my problem matches a "When to use" case
3. Check if it matches a "When NOT to use" case
4. If a pattern fits: suggest the approach, cite the pattern, explain why it applies here
5. If no pattern fits: say so, and suggest an approach grounded in the principles you see across the patterns
6. If my problem matches a smell: warn me before I make the mistake

Never suggest something that contradicts a documented pattern without explicitly calling out the deviation and justifying it.

Reviewing code

You have access to a patterns repo that defines how Rust code should be written. For each file in the diff:

1. Read the relevant pattern files
2. Verify the code follows the documented patterns
3. If it deviates: flag it with a reference to the specific pattern, section, and why it matters
4. If it matches a smell: flag it as a known anti-pattern
5. A deviation without justification is a finding

Don't invent rules. Only flag what the patterns document.

Evaluating a pattern

Read the pattern file. Compare against how the following projects handle the same problem: [list projects]. Does the pattern hold? Are there cases where it breaks down? Should it be updated, split, or retired? File your findings as an issue.

Patterns vs Conventions

Pattern = prescriptive. "When you face X, do Y." Language-scoped. Follow these.

Convention = descriptive. "Project Z does it this way." Context-specific. Study for ideas — applying another project's conventions to yours without understanding their constraints causes harm.

Source

All patterns extracted from library/ at commit f53b654 (325,000 commits, 8,021 contributors).

Related Repos

• rodin/go-patterns — Go patterns from stdlib
• rodin/elixir-patterns — Elixir patterns from stdlib