Imported from David-Li0406/meta-skill-evloving (skill-flow/data/skills-refined-36k/skillsmp/rust-5/AGENTS.md). Install upstream with npx skills add David-Li0406/meta-skill-evloving --skill rust-5. Copyright stays with the author.

Rust

Version 0.1.0
Community
January 2026

Note: This document is for agents and LLMs working with Rust code. It provides guidelines for maintaining, generating, or refactoring Rust codebases. Humans may also find it useful, but guidance is optimized for AI-assisted workflows.

Abstract

Comprehensive performance optimization guide for Rust applications, designed for AI agents and LLMs. Contains 42+ rules across 8 categories, prioritized by impact from critical (memory allocation, ownership patterns) to incremental (micro-optimizations). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.

Table of Contents

1. Memory Allocation — CRITICAL
   • 1.1 Avoid format! for Simple Concatenation — CRITICAL (eliminates allocation for string literals)
   • 1.2 Avoid Unnecessary Clone Calls — CRITICAL (eliminates heap allocations per call)
   • 1.3 Preallocate Vec Capacity — CRITICAL (reduces allocations by 3-5× for growing vectors)
   • 1.4 Use Arc for Shared Immutable Data — CRITICAL (eliminates N clones for N readers)
   • 1.5 Use Cow for Conditional Ownership — CRITICAL (avoids allocation in read-only path)
   • 1.6 Use SmallVec for Small Collections — CRITICAL (eliminates heap allocation for typical cases)
2. Ownership & Borrowing — CRITICAL
   • 2.1 Accept &[T] Instead of &Vec — CRITICAL (eliminates allocation for array callers)
   • 2.2 Accept &str Instead of &String — CRITICAL (eliminates allocation for &str callers)
   • 2.3 Return Borrowed Data When Possible — CRITICAL (eliminates allocation for accessor methods)
   • 2.4 Use AsRef for Generic Borrows — CRITICAL (eliminates allocation for borrowed callers)
   • 2.5 Use Into for Flexible Ownership Transfer — CRITICAL (avoids allocation when caller already owns data)
3. Data Structure Selection — HIGH
   • 3.1 Use BTreeMap for Sorted Iteration — HIGH (avoids O(n log n) sort after each insertion)
   • 3.2 Use Entry API for Conditional Insert — HIGH (single lookup instead of two)
   • 3.3 Use HashMap for Key-Value Lookups — HIGH (O(n) to O(1) per lookup)
   • 3.4 Use HashSet for Membership Tests — HIGH (O(n) to O(1) per lookup)
   • 3.5 Use VecDeque for Queue Operations — HIGH (O(n) to O(1) for front operations)
4. Iterator & Collection Patterns — HIGH
   • 4.1 Chain Iterators Instead of Intermediate Collect — HIGH (eliminates intermediate allocations)
   • 4.2 Use extend() for Bulk Append — HIGH (single reallocation instead of N)
   • 4.3 Use filter_map for Combined Filter and Map — HIGH (single pass instead of two)
   • 4.4 Use flat_map for Nested Iteration — HIGH (avoids nested loops and intermediate collections)
   • 4.5 Use fold() for Complex Accumulation — HIGH (single pass with custom accumulator)
   • 4.6 Use iter() Over into_iter() When Borrowing — HIGH (preserves original collection)
5. Async & Concurrency — MEDIUM-HIGH
   • 5.1 Avoid Blocking in Async Context — MEDIUM-HIGH (prevents executor starvation)
   • 5.2 Avoid Holding Lock Across await Points — MEDIUM-HIGH (prevents deadlocks and starvation)
   • 5.3 Minimize Lock Scope — MEDIUM-HIGH (reduces contention time)
   • 5.4 Use buffered() for Bounded Concurrency — MEDIUM-HIGH (prevents resource exhaustion)
   • 5.5 Use join! for Concurrent Futures — MEDIUM-HIGH (2-5× faster for multiple independent operations)
   • 5.6 Use RwLock Over Mutex for Read-Heavy Workloads — MEDIUM-HIGH (2-10× throughput for read-heavy workloads)
6. Algorithm Complexity — MEDIUM
   • 6.1 Avoid Nested Loops for Lookups — MEDIUM (O(n×m) to O(n+m))
   • 6.2 Use Binary Search for Sorted Data — MEDIUM (O(n) to O(log n))
   • 6.3 Use chunks() for Batch Processing — MEDIUM (reduces overhead per element)
   • 6.4 Use select_nth_unstable for Partial Sorting — MEDIUM (O(n log n) to O(n) for finding kth element)
   • 6.5 Use sort_unstable When Order of Equal Elements Is Irrelevant — MEDIUM (10-30% faster sorting)
7. Compile-Time Optimization — MEDIUM
   • 7.1 Avoid Repeated Parsing of Static Data — MEDIUM (100-1000× speedup for repeated operations)
   • 7.2 Prefer Static Dispatch Over Dynamic Dispatch — MEDIUM (enables inlining and eliminates vtable lookup)
   • 7.3 Reduce Monomorphization Bloat — MEDIUM (smaller binaries, better instruction cache usage)
   • 7.4 Use const for Compile-Time Computation — MEDIUM (eliminates runtime computation entirely)
   • 7.5 Use Const Generics for Array Sizes — MEDIUM (eliminates runtime bounds checks)
8. Micro-optimizations — LOW
   • 8.1 Apply inline Attribute to Small Hot Functions — LOW (eliminates function call overhead)
   • 8.2 Avoid Bounds Checks in Hot Loops — LOW (eliminates branch per iteration)
   • 8.3 Use Byte Literals for ASCII Operations — LOW (avoids char-to-byte conversion)
   • 8.4 Use Wrapping Arithmetic When Overflow Is Expected — LOW (eliminates overflow check overhead)

References

1. https://nnethercote.github.io/perf-book/
2. https://rust-lang.github.io/api-guidelines/
3. https://doc.rust-lang.org/nomicon/
4. https://doc.rust-lang.org/book/
5. https://tokio.rs/tokio/tutorial
6. https://doc.rust-lang.org/reference/behavior-considered-undefined.html
7. https://www.scylladb.com/2022/01/12/async-rust-in-practice-performance-pitfalls-profiling/
8. https://rustc-dev-guide.rust-lang.org/

Source Files

This document was compiled from individual reference files. For detailed editing or extension: