Rust Systems Programming Best Practices

Comprehensive Rust patterns and style conventions for systems programming, containing 52 rules across 5 categories. Designed for systems programming, CLI tools, and performance-critical applications.

When to Apply

Reference these guidelines when:

• Writing new Rust code or modules
• Organizing Rust project structure
• Defining custom types, traits, or error handling
• Reviewing Rust code for style consistency
• Building systems tools, CLIs, or daemon processes

Rule Categories by Priority

Quick Reference

1. Project Organization (HIGH)

• org-cargo-workspace – Use Cargo Workspace for Multi-Crate Projects
• org-directory-naming – Use snake_case for All Directory Names
• org-binary-library-separation – Separate Binary and Library Crates
• org-feature-domain-grouping – Group Crates by Feature Domain
• org-common-crate – Use Dedicated Common Crate for Shared Utilities
• org-flat-crate-structure – Keep Crate Structure Flat

2. Module Structure (HIGH)

• mod-explicit-declarations – Use Explicit Module Declarations in lib.rs
• mod-colocated-tests – Co-locate Tests as test.rs Files
• mod-submodule-organization – Use mod.rs for Multi-File Modules
• mod-types-errors-files – Separate Types and Errors into Dedicated Files
• mod-reexport-pattern – Use pub use for Clean API Re-exports
• mod-conditional-compilation – Use cfg Attributes for Conditional Modules

3. Naming Conventions (HIGH)

• name-function-snake-case – Use snake_case for Functions and Methods
• name-type-pascal-case – Use PascalCase for Types
• name-constant-screaming – Use SCREAMING_SNAKE_CASE for Constants
• name-getter-prefix – Prefix Getter Functions with get_
• name-boolean-predicates – Use is_, has_, should_ for Boolean Predicates
• name-constructor-new – Use new for Constructors
• name-conversion-to-from – Use to_ and from_ for Conversions
• name-type-suffixes – Use Descriptive Suffixes for Type Specialization
• name-field-unit-suffixes – Include Unit Suffixes in Field Names
• name-module-snake-case – Use snake_case for Module Names
• name-generic-parameters – Use Descriptive or Single-Letter Generic Parameters
• name-lifetime-parameters – Use Single Lowercase Letters for Lifetimes
• name-test-files – Name Test Files as test.rs

4. Type & Trait Patterns (HIGH)

• type-option-nullable-fields – Use Option for Nullable Fields
• type-standard-derives – Use Consistent Derive Order for Data Structs
• type-builder-pattern – Use Builder Pattern with Method Chaining
• type-associated-types – Use Associated Types for Related Type Relationships
• type-phantom-data – Use PhantomData for Unused Generic Parameters
• type-newtype-pattern – Use Newtype Pattern for Type Safety
• type-enum-copy-simple – Derive Copy for Simple Enums
• type-enum-variants – Use Enums for Type-Safe Variants
• type-trait-impl-grouping – Group Related Trait Implementations Together
• type-bitflags – Use bitflags! for Type-Safe Bit Flags
• type-operator-overload – Implement Operator Traits for Domain Types
• type-public-fields – Use Public Fields for Data Structs
• type-async-trait – Use async_trait for Async Trait Methods
• type-boxed-trait-objects – Use Box for Runtime Polymorphism
• type-type-aliases – Use Type Aliases for Complex Generics

5. Error Handling (HIGH)

• err-thiserror-enum – Use thiserror for Custom Error Types
• err-result-alias – Define Module-Local Result Type Alias
• err-path-context – Include Path Context in IO Errors
• err-anyhow-context – Use context() and with_context() for Error Messages
• err-bail-validation – Use bail! for Validation Failures
• err-graceful-degradation – Use Graceful Degradation for Non-Critical Operations
• err-panic-unrecoverable – Reserve panic! for Unrecoverable Situations
• err-expect-message – Use expect() with Descriptive Messages
• err-source-attribute – Use #[source] for Error Chaining
• err-ok-or-else – Use ok_or_else for Expensive Error Construction
• err-two-tier-strategy – Use Two-Tier Error Strategy

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions – Category structure and impact levels
• Rule template – Template for adding new rules

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md