agentic-team-templates 0.10.0 → 0.12.0

package/templates/rust-expert/.cursorrules/traits-and-generics.md

@@ -0,0 +1,236 @@
+# Rust Traits and Generics
+
+Traits are Rust's mechanism for abstraction, polymorphism, and code reuse. Combined with generics, they enable zero-cost abstractions that rival hand-written specialized code.
+
+## Trait Design
+
+### Small, Focused Traits
+
+```rust
+// Good: Single-purpose traits
+pub trait Validate {
+    fn validate(&self) -> Result<(), ValidationError>;
+}
+
+pub trait Serialize {
+    fn serialize(&self, writer: &mut dyn Write) -> Result<(), SerializeError>;
+}
+
+// Bad: God trait
+pub trait Entity {
+    fn validate(&self) -> Result<(), Error>;
+    fn serialize(&self) -> Vec<u8>;
+    fn save(&self, db: &Database) -> Result<(), Error>;
+    fn render(&self) -> Html;
+    // Too many responsibilities — split by concern
+}
+```
+
+### Extension Traits
+
+```rust
+// Add methods to existing types via extension traits
+pub trait StrExt {
+    fn is_blank(&self) -> bool;
+    fn truncate_to(&self, max_len: usize) -> &str;
+}
+
+impl StrExt for str {
+    fn is_blank(&self) -> bool {
+        self.trim().is_empty()
+    }
+
+    fn truncate_to(&self, max_len: usize) -> &str {
+        if self.len() <= max_len {
+            self
+        } else {
+            // Find a char boundary to avoid panic
+            let mut end = max_len;
+            while !self.is_char_boundary(end) {
+                end -= 1;
+            }
+            &self[..end]
+        }
+    }
+}
+```
+
+### Sealed Traits
+
+```rust
+// Prevent external implementations when your trait is part of an internal contract
+mod private {
+    pub trait Sealed {}
+}
+
+pub trait Backend: private::Sealed {
+    fn execute(&self, query: &str) -> Result<Rows>;
+}
+
+// Only types in your crate can implement Sealed, so only they can implement Backend
+impl private::Sealed for PostgresBackend {}
+impl Backend for PostgresBackend { ... }
+```
+
+### The Newtype Pattern
+
+```rust
+// Implement foreign traits on foreign types via newtype
+struct Meters(f64);
+struct Seconds(f64);
+
+impl fmt::Display for Meters {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{:.2}m", self.0)
+    }
+}
+
+// Also prevents mixing units at compile time
+fn speed(distance: Meters, time: Seconds) -> f64 {
+    distance.0 / time.0
+}
+// speed(Seconds(1.0), Meters(5.0)) — compile error! Arguments are swapped.
+```
+
+## Generics
+
+### Trait Bounds
+
+```rust
+// Prefer impl Trait for simple cases
+fn print_all(items: &[impl Display]) {
+    for item in items {
+        println!("{item}");
+    }
+}
+
+// Use where clauses for complex bounds
+fn merge<T, U>(left: T, right: U) -> Merged
+where
+    T: IntoIterator<Item = Record>,
+    U: IntoIterator<Item = Record>,
+    T::IntoIter: ExactSizeIterator,
+{
+    // ...
+}
+
+// Use explicit generic parameters when the caller needs to specify the type
+fn parse<T: FromStr>(input: &str) -> Result<T, T::Err> {
+    input.parse()
+}
+let n: i32 = parse("42")?;
+let f: f64 = parse("3.14")?;
+```
+
+### Associated Types vs Generic Parameters
+
+```rust
+// Associated types: one implementation per type
+trait Iterator {
+    type Item; // Each iterator has exactly one Item type
+    fn next(&mut self) -> Option<Self::Item>;
+}
+
+// Generic parameters: multiple implementations per type
+trait Convert<T> {
+    fn convert(&self) -> T;
+}
+// A single type can implement Convert<String>, Convert<i32>, etc.
+
+// Rule of thumb: If there should be only one implementation
+// for a given Self type, use an associated type.
+```
+
+### Phantom Types
+
+```rust
+use std::marker::PhantomData;
+
+// Type-state pattern: encode state in the type system
+struct Validated;
+struct Unvalidated;
+
+struct Form<State> {
+    data: FormData,
+    _state: PhantomData<State>,
+}
+
+impl Form<Unvalidated> {
+    fn new(data: FormData) -> Self {
+        Form { data, _state: PhantomData }
+    }
+
+    fn validate(self) -> Result<Form<Validated>, ValidationError> {
+        // validation logic...
+        Ok(Form { data: self.data, _state: PhantomData })
+    }
+}
+
+impl Form<Validated> {
+    fn submit(self) -> Result<(), SubmitError> {
+        // Only validated forms can be submitted
+        send(self.data)
+    }
+}
+
+// Form::new(data).submit() — compile error! Must validate first.
+```
+
+## Dynamic Dispatch
+
+```rust
+// Static dispatch (monomorphization) — zero cost, larger binary
+fn process(handler: impl Handler) { handler.handle(); }
+
+// Dynamic dispatch (trait objects) — vtable indirection, smaller binary
+fn process(handler: &dyn Handler) { handler.handle(); }
+
+// Use trait objects when:
+// - You need a heterogeneous collection
+// - You want to reduce binary size (e.g., embedded)
+// - The type is determined at runtime
+
+// Trait object safety: a trait is object-safe if:
+// - No methods return Self
+// - No methods have generic type parameters
+// - No associated functions (no &self receiver)
+```
+
+## Derive and Common Traits
+
+```rust
+// Derive what you can — it's correct and free
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct UserId(String);
+
+// Standard trait hierarchy to consider:
+// Debug         — always derive, essential for diagnostics
+// Clone         — when values need to be duplicated
+// PartialEq/Eq  — when values need comparison
+// Hash          — when used as map keys (requires Eq)
+// Default       — when a meaningful zero value exists
+// Display       — for user-facing output (implement manually)
+// Serialize/Deserialize — for serde (derive with feature flag)
+
+// Don't derive Copy unless the type is truly trivially copyable
+// and you want implicit copies. Copy types can't have Drop.
+```
+
+## Anti-Patterns
+
+```rust
+// Never: Trait objects everywhere when generics would work
+// Box<dyn Fn()> is fine for callbacks stored in structs
+// impl Fn() is better for function parameters
+
+// Never: Overusing generics for types that will only ever have one concrete type
+fn process<T: Into<String>>(name: T) { } // Just take String or &str
+
+// Never: Unused type parameters
+struct Wrapper<T> { // T is not used — won't compile without PhantomData
+    data: Vec<u8>,
+}
+
+// Never: Implementing traits for types you don't own without a newtype
+// Orphan rule prevents this anyway — respect it
+```

package/templates/rust-expert/CLAUDE.md

@@ -0,0 +1,283 @@
+# Rust Expert Development Guide
+
+Principal-level guidelines for Rust engineering. Ownership, zero-cost abstractions, and fearless concurrency — wielded with precision.
+
+---
+
+## Overview
+
+This guide applies to:
+- Systems programming and embedded targets
+- Web services and async runtimes (Tokio, async-std)
+- CLI tools and developer utilities
+- Libraries and crates published to crates.io
+- WebAssembly targets
+- FFI and interop with C/C++
+
+### Core Philosophy
+
+Rust gives you power without sacrificing safety. The compiler is your closest collaborator.
+
+- **If it compiles, it's probably correct.** The borrow checker catches bugs that would be CVEs elsewhere.
+- **Zero-cost abstractions are the point.** Never choose between expressiveness and performance.
+- **Make illegal states unrepresentable.** Encode invariants in the type system.
+- **Explicit over implicit.** Lifetimes, ownership, error handling — surfaced, not hidden.
+- **Unsafe is a scalpel, not a sledgehammer.** Every `unsafe` block is a proof obligation.
+- **If you don't know, say so.** Admitting uncertainty is better than guessing about soundness.
+
+### Project Structure
+
+```
+project/
+├── Cargo.toml
+├── src/
+│   ├── main.rs / lib.rs
+│   ├── error.rs
+│   └── domain/
+├── tests/              # Integration tests
+├── benches/            # Benchmarks
+└── examples/
+```
+
+---
+
+## Ownership and Borrowing
+
+### The Three Rules
+
+1. Each value has exactly one owner
+2. When the owner goes out of scope, the value is dropped
+3. Either one `&mut T` OR any number of `&T` — never both
+
+### Lifetimes
+
+```rust
+fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
+    if x.len() > y.len() { x } else { y }
+}
+```
+
+### Smart Pointers
+
+- `Box<T>` — heap allocation, single owner
+- `Rc<T>` — reference-counted, single-threaded
+- `Arc<T>` — atomic reference-counted, thread-safe
+- `Cow<'_, T>` — clone-on-write, avoid allocation when possible
+
+### Interior Mutability
+
+- `Cell<T>` — Copy types, single-threaded, zero overhead
+- `RefCell<T>` — runtime borrow checking, single-threaded
+- `Mutex<T>` / `RwLock<T>` — thread-safe
+- `Atomic*` — lock-free primitives
+
+---
+
+## Error Handling
+
+### thiserror (Libraries)
+
+```rust
+#[derive(Debug, Error)]
+pub enum AppError {
+    #[error("database query failed")]
+    Database(#[from] sqlx::Error),
+    #[error("record not found: {entity} with id {id}")]
+    NotFound { entity: &'static str, id: String },
+}
+```
+
+### anyhow (Applications)
+
+```rust
+fn load_config(path: &Path) -> Result<Config> {
+    let contents = fs::read_to_string(path)
+        .with_context(|| format!("reading config from {}", path.display()))?;
+    Ok(toml::from_str(&contents).context("parsing config")?)
+}
+```
+
+### Panic Policy
+
+Panics are for bugs, not expected errors. No `unwrap()` in library code without justification. `todo!()` never ships.
+
+---
+
+## Traits and Generics
+
+### Small, Focused Traits
+
+```rust
+pub trait Validate {
+    fn validate(&self) -> Result<(), ValidationError>;
+}
+```
+
+### Define Interfaces at the Consumer
+
+The consumer decides what it needs — don't force a God-trait on callers.
+
+### Phantom Types for State Machines
+
+```rust
+struct Form<State> { data: FormData, _state: PhantomData<State> }
+// Form<Unvalidated> can't call submit() — only Form<Validated> can
+```
+
+### Generics Rules
+
+- `impl Trait` for simple bounds in function parameters
+- `where` clauses for complex bounds
+- Associated types when there's one implementation per Self type
+- Generic parameters when multiple implementations per Self type
+
+---
+
+## Concurrency
+
+### Threads
+
+```rust
+// Scoped threads (1.63+) — safe borrows from parent stack
+thread::scope(|s| {
+    s.spawn(|| process(&data));
+});
+```
+
+### Async/Await
+
+```rust
+// Concurrent execution
+let (users, posts) = tokio::join!(fetch_users(), fetch_posts());
+
+// Timeout
+tokio::select! {
+    result = fetch_data() => handle(result),
+    _ = tokio::time::sleep(Duration::from_secs(5)) => bail!("timeout"),
+}
+```
+
+### Key Rules
+
+- Never hold a `MutexGuard` across an `.await` point
+- Never block in async context — use `spawn_blocking` for CPU work
+- Use `tokio::sync::Mutex` when you must hold across awaits
+- Every spawned task needs a cancellation/shutdown strategy
+
+---
+
+## Testing
+
+### Table-Style Tests
+
+```rust
+#[test]
+fn test_parse_age() {
+    let cases = [("25", Ok(25)), ("-1", Err(..)), ("abc", Err(..))];
+    for (input, expected) in cases {
+        assert_eq!(parse_age(input), expected, "input: {input}");
+    }
+}
+```
+
+### Trait-Based Dependency Injection
+
+```rust
+trait Clock { fn now(&self) -> DateTime<Utc>; }
+struct FakeClock(DateTime<Utc>);
+impl Clock for FakeClock { fn now(&self) -> DateTime<Utc> { self.0 } }
+```
+
+### Property-Based Testing
+
+```rust
+proptest! {
+    #[test]
+    fn round_trips(name in "[a-z]{1,50}", age in 0u32..150) {
+        let user = User { name, age };
+        let json = serde_json::to_string(&user)?;
+        let decoded: User = serde_json::from_str(&json)?;
+        assert_eq!(user, decoded);
+    }
+}
+```
+
+### Always Run
+
+```bash
+cargo test --all-features
+cargo clippy -- -D warnings
+cargo +nightly miri test  # For crates with unsafe
+```
+
+---
+
+## Performance and Unsafe
+
+### Measure First
+
+```bash
+cargo bench
+cargo flamegraph
+cargo build --timings
+```
+
+### Key Patterns
+
+- Preallocate with `Vec::with_capacity`
+- Iterators over collect-then-iterate
+- `Cow` for conditional allocation
+- `SmallVec` for small stack-allocated collections
+- `String::with_capacity` and `std::fmt::Write`
+
+### Unsafe Rules
+
+- Every `unsafe` block gets a `// SAFETY:` comment
+- Wrap unsafe in safe abstractions with narrow interfaces
+- Run Miri in CI for any crate with unsafe code
+- `unsafe` doesn't fix design problems — it hides them
+
+---
+
+## Ecosystem and Tooling
+
+### Essential Crates
+
+| Domain | Crate |
+|--------|-------|
+| Serialization | serde, serde_json |
+| Async | tokio |
+| Web | axum, reqwest, tonic |
+| Database | sqlx, diesel |
+| Errors | thiserror, anyhow |
+| CLI | clap |
+| Observability | tracing, metrics |
+| Testing | proptest, criterion, mockall, insta |
+
+### CI Essentials
+
+```bash
+cargo fmt -- --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all-features
+cargo audit
+cargo deny check
+```
+
+---
+
+## Definition of Done
+
+A Rust feature is complete when:
+
+- [ ] `cargo build` compiles with zero warnings
+- [ ] `cargo clippy -- -D warnings` passes
+- [ ] `cargo test` passes (including doc tests)
+- [ ] `cargo fmt -- --check` passes
+- [ ] No `unwrap()` in library code without justification
+- [ ] All `unsafe` blocks have `// SAFETY:` comments
+- [ ] Error types implement `std::error::Error`
+- [ ] Public API has doc comments with examples
+- [ ] No unnecessary allocations in hot paths
+- [ ] `cargo deny check` passes
+- [ ] Code reviewed and approved