| name | rust-architecture-guide |
| description | Comprehensive Rust engineering guide covering priority pyramid, architecture decisions, idiomatic coding style, memory layout transparency, breakwater pattern, and physical feasibility audit. Invoke when starting Rust projects, making trade-offs, writing idiomatic code, or designing system architecture. Based on Jeet Kune Do philosophy — intercept boilerplate, flow with hardware, fold logic to maximum energy density, unity of false and real. |
| license | MIT |
| metadata | {"version":"9.1.0","philosophy":"Dialectical Materialism & Jeet Kune Do — Unity of False and Real","domain":"general Rust engineering","author":"rust-architect","rust_edition":"2024","aligned_with":["Rust API Guidelines","Rust 2024 Edition","Tokio Best Practices","Clippy pedantic/nursery","Safety-Critical Rust Coding Guidelines"]} |
Rust Architecture & Engineering Decision Guide V9.1.0 — The Rust 2024 Edition
This document serves as the constitutional foundation for Rust engineering decisions. It is structured for deterministic, reproducible decision-making suitable for AI-assisted development.
V9.0.0 introduced three paradigm shifts:
- Memory Layout Transparency (ref/30): From "ideological safety" to "materialist physics" — struct padding audit,
#[repr(C)] mandate, cache-friendly design
- Breakwater Architecture (ref/31): Facade/Core layered pattern — ergonomic facade absorbs chaos, zero-overhead core maintains determinism
- Physical Feasibility Audit (ref/32): Mandatory audit between initiation and design — I/O budget, memory ceiling, concurrency true cost
V9.1.0 — Rust 2024 Edition Alignment:
- Adopts Rust 2024 Edition idioms:
unsafe extern blocks, RPIT lifetime capture, impl Trait in return position sugar
- Aligns with Rust API Guidelines checklist (C-CASE, C-CONV, C-MACRO-VIS, C-EXAMPLE)
- Integrates Safety-Critical Rust Coding Guidelines for unsafe code governance
- Adds
cargo-mutants mutation testing, kani formal verification, turmoil network chaos to advanced testing arsenal
Execution Mode
Before applying any rule, determine the execution mode:
rapid (prototype): Enforce P0 only; anyhow in libraries, unlimited .clone(), no doc-testsstandard (default): Enforce P0+P1; warn on P2 violationsstrict (production): Enforce P0-P3; all deviations require formal annotation
See references/00-mode-guide.md for full mode definitions.
Mandatory Output Contract
Every code generation or review output MUST end with a Decision Summary block:
## Decision Summary
- **Mode**: [rapid|standard|strict]
- **Edition**: [2021|2024] — Rust edition in use
- **Rules Applied**: [list specific rules from P0-P3]
- **Conflicts Resolved**: [PX > PY with justification, or "None"]
- **Deviations**: [list with `// DEVIATION: reason` references, or "None"]
- **Trade-offs**: [key trade-off decisions made]
- **External Alignment**: [relevant Rust API Guidelines / Safety-Critical guidelines matched]
1. Priority Decision Matrix
When conflicts arise, apply decisions top-down. Upper levels have absolute veto power.
| Level | Core Principle | Accept | Reject |
|---|
| P0 | Safety & Correctness | Compile-time borrow checking, Miri-verified unsafe | Any UB, race conditions, unproven unsafe |
| P1 | Maintainability | Semantic naming, ownership transfer, trait decoupling | Deeply nested lifetimes, overly complex generics |
| P2 | Engineering Efficiency | Box<dyn Trait>, workspace division, feature isolation | Binary bloat from monomorphization |
| P3 | Runtime Performance | SoA layout, lock-free, SIMD, profiling-proven | Intuition-based premature optimization |
2. Ownership & Memory Architecture Strategy
Business Logic Layer
- Prefer owned types (
String, Vec<T>)
- Allow
.clone() to eliminate lifetime interference on non-hotpaths
- Prohibit storing non-
'static references in structs, unless struct is transient view
Performance Hotpaths Layer
- Zero-Copy Design:
Cow<'a, T> or bytes::Bytes for cross-layer sharing
- Memory Layout: Enforce AoS → SoA conversion for bulk data
- Alignment:
#[repr(align(64))] to eliminate false sharing
3. Error Handling Layering Specification
Library Crate
- Required:
thiserror or manual Display + Error trait
- Prohibited: Never return
anyhow::Error from public API
- Error variants must contain sufficient context
Application Binary
- Use
anyhow with ? operator for error propagation
- Attach
.with_context(|| ...) at error propagation points
- Register global Panic Hook at
main entry
4. Idiomatic Style: Jeet Kune Do Coding Philosophy
Core Philosophy
| Principle | Description |
|---|
| Intercepting Boilerplate | If logic can be expressed in 1 line of pattern matching, never use 5 lines of nesting |
| Economy of Motion | Every line of code should point directly to intent. Eliminate redundant intermediate variables and implicit copies |
| Hardware Sympathy | Leverage iterators and zero-copy types, align with the compiler's inline optimization |
Agent Self-Check List
- Are code paths flat? Can
let else or ? eliminate if let nesting?
- Are manual loops eliminated? Can collection processing be converted to iterator adapter chains?
- Are variable scopes minimized? Can shadowing remove no-longer-needed
mut?
- Are there implicit copies? Is
.to_string() or .clone() misused on hot paths?
- Is naming stuttering? e.g.,
user::UserConfig should be user::Config.
- Is Rust 2024 Edition leveraged? Are
unsafe extern blocks used? Are RPIT captures explicit with use<...>?
- Are Clippy pedantic/nursery lints addressed? For
strict mode, no unjustified #[allow] on pedantic lints.
Reduction Directive
When receiving a Rust coding task, fold the logic with Jeet Kune Do intuition before output — ensuring every line of code carries maximum energy density. The goal is high signal-to-noise ratio.
5. Agent Execution & Self-Review Directives
MUST execute the following workflow before outputting any Rust solution:
Trade-off Analysis
Review Checklists
- Ownership: Unnecessary lifetime annotations removed? Large objects boxed before
.await?
- Concurrency:
std::sync::Mutex held during await? Blocking ops in async context?
- Error Robustness: All
unwrap() have expect("REASON")? External IO handles timeout?
- Safety: Unsafe blocks have SAFETY comments? FFI uses opaque handles?
catch_unwind on extern "C"?
6. Typical Refactoring Paths
| From | To | Signal |
|---|
Option/bool flags | Enum state machine | Business model stabilizing |
String storage | Cow<'a, str> or Arc<str> | Hot path optimization needed |
Manual for loops | Iterator chaining | Collection processing code |
MVP Option fields | Type-driven state machine | Core domain logic stable |
7. Production Observability Specification
- Tracing: All
pub async fn annotated with #[tracing::instrument]; skip large objects
- Metrics: Static labels; atomic counters on hot paths; Prometheus pull model
- Panic Hook: Global hook at
main; synchronous write; std::process::abort() over unwinding
8. Reference Files
Document Relationship Map
flowchart TD
SKILL[SKILL.md<br/>Constitutional Foundation] --> Mode[00-mode-guide.md<br/>Execution Modes]
SKILL --> Pyramid[01-priority-pyramid.md<br/>P0-P3 Hierarchy]
Pyramid --> Conflict[02-conflict-resolution.md<br/>Conflict Scenarios]
Pyramid --> Concurrency[11-concurrency.md<br/>Lock Spectrum]
Mode --> Progressive[03-progressive-architecture.md<br/>MVP → Production]
Mode --> Deviation[06-deviation-process.md<br/>Rule Exceptions]
Concurrency --> StateMachine[07-state-machine.md<br/>Type-Driven States]
Concurrency --> Async[12-async-internals.md<br/>Pin/Unpin/Waker]
Async --> CloudInfra[Cloud Infra Guide<br/>Vertical Deepening]
Pyramid --> DataArch[09-data-architecture.md<br/>Zero-Copy Principles]
DataArch --> Performance[25-performance-tuning.md<br/>Mechanical Sympathy]
StateMachine --> Newtype[08-newtype.md<br/>Semantic IDs]
Conflict --> Tradeoffs[04-trade-offs.md<br/>Decision Framework]
style SKILL fill:#4a90d9,stroke:#2c5aa0,color:#fff
style Pyramid fill:#5cb85c,stroke:#4cae4c,color:#fff
style Concurrency fill:#f0ad4e,stroke:#ec971f,color:#000
style CloudInfra fill:#d9534f,stroke:#c9302c,color:#fff
Execution & Strategy (7)
Architecture Patterns (14)
Modern CI & Formal Methods (V9.1.0 additions)
-
33-ci-modern.md — Modern CI/CD pipeline: cargo-mutants, kani, turmoil, deterministic RNG, rust-toolchain.toml
-
Memory Layout Transparency (P0)
- 30-memory-layout.md — Struct padding audit,
#[repr(C)] mandate, cache-friendly design, false sharing prevention
-
Breakwater Architecture (P0-P1)
-
Physical Feasibility Audit (P0)
- 32-physical-audit.md — Pre-design mandatory audit: I/O budget, memory ceiling, concurrency true cost
Idiomatic Style (7)
- 18-control-flow.md —
let else, matches!, intercepting deep nesting
- 19-iterators.md — Iterator chains,
filter_map, flowing force
- 20-traits.md —
From vs Into, Default, Hardware Sympathy
- 21-errors.md —
unwrap_or_else, map_err, and_then
- 22-data-struct.md — Field shorthand, type stuttering
- 23-borrowing.md —
AsRef, Cow, memory economy
- 24-refactor.md — Agent Self-Check List, Reduction Directive
Deep Dive (P3 Only)
⚠️ Requirement: All P3 optimizations MUST include profiler data proving bottleneck
9. Constitutional Summary
No rule is absolute. The ultimate measure of code quality is whether it matches:
- Its lifecycle stage (MVP vs production) — governed by execution mode
- Business constraints (deadline vs long-term maintenance)
- Team context (solo vs large organization)
The Pragmatic Principle:
Pursue excellence at system boundaries and hot paths; release mental load for internal flows and cold paths.
Deviation Protocol: When breaking a rule is the correct decision, annotate with // DEVIATION: reason and record in the Decision Summary.
Terminology: All specialized terms are defined in glossary.md.
Remember: This guide is the Agent's constitutional foundation. Before each response, generate a Decision Summary recording rationale for choosing specific implementation paths, ensuring consistency and professional depth.
