rust-systems

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

| 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