| 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 discharging the lowest capability interface in a multi-language architecture, providing memory-safe, high-performance foundations for effect composition.
A transformer stack is only one (leaky) interpreter of such an interface, never the interface itself; see preferences-theoretical-foundations, its effects-handlers reference, for why a capability interface discharged by handlers, not a transformer tower, is the primitive.
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- preferences-theoretical-foundations - category-theoretic underpinnings
~/.claude/skills/preferences-algebraic-data-types/SKILL.md - sum/product type patterns
