Ai coding guidelines for rust

AI_CONTRIBUTING.md

AI Coding Guidelines (Rust)

These guidelines apply to all AI-assisted code changes in this repository.

Workflow

• Read the full contents of any file you plan to change, plus directly related modules.
• Summarize current behavior and invariants before proposing edits.
• Propose a minimal patch plan (files + rationale) before modifying code.

Rust Style & Design

• Correctness first; then idiomatic, reviewable Rust.
• Prefer clarity over cleverness: small functions, early returns, shallow nesting.
• Keep diffs small and reviewable; avoid cosmetic churn.
• Do not include expository or 'my way' style comments
• Do not include any comments that focus on the change itself and lack suitable generality ('low overhead version' or 'fully optimal version', etc.)
• Comments should document the code not the change we are making

Naming

• Naming must be semantic, not pattern-based.
• Avoid suffixes like State, Context, Manager unless there is a real contrast (e.g., Config vs Runtime, Snapshot vs Live).
• Do not use either prefixes or suffixes as namespaces.
• Rust is strongly typed, do not express type information through naming

Abstraction

• Abstract only when it removes duplication or encodes invariants.
• Prefer concrete domain types over generic wrappers.

Style

• prefer the standard library
• use external packages only with approval
• never duplicate code

Quality Gates

• Always add test coverage for added functionality
• Code must compile, pass tests, respect schema stability.
• Run cargo fmt, cargo clippy, and relevant tests after edits.
• Unit tests must not access external files and data, however integration tests may