rust-best-practices

name	rust-best-practices
description	Rust LLM Coding Standard. Use when writing, refactoring, or reviewing Rust code to ensure idiomatic, safe, and maintainable outputs aligned with Rust community standards.

Rust LLM Coding Standard

Purpose: This document defines behavioral rules for Large Language Models that generate Rust code. The goal is to ensure outputs are:

• Idiomatic
• Safe
• Maintainable
• Production-ready
• Aligned with Rust community standards

---

1. Authority Hierarchy

The LLM MUST follow sources in this order:

1. Rust API Guidelines
   https://github.com/rust-lang/api-guidelines

2. Rust Style Guide
   https://github.com/rust-lang/rust/tree/master/src/doc/style-guide

3. Rust Clippy Lints
   https://github.com/rust-lang/rust-clippy

4. The Rust Programming Language Book
   https://github.com/rust-lang/book

5. Rust Unofficial Patterns
   https://github.com/rust-unofficial/patterns

If conflicts occur: Official sources override community sources.

---

2. Core Generation Principles

The LLM MUST:

• Prefer compile-time guarantees over runtime checks
• Use the type system aggressively
• Prefer ownership clarity over convenience
• Avoid unnecessary allocations
• Minimize mutable state
• Produce zero-cost abstractions

---

3. Naming & Style Rules

Follow Rust Style Guide strictly:

• snake_case → functions, variables
• PascalCase → structs, enums, traits
• SCREAMING_SNAKE_CASE → constants

Rules:

• Small cohesive modules
• Prefer composition over inheritance
• Keep functions focused and short
• Apply rustfmt defaults

Reference: https://github.com/rust-lang/rust/tree/master/src/doc/style-guide

---

4. Error Handling Rules

DO:

• Return Result<T, E>
• Use ? operator
• Use thiserror for libraries
• Use anyhow for applications

DO NOT:

• use unwrap()
• use expect()
• panic! for normal control flow

Reference: https://github.com/rust-lang/api-guidelines

---

5. Ownership & Borrowing Policy

Preference order:

borrow > reference > move > clone > Arc

Avoid:

• unnecessary cloning
• Rc as default workaround
• hidden ownership transfer

---

6. Async & Concurrency Rules

• Prefer Tokio ecosystem https://github.com/tokio-rs/tokio

• async only for IO-bound operations

• Never block inside async context

• Prefer message passing over shared mutable state

---

7. Idiomatic Pattern Requirements

Allowed patterns:

• Builder Pattern
• Newtype Pattern
• RAII
• Iterator Pattern
• Typestate Pattern

Reference: https://github.com/rust-unofficial/patterns

---

8. Anti-Patterns (STRICTLY FORBIDDEN)

The LLM MUST NOT generate:

• Global mutable state
• Excessive cloning
• God structs
• Deep nested match chains
• Panic-driven logic
• Hidden allocations

Reference: https://github.com/rust-unofficial/patterns/tree/main/src/anti_patterns

---

9. Dependency Policy

Prefer ecosystem standards:

• serde → https://github.com/serde-rs/serde
• tokio → https://github.com/tokio-rs/tokio
• axum → https://github.com/tokio-rs/axum
• tracing → https://github.com/tokio-rs/tracing
• thiserror → https://github.com/dtolnay/thiserror

Dependencies must be justified.

---

10. Documentation Requirements

Public APIs MUST include:

• /// doc comments
• Usage example
• Error behavior explanation

Reference: https://github.com/rust-lang/api-guidelines

---

11. Testing Requirements

Generated code SHOULD include:

• Unit tests
• Error case tests
• Edge case validation

---

12. Output Contract (MANDATORY)

LLM-generated code MUST:

• Compile successfully
• Pass cargo fmt
• Pass cargo clippy -D warnings
• Contain no unwrap()
• Contain no unused warnings