rodin
5cc77138b2
Consistent structure: prescriptive header, structure, agent instructions (solving/reviewing/evaluating), taxonomy definition. Removed discovery data table and line counts — the patterns speak for themselves.
80 lines
3.9 KiB
Markdown
80 lines
3.9 KiB
Markdown
# 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](https://github.com/rust-lang/rust) *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](patterns/error-handling.md) | 10 | Result, ?, Error trait, From, panic! |
|
|
| [traits.md](patterns/traits.md) | 10 | Small traits, derive, From/Into, Iterator, Deref |
|
|
| [ownership.md](patterns/ownership.md) | 10 | Borrowing, Clone/Copy, Cow, Arc, Drop, lifetimes |
|
|
| [documentation.md](patterns/documentation.md) | 10 | Doc comments, # Safety, # Examples, doc tests |
|
|
| [concurrency.md](patterns/concurrency.md) | 10 | Send/Sync, Mutex, atomics, channels, scoped threads |
|
|
| [testing.md](patterns/testing.md) | 10 | cfg(test), assert_eq!, should_panic, property tests |
|
|
| [unsafe-patterns.md](patterns/unsafe-patterns.md) | 10 | // SAFETY:, unsafe fn, MaybeUninit, FFI |
|
|
| [api-design.md](patterns/api-design.md) | 10 | Naming, #[non_exhaustive], newtype, typestate |
|
|
| [module-organization.md](patterns/module-organization.md) | 10 | File structure, pub use, prelude, workspaces |
|
|
| [macros.md](patterns/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`](https://github.com/rust-lang/rust/tree/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6) (325,000 commits, 8,021 contributors).
|
|
|
|
## Related Repos
|
|
|
|
- [rodin/go-patterns](https://gitea.weiker.me/rodin/go-patterns) — Go patterns from stdlib
|
|
- [rodin/elixir-patterns](https://gitea.weiker.me/rodin/elixir-patterns) — Elixir patterns from stdlib
|