rag-rat: Skill for Claude Code

Rust Modern Style

Use this skill when writing or reviewing Rust in the rag-rat repository. It complements async-specific guidance; this skill owns the workspace's general Rust, module, persistence, and API conventions.

Baseline

• Target the Rust 2024 edition and the current workspace rust-version; do not add compatibility shims for older compilers that the workspace does not support.
• Prefer current stable idioms when they make control flow clearer: let-else, inline format args, matches!, is_some_and, and is_none_or.
• Modern does not mean clever. Prefer explicit match, if let, and early returns over iterator or combinator chains that hide domain states or side effects.
• Prefer std::sync::OnceLock or LazyLock over new lazy_static! usage.
• Use &str and slices at borrowed boundaries instead of &String and &Vec<T>.

Imports

Types, traits, enums, and structs may be imported directly. In a mixed or large import group, bring the module in with {self, ..} and qualify free functions, constants, and macros at the call site. This preserves origin information where the code is read.

// Avoid: callables and constants lose their module identity.
use crate::index::graph_index::{
    KeyVersionStamp, LOGICAL_KEY_VERSION, rebuild_logical_symbols,
};

// Prefer: types are direct; operations and constants retain their origin.
use crate::index::graph_index::{self, KeyVersionStamp};

graph_index::rebuild_logical_symbols(...);
let version = graph_index::LOGICAL_KEY_VERSION;

A small, single-purpose import of one function is fine. Apply this rule when an import list mixes roles or makes bare call sites ambiguous, not mechanically to every use.

Modules And Visibility

• Treat mod.rs as a curated index: module declarations and intentional pub/pub(crate) re-exports. Put implementation in cohesive sibling files.
• Split by domain job, not arbitrary line count. Keep helpers private and adjacent to the flow they support.
• Sibling modules should import through super::, not back through their parent's public re-export.
• Start private and widen only for a real production caller: private, then pub(super), then pub(crate), and pub only for a genuine public boundary.
• Never widen production visibility solely for a test; colocate the test or use a test-only seam.