agentic-team-templates 0.9.2 → 0.11.0

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