Create AGENTS.md

AGENTS.md

@@ -0,0 +1,122 @@
+# 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