rust-systems

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

Priority	Category	Impact	Prefix
1	Project Organization	HIGH	org-
2	Module Structure	HIGH	mod-
3	Naming Conventions	HIGH	name-
4	Type & Trait Patterns	HIGH	type-
5	Error Handling	HIGH	err-

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