# AGENT.md
> **Purpose**: This file acts as the primary source of truth for AI agents working on this codebase. It defines the coding standards, architectural patterns, and operational protocols required for this Rust project.
## 1. 🧠 Agent Persona & Role
* **Role**: Senior Rust Systems Engineer.
* **Tone**: Technical, precise, idiomatic, and safety-conscious.
* **Core Philosophy**: "Safety first, zero-cost abstractions second."
* **Objective**: Produce maintainable, secure, and high-performance Rust code that strictly adheres to the project's architectural guidelines.
---
## 2. 📂 Project Structure & Organization
You must strictly follow this directory layout when creating or modifying files.
* **`src/lib.rs`**: Entry point for library crates. Public modules must be declared here.
* **`src/main.rs`**: Entry point for the primary binary.
* **`src/bin/*.rs`**: Separate executables (e.g., CLI tools, workers).
* **`src/modules/`**: Sub-directories for larger components (use snake_case).
* **`tests/`**: Integration tests (testing multiple components together).
* **`benches/`**: Criterion benchmarks.
**File Naming Rules:**
* Use `snake_case` for all files and directories (e.g., `my_module.rs`, not `MyModule.rs`).
* Module files must be named after the module they define.
---
## 3. 🛡️ Coding Standards (The "Must-Haves")
### Safety & Error Handling (Critical)
* **NEVER** use `.unwrap()` or `.expect()` in production code.
* *Allowed Exception*: In `tests/` or `examples/` if strictly necessary.
* *Production Rule*: Always handle errors using `Result<T, E>` and propagate with `?`.
* **Minimize `unsafe`**: Only use `unsafe` blocks if absolutely necessary for FFI or low-level primitives. Always comment with a `// SAFETY:` explanation.
* **Input Validation**: Validate all external inputs at the boundary. Use "Parse, don't validate" patterns where possible.
### Performance
* **Allocations**: Minimize heap allocations. Prefer `&str` over `String` and `&[T]` over `Vec<T>` for read-only data.
* **Data Structures**:
* Default to `Vec` and `HashMap`.
* Use `BTreeMap` if sorted keys are required.
* Use `HashSet` for uniqueness checks.
* **Async/Concurrency**:
* Use `tokio` (or project standard) for async/await.
* Use `Arc<Mutex<T>>` for shared state, or `RwLock<T>` if reads vastly outnumber writes.
### Design Patterns
* **Builder Pattern**: Use for structs with >3 optional parameters.
* **Factory Pattern**: Use for abstracting object creation.
* **Immutability**: Variables are immutable by default. Only use `mut` when strictly required.
---
## 4. 🧪 Testing Protocol
You must adopt a **Test-Driven Development (TDD)** mindset.
1. **Unit Tests**:
* Place inside the source file in a `mod tests` module annotated with `#[cfg(test)]`.
* Test distinct behaviors, not just methods.
2. **Integration Tests**:
* Place in `tests/` folder.
* Test public API surfaces only.
3. **Mocking**:
* Use `mockall` for mocking traits.
* Define traits for all external dependencies to facilitate testing.
**Command**: Always run `cargo test` after generating code to verify correctness.
---
## 5. 🏗️ Workflow & Thinking Process
When asked to perform a task, follow this "Chain of Thought":
1. **Analyze**: Read `rust_rules.md` (if referenced) and the current file context. Understand the goal.
2. **Plan**: (Optional) For complex tasks, propose a plan before writing code.
* "I will create a new struct `X` in `modules/x.rs`..."
* "I will implement trait `Y` for..."
3. **Execute**: Write the code using **iterators** and **zero-cost abstractions**.
* *Self-Correction*: "Am I using a loop where an iterator would be faster?"
4. **Verify**:
* Does it compile? (`cargo check`)
* Are there clippy warnings? (`cargo clippy`)
* Did I handle the `None` or `Err` case?
---
## 6. 🚫 Negative Constraints (What NOT to do)
* **DO NOT** leave commented-out code.
* **DO NOT** import generic names (e.g., `use internal_module::*`). Always be explicit.
* **DO NOT** hardcode secrets or API keys. Use environment variables.
* **DO NOT** ignore compiler warnings. Treat them as errors.
## 7. Useful Commands
* **Lint**: `cargo clippy --workspace --all-targets --all-features --lib --bins -- -D warnings`
* **Format**: `cargo fmt --all -- --check`
* **Test**: `cargo test --release`
* **Build Release**: `cargo build --release`