Learn-Rust-through-projects/AGENTS.md

Agent Guidelines for opencode-testing

This is a Rust project using Edition 2024.

Build/Test Commands

# Build the project
cargo build

# Build for release
cargo build --release

# Run the application
cargo run

# Run all tests
cargo test

# Run a specific test (e.g., test named `test_calculate_area`)
cargo test test_calculate_area

# Run tests in a specific module
cargo test module_name::

# Run with output visible
cargo test -- --nocapture

# Check for compilation errors without building
cargo check

# Watch mode for development (requires cargo-watch)
cargo watch -x "run"

Code Quality Commands

# Format code (rustfmt)
cargo fmt

# Check formatting without making changes
cargo fmt -- --check

# Run clippy lints
cargo clippy

# Run clippy with all features and warnings as errors
cargo clippy --all-features -- -D warnings

Code Style Guidelines

Formatting

• Use cargo fmt with default settings
• Max line width: 100 characters (default)
• Use 4 spaces for indentation (default)
• Trailing commas in multi-line lists

Naming Conventions

• Variables, functions, modules: snake_case
• Types (structs, enums, traits): CamelCase
• Constants, statics: SCREAMING_SNAKE_CASE
• Lifetimes: 'lowercase
• Generic type parameters: CamelCase (single uppercase letter preferred: T, K, V)
• Macros: snake_case!

Import Organization

Group imports in this order, separated by blank lines:

1. Standard library imports (std::, core::, alloc::)
2. External crate imports
3. Internal crate imports (crate::)
4. Super module imports (super::)
5. Current module imports (self::)

Use use statements not extern crate.

Types and Type Safety

• Prefer explicit types over impl Trait in public APIs
• Use Option<T> and Result<T, E> for fallible operations
• Avoid unwrap() and expect() in production code; handle errors properly
• Use ? operator for error propagation
• Prefer &str over &String, &[T] over &Vec<T> for function parameters

Error Handling

• Define custom error types using thiserror or enum for complex error cases
• Use anyhow for application code error handling
• Propagate errors with ? operator
• Provide context with map_err() when needed

Functions

• Keep functions small and focused on a single task
• Max 5-7 parameters; use structs for more complex parameter sets
• Document public functions with /// doc comments
• Use early returns to reduce nesting

Comments and Documentation

• Use // for inline comments
• Use /// for public API documentation
• Use //! for module-level documentation
• Document panics, unsafe code, and complex algorithms

Unsafe Code

• Avoid unsafe code unless absolutely necessary
• Document all safety invariants with // SAFETY: comments
• Keep unsafe blocks as small as possible

Testing

• Write unit tests in the same file as the code: #[cfg(test)] module
• Use descriptive test names: test_<scenario>_<expected_behavior>
• Use assert!, assert_eq!, assert_ne! for assertions
• Organize tests with submodules for different scenarios

Memory Management

• Prefer ownership and borrowing over cloning when possible
• Use .clone() explicitly when needed
• Consider Cow<'_, T> for data that may be borrowed or owned

Performance

• Avoid premature optimization; write clear code first
• Use iterators instead of loops when appropriate
• Profile before optimizing