Skip to main content
rule CX Codex

rust · microsoft — Claude Code rule: what it does, how to install

Enforces Rust 2021 conventions in Claude Code, covering crate layout, Cargo release settings, thiserror patterns, and Tokio runtimes.

MIT ★ 1,627 updated 2026-10-25

Install into GitHub Copilot · Manually: put the files in place All methods and platforms ↓
.github/instructions/rust.instructions.md
Open on GitHub

What rust does

This rule targets all **/*.rs files across the workspace. It specifies standard crate layouts, internal module member ordering, and naming suffixes like *Error and *Builder. It also defines an optimized release profile for Cargo.toml using strip = true, lto = true, and panic = "abort".

Error handling conventions are explicit. Domain modules and libraries must structure variants using thiserror, restricting anyhow to CLI tools and root main functions. Production code paths completely forbid unwrap() or expect(). Those panic methods are kept exclusively for initialization routines like reading bootstrap configuration.

For asynchronous code, the guide mandates the Tokio runtime. It directs the agent to select either the standard multi-threaded engine or the resource-friendly current_thread flavor.

What it helps with

  • standardize Rust crate folder layouts and module member order
  • configure Cargo release profiles to minimize binary size
  • enforce typed errors with thiserror instead of unwrap calls
  • set up multi-threaded or single-threaded Tokio async runtimes

Example prompts for the agent

  • Generate an error enum using thiserror with a module-level Result alias
  • Configure the Cargo.toml release profile for optimized production builds
  • Set up a lightweight async entry point with the current_thread Tokio flavor

How to install rust

Manually: put the files in place

.github/instructions/rust.instructions.md

The applyTo field sets which files it applies to

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about rust

How to install rust in Claude Code?

Place the rule file at .claude/rules/rust.md in your repository root.

What conventions does this rule set?

It establishes Rust 2021 edition conventions for file trees, module organization, dependency pinning, and async architectures.

Where are unwrap() and expect() permitted by this rule?

They are allowed solely in startup code, including initial configuration parsing in main or inside OnceLock and LazyLock definitions.

Source text

rust.instructions.md · MIT
---
applyTo: '**/*.rs'
description: 'Rust code authoring conventions'
---

# Rust Instructions

Conventions for Rust development targeting the 2021 edition.

## Project Structure

Crates follow a standard layout:

```text
Cargo.toml
Cargo.lock
src/
  main.rs           # Binary crate entry point
  lib.rs            # Library crate root
  module_name.rs    # Top-level module
  module_name/
    mod.rs           # Module with submodules
    submodule.rs
tests/
  integration_test.rs
```

* `Cargo.toml` and `Cargo.lock` at crate root.
* Commit `Cargo.lock` for binary crates to ensure reproducible builds. Exclude it from version control for library crates.
* `src/` contains all source files.
* Binary crates use `main.rs`; library crates use `lib.rs`.
* Test projects use a sibling `tests/` directory for integration tests.
* Keep crate roots thin with module declarations and re-exports.

Project folder organization scales with complexity. Keep all files at root-level modules when fewer than 10 source files exist. When folders become necessary, organize by domain responsibility: `config`, `error`, `handlers`, `models`, `services`.

## Cargo.toml Conventions

### Standard Fields

<!-- <example-cargo-toml> -->
```toml
[package]
name = "service-name"
version = "0.1.0"
edition = "2021"
license = "MIT"

[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
thiserror = "2"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
```
<!-- </example-cargo-toml> -->

Sections below reference additional crates (`reqwest`, `tokio-retry`, `async-trait`). Add them to `[dependencies]` when using those patterns.

### Dependency Management

* Use caret ranges for stable public crates: `version = "1"`.
* Pin exact versions for private or unstable SDKs: `version = "=1.1.3"`.
* Disable default features when targeting WASM or minimal builds: `default-features = false`.
* Specify only needed feature flags to reduce compile time and binary size.

### Release Profile

<!-- <example-release-profile> -->
```toml
[profile.release]
strip = true
lto = true
codegen-units = 1
panic = "abort"
```
<!-- </example-release-profile> -->

Use `strip = true` to remove debug symbols. Enable `lto` and `codegen-units = 1` for optimized builds. Set `panic = "abort"` for smaller binaries when stack unwinding is unnecessary.

## Coding Conventions

### Naming

| Element         | Convention           | Example                       |
|-----------------|----------------------|-------------------------------|
| Types & Structs | PascalCase           | `UserService`, `DeviceConfig` |
| Traits          | PascalCase           | `Repository`, `Serializer`    |
| Enum Variants   | PascalCase           | `Status::Active`              |
| Functions       | snake_case           | `process_request`             |
| Variables       | snake_case           | `device_url`, `retry_count`   |
| Constants       | SCREAMING_SNAKE_CASE | `DEFAULT_TIMEOUT`             |
| Modules         | snake_case           | `error_handler`               |
| Crate Names     | kebab-case           | `my-service`                  |
| Feature Flags   | kebab-case           | `onnx-runtime`                |

### Type Naming Suffixes

Apply these suffixes consistently for domain types:

* Error types: `*Error` suffix (`ServiceError`, `ParseError`)
* Config types: `*Config` suffix (`AppConfig`, `DatabaseConfig`)
* Builder types: `*Builder` suffix (`RequestBuilder`, `SessionBuilder`)
* Result type aliases: `pub type Result<T> = std::result::Result<T, ServiceError>;`

### Module Structure

Member ordering within a module:

1. `use` declarations (standard library, external crates, internal modules)
2. Constants and statics
3. Type definitions (structs, enums, type aliases)
4. Trait definitions
5. Trait implementations
6. Inherent implementations
7. Free functions
8. Test module

Within categories, order: `pub` items before `pub(crate)` before private.

### Variable Declarations

Prefer type inference with `let` when the type is obvious from the right side. Use explicit type annotations when inference is ambiguous or the type aids readability:

```rust
let service = UserService::new(repo, logger);
let lookup: HashMap<String, Vec<Item>> = HashMap::new();
```

Prefer early returns over deep nesting. Use `if let` and `let ... else` for option/result unwrapping at control flow boundaries:

```rust
let Some(user) = repository.find(id).await? else {
    return Err(ServiceError::not_found("User not found"));
};
```

## Error Handling

### Custom Error Types

Use `thiserror` for library-style error enums. Define a module-scoped `Result` type alias to reduce boilerplate.

<!-- <example-error-handling> -->
```rust
use thiserror::Error;

pub type Result<T> = std::result::Result<T, ServiceError>;

#[derive(Error, Debug)]
pub enum ServiceError {
    #[error("Not found: {message}")]
    NotFound { message: String },

    #[error("Invalid input: {message}")]
    InvalidInput { message: String },

    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),

    #[error("Serialization error: {0}")]
    Serialization(#[from] serde_json::Error),
}

impl ServiceError {
    pub fn not_found<S: Into<String>>(message: S) -> Self {
        Self::NotFound { message: message.into() }
    }

    pub fn invalid_input<S: Into<String>>(message: S) -> Self {
        Self::InvalidInput { message: message.into() }
    }
}
```
<!-- </example-error-handling> -->

### Error Handling Rules

* Use `thiserror` for error types in libraries and modules with structured error variants.
* Use `anyhow` only in application-level `main` functions or CLI tools where error granularity is unnecessary.
* Prefer `?` operator for error propagation over explicit `match` or `unwrap`.
* Never use `unwrap()` or `expect()` in production paths. Reserve them for cases with compile-time or initialization guarantees.
* Initialization paths include startup config loading in `main`, `OnceLock`/`LazyLock` initializers, and one-time setup that runs before the service accepts work. Use `expect()` with a descriptive message in these contexts.
* Provide context-aware error messages that include relevant state.
* Implement `#[from]` for delegating errors from external crates.
* Add helper constructors on error types for ergonomic creation.

## Async Patterns

### Tokio Runtime

Use Tokio as the async runtime. Select the flavor based on workload characteristics:

<!-- <example-tokio-runtime> -->
```rust
// Multi-threaded for high-concurrency services
#[tokio::main]
async fn main() -> Result<()> {
    // ...
}

// Single-threaded for lightweight or resource-constrained services
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<()> {
    // ...
}
```
<!-- </example-tokio-runtime> -->

### Concurrent Task Management

* Use `tokio::select!` for racing independent tasks that should run concurrently until one completes.
* Use `tokio::try_join!` for collecting results from concurrent tasks that must all succeed.
* Use `tokio::spawn` for background tasks that run independently.
* Handle task cancellation and shutdown gracefully via `CancellationToken` or `tokio::select!`.
* Never block the async runtime with synchronous operations; use `tokio::task::spawn_blocking` instead.

<!-- <example-concurrency> -->
```rust
tokio::select! {
    result = background_task() => result?,
    result = server.run() => result?,
}
```
<!-- </example-concurrency> -->

### Async Trait Implementations

Use `async-trait` for trait definitions requiring async methods. The `async-trait` crate is required for the 2021 edition. Native async trait support is available in the 2024 edition and later.

```rust
use async_trait::async_trait;

#[async_trait]
pub trait Repository: Send + Sync {
    async fn find_by_id(&self, id: &str) -> Result<Option<Item>>;
    async fn save(&self, item: &Item) -> Result<()>;
}
```

## Observability

### Structured Logging

Use the `tracing` crate for all logging. Never use `println!` or `eprintln!` in production code.

<!-- <example-tracing> -->
```rust
use tracing::{info, warn, error, debug};
use tracing_subscriber::filter::EnvFilter;

tracing_subscriber::fmt()
    .with_env_filter(EnvFilter::from_default_env())
    .init();

info!(
    endpoint = %endpoint,
    interval_secs = %interval,
    "Starting service with configuration"
);

error!(
    error_code = "PUBLISH_FAILED",
    topic = %topic,
    "Failed to publish message: {:?}", err
);
```
<!-- </example-tracing> -->

### OpenTelemetry Integration

When distributed tracing is required, integrate OpenTelemetry via `tracing-opentelemetry`. Add `tracing-opentelemetry`, `opentelemetry`, `opentelemetry-sdk` (with the `rt-tokio` feature), and `opentelemetry-otlp` to `[dependencies]`.

* Check for `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable before enabling the exporter.
* Fall back to console-only logging when the variable is absent.
* Use `TraceContextPropagator` for W3C trace context propagation.

```rust
use std::env;

use tracing_subscriber::layer::SubscriberExt;

fn init_tracing() {
    let subscriber = tracing_subscriber::fmt()
        .with_env_filter(tracing_subscriber::EnvFilter::from_default_env());

    if env::var("OTEL_EXPORTER_OTLP_ENDPOINT").is_ok() {
        let tracer = opentelemetry_otlp::new_pipeline()
            .tracing()
            .install_batch(opentelemetry_sdk::runtime::Tokio)
            .expect("OpenTelemetry pipeline must initialize at startup");

        let telemetry = tracing_opentelemetry::layer().with_tracer(tracer);
        tracing::subscriber::set_global_default(
            subscriber.finish().with(telemetry),
        ).expect("Global subscriber must be set once at startup");
    } else {
        subscriber.init();
    }
}
```

## Serialization

### Serde Patterns

* Derive `Serialize` and `Deserialize` using `serde` for all data transfer types.
* Use `#[serde(rename_all = "camelCase")]` when interfacing with JSON APIs that use camelCase.
* Implement `Default` for configuration types to provide sensible fallback values.
* Use `#[serde(default = "...")]` for fields with non-trivial defaults.

<!-- <example-serde> -->
```rust
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct AppConfig {
    pub endpoint: String,
    pub polling_interval_secs: u64,
    #[serde(default = "default_timeout")]
    pub timeout_ms: u64,
}

fn default_timeout() -> u64 { 5000 }

impl Default for AppConfig {
    fn default() -> Self {
        Self {
            endpoint: String::new(),
            polling_interval_secs: 10,
            timeout_ms: default_timeout(),
        }
    }
}
```
<!-- </example-serde> -->

## Configuration Management

### Environment Variables

Define environment variable names as constants. Use `env::var` with clear error messages or sensible defaults.

<!-- <example-env-vars> -->
```rust
const ENDPOINT_VAR: &str = "SERVICE_ENDPOINT";
const INTERVAL_VAR: &str = "POLLING_INTERVAL";

let endpoint = env::var(ENDPOINT_VAR)
    .expect("SERVICE_ENDPOINT must be set");

let interval = env::var(INTERVAL_VAR)
    .unwrap_or_else(|_| "10".to_string())
    .parse::<u64>()
    .expect("POLLING_INTERVAL must be a valid u64");
```
<!-- </example-env-vars> -->

### File-Based Configuration

Support YAML and JSON configuration with validation:

```rust
impl AppConfig {
    pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self> {
        let content = std::fs::read_to_string(&path)?;
        let config: Self = serde_json::from_str(&content)?;
        config.validate()?;
        Ok(config)
    }

    pub fn validate(&self) -> Result<()> {
        if self.endpoint.is_empty() {
            return Err(ServiceError::invalid_input("Endpoint must not be empty"));
        }
        Ok(())
    }
}
```

### Static Initialization

Use `OnceLock` for thread-safe, one-time initialization of global state:

```rust
use std::sync::OnceLock;

static CONFIG: OnceLock<AppConfig> = OnceLock::new();
```

## Resilience Patterns

### Retry Logic

Use `tokio_retry` with exponential backoff for transient failures:

<!-- <example-retry> -->
```rust
use tokio_retry::{strategy::ExponentialBackoff, Retry};
use std::time::Duration;

let retry_strategy = ExponentialBackoff::from_millis(2000)
    .max_delay(Duration::from_secs(10))
    .take(5);

let result = Retry::spawn(retry_strategy, || async {
    client.send(&payload).await
}).await;
```
<!-- </example-retry> -->

## Visibility

* Default to private. Expose only what is needed at module boundaries.
* Use `pub(crate)` for types shared across modules within the same crate.
* Mark public API types with `pub` only when they form the crate's external contract.

### Feature Flags

Use Cargo feature flags for optional functionality:

```rust
pub enum Backend {
    #[cfg(feature = "backend-a")]
    BackendA(BackendAImpl),
    #[cfg(feature = "backend-b")]
    BackendB(BackendBImpl),
}
```

Declare features and gate optional dependencies in `Cargo.toml`:

```toml
[features]
default = []
backend-a = ["dep:backend-a-crate"]
backend-b = ["dep:backend-b-crate"]
```

Gate heavy dependencies behind features so downstream consumers control binary size.

## Code Documentation

Public and protected items require documentation comments.

Guidelines:

* Use `///` for item-level documentation on public types, functions, and modules.
* Use `//!` for module-level documentation at the top of `lib.rs` or `mod.rs`.
* Document parameters and return values in the description when non-obvious.
* Include `# Examples` sections for public API functions.
* Include `# Errors` sections for functions returning `Result`.
* Include `# Panics` sections for functions that can panic.

<!-- <example-documentation> -->
```rust
/// Processes the input data and returns the transformed result.
///
/// # Arguments
///
/// * `input` - Raw input bytes to process.
/// * `config` - Processing configuration.
///
/// # Returns
///
/// The processed output as a byte vector.
///
/// # Errors
///
/// Returns `ServiceError::InvalidInput` if the input cannot be parsed.
///
/// # Examples
///
/// ```
/// let result = process(&input, &config)?;
/// assert!(!result.is_empty());
/// ```
pub fn process(input: &[u8], config: &ProcessConfig) -> Result<Vec<u8>> {
    // ...
}
```
<!-- </example-documentation> -->

## Clippy and Formatting

### Clippy

* Run `cargo clippy` and resolve all warnings before committing.
* Do not suppress Clippy lints without documented justification.
* Use `#[allow(...)]` on specific items rather than crate-wide `#![allow(...)]` when suppression is necessary.

### Formatting

* Run `cargo fmt` before committing.
* Use default `rustfmt` configuration unless the project includes a `rustfmt.toml`.

## Additional Conventions

* Prefer `&str` over `String` in function parameters when ownership is not needed.
* Use `impl Into<String>` for constructors and builders accepting string arguments.
* Use `Cow<'_, str>` when a function may or may not need to allocate:

```rust
use std::borrow::Cow;

fn normalize_name(name: &str) -> Cow<'_, str> {
    if name.contains(' ') {
        Cow::Owned(name.replace(' ', "_"))
    } else {
        Cow::Borrowed(name)
    }
}
```

* Use iterators and combinators over manual loops where readability is maintained.
* Prefer `Vec<u8>` and slices over raw pointer manipulation.

## Patterns to Avoid

* `println!` or `eprintln!` in production code (use `tracing` macros).
* `unwrap()` or `expect()` in production paths without compile-time guarantees.
* Shared mutable state without synchronization primitives (`Mutex`, `RwLock`, `OnceLock`).
* Blocking operations inside async contexts (use `tokio::task::spawn_blocking`).
* Overly broad feature sets on dependencies (minimize with `default-features = false`).
* Global mutable statics without `OnceLock`, `LazyLock`, or equivalent.
* Suppressing Clippy lints without documented justification.
* `unsafe` blocks without a `// SAFETY:` comment explaining the invariant.

## Complete Example

Demonstrates naming, structure, error handling, async patterns, configuration, observability, and testing:

```rust
// Rust uses modules, not namespaces — see the mod declarations below.

use std::env;
use std::time::Duration;

use serde::{Deserialize, Serialize};
use thiserror::Error;
use tokio_retry::{strategy::ExponentialBackoff, Retry};
use tracing::{error, info};
use tracing_subscriber::filter::EnvFilter;

const ENDPOINT_VAR: &str = "SERVICE_ENDPOINT";
const INTERVAL_VAR: &str = "POLLING_INTERVAL";

// --- Error ---

pub type Result<T> = std::result::Result<T, ServiceError>;

#[derive(Error, Debug)]
pub enum ServiceError {
    #[error("Not found: {message}")]
    NotFound { message: String },

    #[error("Request failed: {message}")]
    Request { message: String },

    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),

    #[error("JSON error: {0}")]
    Json(#[from] serde_json::Error),
}

impl ServiceError {
    pub fn not_found<S: Into<String>>(message: S) -> Self {
        Self::NotFound { message: message.into() }
    }

    pub fn request<S: Into<String>>(message: S) -> Self {
        Self::Request { message: message.into() }
    }
}

// --- Config ---

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AppConfig {
    pub endpoint: String,
    #[serde(default = "default_interval")]
    pub polling_interval_secs: u64,
}

fn default_interval() -> u64 { 10 }

impl AppConfig {
    pub fn from_env() -> Self {
        Self {
            endpoint: env::var(ENDPOINT_VAR)
                .expect("SERVICE_ENDPOINT must be set"),
            polling_interval_secs: env::var(INTERVAL_VAR)
                .unwrap_or_else(|_| "10".to_string())
                .parse()
                .expect("POLLING_INTERVAL must be a valid u64"),
        }
    }
}

// --- Service ---

/// Polls an endpoint and processes responses.
pub struct PollingService {
    config: AppConfig,
    client: reqwest::Client,
}

impl PollingService {
    pub fn new(config: AppConfig) -> Self {
        Self {
            config,
            client: reqwest::Client::new(),
        }
    }

    /// Starts the polling loop.
    ///
    /// # Errors
    ///
    /// Returns `ServiceError::Request` on repeated fetch failures.
    pub async fn run(&self) -> Result<()> {
        let interval = Duration::from_secs(self.config.polling_interval_secs);

        loop {
            match self.fetch_with_retry().await {
                Ok(data) => info!(items = data.len(), "Fetched data"),
                Err(err) => error!(?err, "Fetch failed after retries"),
            }
            tokio::time::sleep(interval).await;
        }
    }

    async fn fetch_with_retry(&self) -> Result<Vec<u8>> {
        let strategy = ExponentialBackoff::from_millis(1000)
            .max_delay(Duration::from_secs(8))
            .take(3);

        Retry::spawn(strategy, || self.fetch()).await
    }

    async fn fetch(&self) -> Result<Vec<u8>> {
        let response = self.client
            .get(&self.config.endpoint)
            .send()
            .await
            .map_err(|e| ServiceError::request(e.to_string()))?;

        if !response.status().is_success() {
            return Err(ServiceError::request(
                format!("HTTP {}", response.status()),
            ));
        }

        response.bytes()
            .await
            .map(|b| b.to_vec())
            .map_err(|e| ServiceError::request(e.to_string()))
    }
}

// --- Entry Point ---

#[tokio::main]
async fn main() -> Result<()> {
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::from_default_env())
        .init();

    let config = AppConfig::from_env();
    info!(endpoint = %config.endpoint, "Starting service");

    let service = PollingService::new(config);
    service.run().await
}
```

© microsoft · MIT · microsoft/hve-core

Similar IDE rules

All IDE rules for Programming languages →

rust by other authors comes first.

rust official github This rule guides GitHub Copilot when it writes or reviews Rust files, with advice on ownership, errors, APIs, tests, and project structure. CX Codex +1 ★ 41,430repo stars rust PatrickJS Guides Solana smart contract engineering with the Anchor framework and Rust SDK. Targets account safety, compute efficiency, and TypeScript testing. CX Codex +1 ★ 41,178repo stars rust sanjeed5 A Cursor rule for Rust projects covering module layout, type-safe patterns, error handling, collections, and tests. It applies across project files. CX Codex +1 ★ 3,589repo stars rust-engineer https://github.com/Jeffallan rust-engineer guides the agent to write and review idiomatic Rust 2021 code. Useful when designing traits, resolving borrow checker errors, and building async tokio services. CX Codex +1 6,900installs rust_development vuralserhat86 Guides Rust development with conventions for Tokio runtimes, Axum web services, and strict error handling. CX Codex +1 1installs rust-stinger Legion Code Inc. rust-stinger guides bounded Rust development across Cargo workspaces, Tokio runtimes, SQLx persistence, and test validation before release. CX Codex +1 ★ 96repo stars rust-wasp-drone Legion Code Inc. rust-wasp-drone is a Claude Code, Codex, and Cursor subagent for Rust implementation and code review. It activates on Rust files, Cargo workspaces, or tasks involving Tokio and SQLx. CX Codex ★ 96repo stars rust-best-practices Pedro Nauck rust-best-practices — a skill for writing, refactoring, and optimizing Rust code with ownership, error handling, Tokio, traits, and testing. Use it for systems programming or async workloads where correctness matters. CX Codex +1 298installs rust-learner actionbook rust-learner fetches live Rust updates and crate changelogs from lib.rs or crates.io. Useful when updating Cargo.toml dependencies. CX Codex +1 110installs

From the same set148

The whole set →
powerpoint Builds PowerPoint decks from YAML files that describe each slide's text, shapes and styling, using python-pptx. CX Codex +1 ★ 1,627repo stars Backlog Manager Backlog Manager is a Claude Code subagent that plans backlogs in Azure DevOps, GitHub, and Jira in read-only mode, delegating updates to executor agents. CX Codex +1 ★ 1,627repo stars workflows workflows is a Claude Code rule for GitHub Actions in hve-core. It applies to .github/workflows/*.yml files and sets security conventions for their configuration. CX Codex +1 ★ 1,627repo stars hve-core-installer hve-core-installer walks through installing HVE-Core either as a VS Code extension or via repository clone, detecting the environment and checking the result. CX Codex +1 ★ 1,627repo stars Meeting Analyst Meeting Analyst retrieves Microsoft 365 meetings through WorkIQ, extracts product requirements and decisions, and prepares a handoff for PRD Builder. Use it to turn meeting discussions into structured product findings. CX Codex +1 ★ 1,627repo stars community-interaction community-interaction sets the voice and reply templates an agent uses when it comments on issues, pull requests and discussions visible to outside contributors. CX Codex +1 ★ 1,627repo stars rpi-plan rpi-plan generates or updates evidence-based Markdown implementation plans with phased tracking. Useful when a task requires structured staging and optional multi-pass critique. CX Codex +1 ★ 1,627repo stars adr-identity The adr-identity rule structures Architecture Decision Record sessions, helping authors frame a decision and compare options while leaving the final choice to them. CX Codex +1 ★ 1,627repo stars

Project sponsors

Companies that keep this analytics open