AgentSkillsCN

Expert Rust Skill

编写符合 Rust 语言习惯、兼具高性能与安全性代码的指导方针、模式与最佳实践。

SKILL.md
--- frontmatter
name: Expert Rust Skill
description: Instructions, patterns, and best practices for writing idiomatic, high-performance, and safe Rust code.

Expert Rust Skill

This skill serves as a guide for writing production-grade Rust code, focusing on safety, concurrency, and idiomatic patterns.

1. Ownership & Memory Management

  • •Borrowing: Prefer borrowing (&T, &mut T) over taking ownership when data doesn't need to be consumed.
  • •Cloning: Be explicit with .clone(). Avoid it in hot paths unless necessary. Use Arc<T> for shared ownership across threads/tasks.
  • •Lifetimes: Explicitly strictly define lifetimes 'a only when the compiler cannot infer them.

2. Error Handling

  • •Result & Option: Never use .unwrap() or .expect() in production code unless you have proof that it will never panic (and comment that proof).
  • •Propagation: Use the ? operator to propagate errors.
  • •Crates:
    • •Use thiserror for library error definitions (enum implementation).
    • •Use anyhow for application-level error handling and context (.context("...")).

3. Concurrency & Async

  • •Runtime: Use tokio for async operations.
  • •Send & Sync: Ensure types passed across thread/task boundaries implement Send (and Sync if shared).
  • •Blocking: NEVER block the async runtime thread. Use tokio::task::spawn_blocking for CPU-intensive or synchronous I/O operations.
  • •Synchronization: Use tokio::sync::Mutex for async critical sections, but prefer message passing (tokio::sync::mpsc) via channels over shared state where possible.

4. Type System & Traits

  • •Newtypes: Use the "Newtype" pattern (struct ID(String)) to enforce type safety and avoid primitives obsession.
  • •Traits: Prefer defining behavior via Traits. Use impl Trait for return types to reduce signature complexity.
  • •Generics: Use Generics with trait bounds (T: AsRef<Path>) to increase API flexibility.

5. Idiomatic Rust

  • •Clippy: Always respect cargo clippy. Treat warnings as errors.
  • •Formatting: Run cargo fmt automatically.
  • •Iterators: Prefer functional iterator chains (.map(), .filter(), .collect()) over raw for loops for readability and potential compiler optimizations.
  • •Pattern Matching: Use match with exhaustive patterns. Use if let for single pattern handling.

6. Testing

  • •Unit Tests: Place unit tests in the same file mod tests { ... }.
  • •Integration Tests: Place integration tests in tests/ directory.
  • •Doc Tests: Write examples in documentation comments (///) which serve as tests.

7. Performance

  • •Allocations: Minimize heap allocations. Use &str instead of String when possible.
  • •Data Structures: Choose the right container (e.g., HashMap, BTreeMap, Vec) based on access patterns.
  • •Buffering: Use BufReader/BufWriter for I/O operations to reduce syscalls.