RUST_RULES.md

RUST_RULES.md

Rust Agent Guidelines

Code Quality

• Never use panic!, unwrap(), or expect() in production code.
• Always handle errors explicitly using Result or Option.

Clippy

• Run with strict pedantic linting enabled.
• Follow all clippy suggestions without adding #[allow] directives.
• Project-specific strictness is configured in clippy.toml or Cargo.toml.

Formatting and Sorting

• Format all code: cargo fmt --all
• Sort imports: cargo sort --grouped

Dependencies

• Use the latest minor version for all dependencies.
• GOOD: version = "1.0"
• BAD: version = "1" or version = "1.0.123"

Path Preferences

• Prefer core:: over std:: when possible.
• Prefer crate:: over super:: for project modules.

Import Style

• All imports must be at the top of the file, before any code.
• Use long paths in imports, short paths in code:
  • GOOD: use std::collections::HashMap; and let m = HashMap::new();
  • BAD: let m = std::collections::HashMap::new();
• More relaxed for function calls: let a = std::thread::spawn(); is acceptable.

Trait Usage

• Use idiomatic traits for conversions:
  • From for infallible conversions.
  • TryFrom for fallible conversions.
• Avoid creating custom conversion functions when traits would be more appropriate.

Type Name Aliasing

When type names conflict, use use aliases following this priority order:

1. std (highest priority)
2. Third-party crates
3. Project crates (lowest priority)

use somecrate::HashMap as NewHashMap;

Performance Style

• Prefer references (&T, &mut T) over passing values by default.
• Minimize cloning; prefer borrowing or Cow<'a, T> for copy-on-write semantics.
• Ergonomic over performance if the trade-off is not worth the complexity:
  • GOOD: Use String when Cow<'a, str> would require awkward code.
  • GOOD: Use Cow<'a, str> when you can pay the ergonomics cost for zero-copy.

File Structure

Organize Rust source files in this order:

1. const - associated constants
2. Type definitions - structs, enums, unions, type aliases
3. impl std traits - Display, Debug, Clone, Copy, etc.
4. impl 3rd party crate traits - traits from dependencies
5. impl project traits - traits defined in this project
6. impl blocks - custom methods for the type
7. functions - free/public helper functions
8. tests - #[cfg(test)] module with unit tests

// 1. const
impl MyType {
    pub const MAX_VALUE: i32 = 100;
}

// 2. Type definition
pub struct MyType {
    field: i32,
}

// 3. impl std traits
use std::fmt::{Display, Formatter, Result};

impl Display for MyType {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        write!(f, "{}", self.field)
    }
}

// 4. impl 3rd party trait
use SomeCrate::Serializable;

impl Serializable for MyType { ... }

// 5. impl project trait
use crate::traits::Validatable;

impl Validatable for MyType { ... }

// 6. impl blocks (custom methods)
impl MyType {
    pub fn new() -> Self { Self { field: 0 } }
}

// 7. functions
pub fn helper_function() { ... }

// 8. tests
#[cfg(test)]
mod tests {
    use crate::MyType;

    #[test]
    fn test_something() { ... }
}