The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat(rules): add Rust language rules (rebased #660) (#686)
Affaan Mustafa9a478ad67605
diff --git a/rules/rust/coding-style.md b/rules/rust/coding-style.mdnew file mode 100644index 000000000..cda67b543--- /dev/null+++ b/rules/rust/coding-style.md@@ -0,0 +1,151 @@+---+paths:+ - "**/*.rs"+---+# Rust Coding Style++> This file extends [common/coding-style.md](../common/coding-style.md) with Rust-specific content.++## Formatting++- **rustfmt** for enforcement — always run `cargo fmt` before committing+- **clippy** for lints — `cargo clippy -- -D warnings` (treat warnings as errors)+- 4-space indent (rustfmt default)+- Max line width: 100 characters (rustfmt default)++## Immutability++Rust variables are immutable by default — embrace this:++- Use `let` by default; only use `let mut` when mutation is required+- Prefer returning new values over mutating in place+- Use `Cow<'_, T>` when a function may or may not need to allocate++```rust+use std::borrow::Cow;++// GOOD — immutable by default, new value returned+fn normalize(input: &str) -> Cow<'_, str> {+ if input.contains(' ') {+ Cow::Owned(input.replace(' ', "_"))+ } else {+ Cow::Borrowed(input)+ }+}++// BAD — unnecessary mutation+fn normalize_bad(input: &mut String) {+ *input = input.replace(' ', "_");+}+```++## Naming++Follow standard Rust conventions:+- `snake_case` for functions, methods, variables, modules, crates+- `PascalCase` (UpperCamelCase) for types, traits, enums, type parameters+- `SCREAMING_SNAKE_CASE` for constants and statics+- Lifetimes: short lowercase (`'a`, `'de`) — descriptive names for complex cases (`'input`)++## Ownership and Borrowing++- Borrow (`&T`) by default; take ownership only when you need to store or consume+- Never clone to satisfy the borrow checker without understanding the root cause+- Accept `&str` over `String`, `&[T]` over `Vec<T>` in function parameters+- Use `impl Into<String>` for constructors that need to own a `String`++```rust+// GOOD — borrows when ownership isn't needed+fn word_count(text: &str) -> usize {+ text.split_whitespace().count()+}++// GOOD — takes ownership in constructor via Into+fn new(name: impl Into<String>) -> Self {+ Self { name: name.into() }+}++// BAD — takes String when &str suffices+fn word_count_bad(text: String) -> usize {+ text.split_whitespace().count()+}+```++## Error Handling++- Use `Result<T, E>` and `?` for propagation — never `unwrap()` in production code+- **Libraries**: define typed errors with `thiserror`+- **Applications**: use `anyhow` for flexible error context+- Add context with `.with_context(|| format!("failed to ..."))?`+- Reserve `unwrap()` / `expect()` for tests and truly unreachable states++```rust+// GOOD — library error with thiserror+#[derive(Debug, thiserror::Error)]+pub enum ConfigError {+ #[error("failed to read config: {0}")]+ Io(#[from] std::io::Error),+ #[error("invalid config format: {0}")]+ Parse(String),+}++// GOOD — application error with anyhow+use anyhow::Context;++fn load_config(path: &str) -> anyhow::Result<Config> {+ let content = std::fs::read_to_string(path)+ .with_context(|| format!("failed to read {path}"))?;+ toml::from_str(&content)+ .with_context(|| format!("failed to parse {path}"))+}+```++## Iterators Over Loops++Prefer iterator chains for transformations; use loops for complex control flow:++```rust+// GOOD — declarative and composable+let active_emails: Vec<&str> = users.iter()+ .filter(|u| u.is_active)+ .map(|u| u.email.as_str())+ .collect();++// GOOD — loop for complex logic with early returns+for user in &users {+ if let Some(verified) = verify_email(&user.email)? {+ send_welcome(&verified)?;+ }+}+```++## Module Organization++Organize by domain, not by type:++```text+src/+├── main.rs+├── lib.rs+├── auth/ # Domain module+│ ├── mod.rs+│ ├── token.rs+│ └── middleware.rs+├── orders/ # Domain module+│ ├── mod.rs+│ ├── model.rs+│ └── service.rs+└── db/ # Infrastructure+ ├── mod.rs+ └── pool.rs+```++## Visibility++- Default to private; use `pub(crate)` for internal sharing+- Only mark `pub` what is part of the crate's public API+- Re-export public API from `lib.rs`++## References++See skill: `rust-patterns` for comprehensive Rust idioms and patterns.diff --git a/rules/rust/hooks.md b/rules/rust/hooks.mdnew file mode 100644index 000000000..4511f1c29--- /dev/null+++ b/rules/rust/hooks.md@@ -0,0 +1,16 @@+---+paths:+ - "**/*.rs"+ - "**/Cargo.toml"+---+# Rust Hooks++> This file extends [common/hooks.md](../common/hooks.md) with Rust-specific content.++## PostToolUse Hooks++Configure in `~/.claude/settings.json`:++- **cargo fmt**: Auto-format `.rs` files after edit+- **cargo clippy**: Run lint checks after editing Rust files+- **cargo check**: Verify compilation after changes (faster than `cargo build`)diff --git a/rules/rust/patterns.md b/rules/rust/patterns.mdnew file mode 100644index 000000000..3d807e7d9--- /dev/null+++ b/rules/rust/patterns.md@@ -0,0 +1,168 @@+---+paths:+ - "**/*.rs"+---+# Rust Patterns++> This file extends [common/patterns.md](../common/patterns.md) with Rust-specific content.++## Repository Pattern with Traits++Encapsulate data access behind a trait:++```rust+pub trait OrderRepository: Send + Sync {+ fn find_by_id(&self, id: u64) -> Result<Option<Order>, StorageError>;+ fn find_all(&self) -> Result<Vec<Order>, StorageError>;+ fn save(&self, order: &Order) -> Result<Order, StorageError>;+ fn delete(&self, id: u64) -> Result<(), StorageError>;+}+```++Concrete implementations handle storage details (Postgres, SQLite, in-memory for tests).++## Service Layer++Business logic in service structs; inject dependencies via constructor:++```rust+pub struct OrderService {+ repo: Box<dyn OrderRepository>,+ payment: Box<dyn PaymentGateway>,+}++impl OrderService {+ pub fn new(repo: Box<dyn OrderRepository>, payment: Box<dyn PaymentGateway>) -> Self {+ Self { repo, payment }+ }++ pub fn place_order(&self, request: CreateOrderRequest) -> anyhow::Result<OrderSummary> {+ let order = Order::from(request);+ self.payment.charge(order.total())?;+ let saved = self.repo.save(&order)?;+ Ok(OrderSummary::from(saved))+ }+}+```++## Newtype Pattern for Type Safety++Prevent argument mix-ups with distinct wrapper types:++```rust+struct UserId(u64);+struct OrderId(u64);++fn get_order(user: UserId, order: OrderId) -> anyhow::Result<Order> {+ // Can't accidentally swap user and order IDs at call sites+ todo!()+}+```++## Enum State Machines++Model states as enums — make illegal states unrepresentable:++```rust+enum ConnectionState {+ Disconnected,+ Connecting { attempt: u32 },+ Connected { session_id: String },+ Failed { reason: String, retries: u32 },+}++fn handle(state: &ConnectionState) {+ match state {+ ConnectionState::Disconnected => connect(),+ ConnectionState::Connecting { attempt } if *attempt > 3 => abort(),+ ConnectionState::Connecting { .. } => wait(),+ ConnectionState::Connected { session_id } => use_session(session_id),+ ConnectionState::Failed { retries, .. } if *retries < 5 => retry(),+ ConnectionState::Failed { reason, .. } => log_failure(reason),+ }+}+```++Always match exhaustively — no wildcard `_` for business-critical enums.++## Builder Pattern++Use for structs with many optional parameters:++```rust+pub struct ServerConfig {+ host: String,+ port: u16,+ max_connections: usize,+}++impl ServerConfig {+ pub fn builder(host: impl Into<String>, port: u16) -> ServerConfigBuilder {+ ServerConfigBuilder {+ host: host.into(),+ port,+ max_connections: 100,+ }+ }+}++pub struct ServerConfigBuilder {+ host: String,+ port: u16,+ max_connections: usize,+}++impl ServerConfigBuilder {+ pub fn max_connections(mut self, n: usize) -> Self {+ self.max_connections = n;+ self+ }++ pub fn build(self) -> ServerConfig {+ ServerConfig {+ host: self.host,+ port: self.port,+ max_connections: self.max_connections,+ }+ }+}+```++## Sealed Traits for Extensibility Control++Use a private module to seal a trait, preventing external implementations:++```rust+mod private {+ pub trait Sealed {}+}++pub trait Format: private::Sealed {+ fn encode(&self, data: &[u8]) -> Vec<u8>;+}++pub struct Json;+impl private::Sealed for Json {}+impl Format for Json {+ fn encode(&self, data: &[u8]) -> Vec<u8> { todo!() }+}+```++## API Response Envelope++Consistent API responses using a generic enum:++```rust+#[derive(Debug, serde::Serialize)]+#[serde(tag = "status")]+pub enum ApiResponse<T: serde::Serialize> {+ #[serde(rename = "ok")]+ Ok { data: T },+ #[serde(rename = "error")]+ Error { message: String },+}+```++## References++See skill: `rust-patterns` for comprehensive patterns including ownership, traits, generics, concurrency, and async.diff --git a/rules/rust/security.md b/rules/rust/security.mdnew file mode 100644index 000000000..83c0e0774--- /dev/null+++ b/rules/rust/security.md@@ -0,0 +1,141 @@+---+paths:+ - "**/*.rs"+---+# Rust Security++> This file extends [common/security.md](../common/security.md) with Rust-specific content.++## Secrets Management++- Never hardcode API keys, tokens, or credentials in source code+- Use environment variables: `std::env::var("API_KEY")`+- Fail fast if required secrets are missing at startup+- Keep `.env` files in `.gitignore`++```rust+// BAD+const API_KEY: &str = "sk-abc123...";++// GOOD — environment variable with early validation+fn load_api_key() -> anyhow::Result<String> {+ std::env::var("PAYMENT_API_KEY")+ .context("PAYMENT_API_KEY must be set")+}+```++## SQL Injection Prevention++- Always use parameterized queries — never format user input into SQL strings+- Use query builder or ORM (sqlx, diesel, sea-orm) with bind parameters++```rust+// BAD — SQL injection via format string+let query = format!("SELECT * FROM users WHERE name = '{name}'");+sqlx::query(&query).fetch_one(&pool).await?;++// GOOD — parameterized query with sqlx+// Placeholder syntax varies by backend: Postgres: $1 | MySQL: ? | SQLite: $1+sqlx::query("SELECT * FROM users WHERE name = $1")+ .bind(&name)+ .fetch_one(&pool)+ .await?;+```++## Input Validation++- Validate all user input at system boundaries before processing+- Use the type system to enforce invariants (newtype pattern)+- Parse, don't validate — convert unstructured data to typed structs at the boundary+- Reject invalid input with clear error messages++```rust+// Parse, don't validate — invalid states are unrepresentable+pub struct Email(String);++impl Email {+ pub fn parse(input: &str) -> Result<Self, ValidationError> {+ let trimmed = input.trim();+ let at_pos = trimmed.find('@')+ .filter(|&p| p > 0 && p < trimmed.len() - 1)+ .ok_or_else(|| ValidationError::InvalidEmail(input.to_string()))?;+ let domain = &trimmed[at_pos + 1..];+ if trimmed.len() > 254 || !domain.contains('.') {+ return Err(ValidationError::InvalidEmail(input.to_string()));+ }+ // For production use, prefer a validated email crate (e.g., `email_address`)+ Ok(Self(trimmed.to_string()))+ }++ pub fn as_str(&self) -> &str {+ &self.0+ }+}+```++## Unsafe Code++- Minimize `unsafe` blocks — prefer safe abstractions+- Every `unsafe` block must have a `// SAFETY:` comment explaining the invariant+- Never use `unsafe` to bypass the borrow checker for convenience+- Audit all `unsafe` code during review — it is a red flag without justification+- Prefer `safe` FFI wrappers around C libraries++```rust+// GOOD — safety comment documents ALL required invariants+let widget: &Widget = {+ // SAFETY: `ptr` is non-null, aligned, points to an initialized Widget,+ // and no mutable references or mutations exist for its lifetime.+ unsafe { &*ptr }+};++// BAD — no safety justification+unsafe { &*ptr }+```++## Dependency Security++- Run `cargo audit` to scan for known CVEs in dependencies+- Run `cargo deny check` for license and advisory compliance+- Use `cargo tree` to audit transitive dependencies+- Keep dependencies updated — set up Dependabot or Renovate+- Minimize dependency count — evaluate before adding new crates++```bash+# Security audit+cargo audit++# Deny advisories, duplicate versions, and restricted licenses+cargo deny check++# Inspect dependency tree+cargo tree+cargo tree -d # Show duplicates only+```++## Error Messages++- Never expose internal paths, stack traces, or database errors in API responses+- Log detailed errors server-side; return generic messages to clients+- Use `tracing` or `log` for structured server-side logging++```rust+// Map errors to appropriate status codes and generic messages+// (Example uses axum; adapt the response type to your framework)+match order_service.find_by_id(id) {+ Ok(order) => Ok((StatusCode::OK, Json(order))),+ Err(ServiceError::NotFound(_)) => {+ tracing::info!(order_id = id, "order not found");+ Err((StatusCode::NOT_FOUND, "Resource not found"))+ }+ Err(e) => {+ tracing::error!(order_id = id, error = %e, "unexpected error");+ Err((StatusCode::INTERNAL_SERVER_ERROR, "Internal server error"))+ }+}+```++## References++See skill: `rust-patterns` for unsafe code guidelines and ownership patterns.+See skill: `security-review` for general security checklists.diff --git a/rules/rust/testing.md b/rules/rust/testing.mdnew file mode 100644index 000000000..dae4b6752--- /dev/null+++ b/rules/rust/testing.md@@ -0,0 +1,154 @@+---+paths:+ - "**/*.rs"+---+# Rust Testing++> This file extends [common/testing.md](../common/testing.md) with Rust-specific content.++## Test Framework++- **`#[test]`** with `#[cfg(test)]` modules for unit tests+- **rstest** for parameterized tests and fixtures+- **proptest** for property-based testing+- **mockall** for trait-based mocking+- **`#[tokio::test]`** for async tests++## Test Organization++```text+my_crate/+├── src/+│ ├── lib.rs # Unit tests in #[cfg(test)] modules+│ ├── auth/+│ │ └── mod.rs # #[cfg(test)] mod tests { ... }+│ └── orders/+│ └── service.rs # #[cfg(test)] mod tests { ... }+├── tests/ # Integration tests (each file = separate binary)+│ ├── api_test.rs+│ ├── db_test.rs+│ └── common/ # Shared test utilities+│ └── mod.rs+└── benches/ # Criterion benchmarks+ └── benchmark.rs+```++Unit tests go inside `#[cfg(test)]` modules in the same file. Integration tests go in `tests/`.++## Unit Test Pattern++```rust+#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn creates_user_with_valid_email() {+ let user = User::new("Alice", "[email protected]").unwrap();+ assert_eq!(user.name, "Alice");+ }++ #[test]+ fn rejects_invalid_email() {+ let result = User::new("Bob", "not-an-email");+ assert!(result.is_err());+ assert!(result.unwrap_err().to_string().contains("invalid email"));+ }+}+```++## Parameterized Tests++```rust+use rstest::rstest;++#[rstest]+#[case("hello", 5)]+#[case("", 0)]+#[case("rust", 4)]+fn test_string_length(#[case] input: &str, #[case] expected: usize) {+ assert_eq!(input.len(), expected);+}+```++## Async Tests++```rust+#[tokio::test]+async fn fetches_data_successfully() {+ let client = TestClient::new().await;+ let result = client.get("/data").await;+ assert!(result.is_ok());+}+```++## Mocking with mockall++Define traits in production code; generate mocks in test modules:++```rust+// Production trait — pub so integration tests can import it+pub trait UserRepository {+ fn find_by_id(&self, id: u64) -> Option<User>;+}++#[cfg(test)]+mod tests {+ use super::*;+ use mockall::predicate::eq;++ mockall::mock! {+ pub Repo {}+ impl UserRepository for Repo {+ fn find_by_id(&self, id: u64) -> Option<User>;+ }+ }++ #[test]+ fn service_returns_user_when_found() {+ let mut mock = MockRepo::new();+ mock.expect_find_by_id()+ .with(eq(42))+ .times(1)+ .returning(|_| Some(User { id: 42, name: "Alice".into() }));++ let service = UserService::new(Box::new(mock));+ let user = service.get_user(42).unwrap();+ assert_eq!(user.name, "Alice");+ }+}+```++## Test Naming++Use descriptive names that explain the scenario:+- `creates_user_with_valid_email()`+- `rejects_order_when_insufficient_stock()`+- `returns_none_when_not_found()`++## Coverage++- Target 80%+ line coverage+- Use **cargo-llvm-cov** for coverage reporting+- Focus on business logic — exclude generated code and FFI bindings++```bash+cargo llvm-cov # Summary+cargo llvm-cov --html # HTML report+cargo llvm-cov --fail-under-lines 80 # Fail if below threshold+```++## Testing Commands++```bash+cargo test # Run all tests+cargo test -- --nocapture # Show println output+cargo test test_name # Run tests matching pattern+cargo test --lib # Unit tests only+cargo test --test api_test # Specific integration test (tests/api_test.rs)+cargo test --doc # Doc tests only+```++## References++See skill: `rust-testing` for comprehensive testing patterns including property-based testing, fixtures, and benchmarking with Criterion.