preferences-rust-development

name	preferences-rust-development
description	Rust development conventions covering domain modeling, error handling, API design, testing, performance, and type-level programming. Load when working with .rs files or Rust projects.

Rust development

This guide integrates functional domain modeling (FDM) with pragmatic Rust practices from Microsoft engineers.

Primary lens: Functional domain modeling - type-driven design encoding business logic in the type system, making invariants explicit and violations compile-time errors.

Complementary guidance: Microsoft Pragmatic Rust Guidelines - industry best practices for API design, testing, performance, and safety.

Philosophical reconciliations:

• Panic semantics: Panics for true programming bugs only (contract violations, impossible states). Domain and infrastructure errors use Result types. Good type design reduces both panic surface and error handling complexity.
• Dependency injection: Prefer concrete types for domain logic, enums for testable I/O (sans-io), generics for algorithm parameters, dyn Trait only for true runtime polymorphism. This hierarchy complements FDM's emphasis on explicit, type-safe dependencies.
• Type-driven design: Both approaches emphasize making invalid states unrepresentable. Smart constructors, state machines, and strong types eliminate bug categories.

Role in multi-language architectures: Rust often serves as the base IO/Result layer in multi-language monad transformer stacks, providing memory-safe, high-performance foundations for effect composition.

Contents

This guide is organized into focused topic files for easy navigation and AI agent efficiency.

File	Description
01-functional-domain-modeling.md	Core FDM patterns: smart constructors, state machines, workflows, aggregates, error classification; advanced patterns: phantom types, const generics, NonEmpty collections; Pattern 6: The Decider pattern (fmodel-rust) for event-sourced command handling
02-error-handling.md	Canonical error structs, thiserror/anyhow/miette, Result composition, railway-oriented programming, applicative validation, #[must_use] enforcement
03-panic-semantics.md	When to panic vs return Result, programming bugs vs domain errors
04-api-design.md	Naming, dependency injection hierarchy, builders, sans-io pattern, serialization boundaries, command/event struct patterns
05-testing.md	Mockable I/O, property-based testing, feature-gated test utilities
06-documentation.md	Canonical doc sections, module docs, doc tests
07-performance.md	Hot paths, throughput optimization, async yield points, allocators
08-structured-logging.md	Tracing, message templates, OpenTelemetry conventions
09-unsafe-code.md	Validation requirements, Miri testing, soundness guarantees
10-tooling.md	Code quality, linting, dependency management
11-concurrency.md	Capability-secure concurrency: deny capabilities, actor patterns, channel primitives, structured concurrency
12-distributed-systems.md	Distributed patterns: idempotency keys, saga orchestration, transactional outbox, event sourcing integration
13-type-level-programming.md	Strategic library extensions: typenum, frunk, nutype for type-level programming; compile-time assertions; anti-patterns to avoid

References

Primary sources

This document integrates guidance from:

• Functional domain modeling: See ~/.claude/skills/preferences-domain-modeling/SKILL.md for universal patterns, ~/.claude/skills/preferences-architectural-patterns/SKILL.md for application structure, ~/.claude/skills/preferences-railway-oriented-programming/SKILL.md for error composition
• Microsoft Pragmatic Rust Guidelines: https://microsoft.github.io/rust-guidelines/agents/all.txt - comprehensive production Rust guidance from Microsoft engineers
• Rust API Guidelines: https://rust-lang.github.io/api-guidelines/ - official Rust API design checklist

Related documents

• ~/.claude/skills/preferences-distributed-systems/SKILL.md - universal distributed systems decision framework
• ~/.claude/skills/preferences-theoretical-foundations/SKILL.md - category-theoretic underpinnings
• ~/.claude/skills/preferences-algebraic-data-types/SKILL.md - sum/product type patterns