cursor-rust-rules/specs/rust-rules-improvement-plan.md

Rust Rules Improvement Plan

Executive Summary

After analyzing the existing Rust rule sets and extensive real-world usage patterns, I've identified several common patterns and gaps that warrant updates to our Rust coding standards. This plan outlines specific improvements to existing rules and proposes new rule sets for configuration management and observability.

Current Rule Analysis

Strengths of Existing Rules

• Comprehensive coverage: Core areas (code quality, dependencies, design patterns, performance) are well-covered
• Practical examples: Good balance of theoretical guidance and concrete code examples
• Workspace architecture: Excellent multi-crate organization guidance
• Modern Rust idioms: Rules emphasize Rust 2024 edition and best practices

Identified Gaps from Real-World Usage

From analyzing common patterns in modern Rust applications, several areas need better coverage:

1. Configuration Management - Multi-format config parsing, validation, and runtime updates
2. Observability Patterns - Real-time metrics collection and distributed tracing
3. Service Architecture - Async service orchestration and middleware patterns
4. Frontend Integration - Embedded web assets and API integration patterns

Proposed Rule Updates

1. Enhanced Workspace Architecture Rules

File: .cursor/rules/rust/complex/workspace.mdc

Changes:

• Add service-oriented architecture patterns
• Include plugin architecture examples for extensible systems
• Add configuration hot-reloading patterns

New Example Pattern:

// Service-oriented architecture with shared state
pub struct ServiceManager<T> {
    config: Arc<ArcSwap<T>>,
    components: Vec<Arc<dyn ServiceComponent>>,
}

impl<T> ServiceManager<T> {
    pub fn update_config(&self, new_config: T) {
        self.config.store(Arc::new(new_config));
        // Notify components of config change
        for component in &self.components {
            component.on_config_update();
        }
    }
}

pub trait ServiceComponent: Send + Sync {
    fn on_config_update(&self);
}

2. New Configuration Management Rules

New File: .cursor/rules/rust/features/configuration.mdc

Purpose: Comprehensive configuration management patterns

Key Sections:

• Multi-format parsing (YAML, TOML, JSON)
• Configuration validation with compile-time guarantees
• Environment-based overrides
• Configuration watching with filesystem events

Example Pattern:

#[derive(Debug, Clone, Deserialize, Validate)]
pub struct AppConfig {
    #[validate(length(min = 1))]
    pub name: String,

    #[validate(range(min = 1, max = 65535))]
    pub port: u16,

    #[serde(default)]
    pub features: Vec<String>,
}

pub struct ConfigManager<T> {
    current: Arc<ArcSwap<T>>,
    reload_tx: mpsc::Sender<ConfigReload>,
}

3. New Observability Rules

New File: .cursor/rules/rust/features/observability.mdc

Purpose: Real-time metrics collection and observability patterns

Key Patterns:

• Lock-free counter implementation for high-throughput scenarios
• Metrics collection with proper aggregation
• Distributed tracing patterns
• Health check implementations

Example:

// Lock-free metrics for high-performance scenarios
pub struct AtomicCounter {
    value: AtomicU64,
}

impl AtomicCounter {
    pub fn increment(&self) -> u64 {
        self.value.fetch_add(1, Ordering::Relaxed)
    }

    pub fn get(&self) -> u64 {
        self.value.load(Ordering::Relaxed)
    }
}

// Metrics collection pattern
pub struct MetricsCollector {
    counters: DashMap<String, AtomicCounter>,
    histograms: DashMap<String, Histogram>,
}

4. Updated Dependency Management Rules

File: .cursor/rules/rust/core/dependencies.mdc

Additions:

• Configuration management dependencies
• Observability dependency patterns
• Frontend integration dependencies

New Section: Common Service Dependencies

# Configuration management
figment = { version = "0.10", features = ["yaml", "toml", "env"] }
notify = "6.0"  # File watching
arc-swap = "1.0"  # Atomic updates
validator = { version = "0.18", features = ["derive"] }

# Observability
prometheus = "0.13"
opentelemetry = "0.23"
tracing-opentelemetry = "0.23"
dashmap = "6.0"  # Concurrent collections

# Frontend integration
rust-embed = "8.0"  # Static asset embedding
mime_guess = "2.0"  # MIME type detection

Implementation Priority

Phase 1: Critical Updates (High Impact, Common Patterns)

1. Configuration Management Rules - Most frequently used pattern
2. Observability Rules - Essential for production systems
3. Enhanced Workspace Architecture - Service-oriented patterns

Phase 2: Refinements (Medium Impact)

1. Updated Dependency Management - New common dependencies
2. Documentation Updates - Ensure all examples are current

Common Best Practices Identified

From analyzing real-world usage, these patterns appear frequently and should be emphasized:

1. Configuration Management

• Multi-format support with validation
• Environment-based overrides
• Atomic configuration updates using arc-swap

2. Observability

• Lock-free data structures for metrics
• Structured logging with context
• Health check patterns for services

3. Service Architecture

• Trait-based components for extensibility
• Shared state management with atomic updates
• Graceful shutdown with signal handling

4. Error Handling

• Contextual errors with detailed information
• Error propagation patterns
• Retry patterns with exponential backoff

5. Testing Strategies

• Integration testing with real services
• Configuration testing with multiple formats
• Metrics testing with mock collectors

Success Metrics

To measure the effectiveness of these rule updates:

1. Developer Velocity: Faster onboarding for Rust projects
2. Code Quality: Reduced bugs in configuration and observability code
3. Consistency: More uniform patterns across projects
4. Maintainability: Better separation of concerns and testability

Conclusion

These rule updates codify common patterns that have emerged from real-world Rust development, particularly in service-oriented applications. The focus on configuration management and observability addresses critical needs in modern applications while maintaining the high standards of the existing rule set.