# Agent Guidelines for opencode-testing

This is a Rust project using Edition 2024.

## Build/Test Commands

```bash
# 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

```bash
# 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