Rust

Instructions

1. Planning & Analysis

Before writing any code:

• Understand the full requirements and constraints
• Review the existing codebase for conventions, utilities, and patterns already in use
• Check for shared/common modules before creating new utilities
• Consider edge cases within reason unless the user specifically asks for more
• For GUI work: identify which platforms are targeted and any platform-specific constraints

2. Design Principles

Rust-Specific:

• Prefer borrowing over cloning; pass &str not &String, &Path not &PathBuf, &[T] not &Vec<T>
• Use enums, newtypes, and the type system to make illegal states unrepresentable
• Parse raw input into well-typed structures at the boundary, then pass typed data inward
• Leverage impl Into<T>, AsRef<T>, and other conversion traits for ergonomic public APIs

General:

• YAGNI: Implement only what is required; add complexity as the need arises
• KISS: Favor simplicity and clarity over cleverness
• DRY: Extract shared logic into common modules or helper functions
• Follow the repo's existing conventions over personal preference

3. Error Handling (anyhow required)

Use anyhow as the primary error-handling crate. Do not introduce thiserror, eyre, or other error libraries unless explicitly approved.

• All fallible functions return anyhow::Result<T>
• Attach context at every level with .context("message") or .with_context(|| format!(...))
• Propagate errors with ?; never use unwrap() or expect() outside test code
• Use anyhow::anyhow!("message") or anyhow::bail!("message") for ad-hoc errors
• At the entrypoint: handle errors gracefully — print to stderr and exit with appropriate code

4. Project Structure

Follow the structure established by the project. For new projects, use idiomatic Rust conventions:

Workspace projects:

• Place crates under a crates/ directory; list them in root Cargo.toml [workspace.members]
• Shared utilities go in a common crate (e.g., crates/common/ or crates/shared/)
• Each crate has a focused responsibility

Single-crate projects:

• src/main.rs — thin entrypoint: init, parse args/config, call into app logic, handle exit
• src/lib.rs — public API surface; re-exports from submodules
• src/models.rs — domain types, config structs, enums
• src/app.rs (or domain-named module) — core logic

General guidelines:

• Keep main.rs thin — it orchestrates; logic lives in library code
• One module per concern; split files when they exceed ~300 lines
• Additional modules are fine when they keep things tidy and well-scoped
• #[derive(Debug, Clone)] on config/model structs; add Copy, PartialEq, Eq where appropriate
• Enums for discrete modes/states; Option<T> for optional fields

5. Cross-Platform GUI Development

When building GUI applications, apply these practices:

Before doing any visual changes, check the ui-guidelines.md at the root of the repo for general guidelines and best practices for UI/UX development.

Architecture:

• Separate core logic from UI: business logic in a library crate, UI in the binary crate
• Use a message/command pattern to communicate between UI and logic layers
• Keep platform-specific code isolated behind trait abstractions or #[cfg(target_os)] gates
• Design for the event loop: avoid blocking the main/UI thread

Framework guidance (choose based on project needs):

• iced — Elm-inspired, pure Rust, good for data-driven UIs. Strengths: type-safe message passing, no unsafe, cross-platform. Use iced::Application or iced::Sandbox traits.
• egui / eframe — immediate-mode, excellent for tools, dashboards, debug UIs. Strengths: very fast iteration, minimal boilerplate, easy embedding. Use eframe::App trait.
• Tauri — web-tech frontend with Rust backend. Strengths: small binary size, leverage web ecosystem, strong IPC. Use for apps where web UI is preferred.
• Slint — declarative UI with .slint markup language. Strengths: designer-friendly, embedded-capable, good accessibility.
• gtk4-rs / relm4 — GTK4 bindings. Strengths: mature widget set, strong Linux integration. Use relm4 for Elm-style architecture on top of GTK4.
• Dioxus — React-like with RSX syntax. Strengths: familiar to web devs, cross-platform (desktop, web, mobile).

Cross-platform considerations:

• Test on all target platforms early and regularly (Windows, macOS, Linux at minimum)
• Use dirs or directories crate for platform-appropriate config/data/cache paths
• Handle HiDPI/scaling — use logical pixels, not physical pixels
• Respect platform conventions for keyboard shortcuts (Cmd vs Ctrl), file paths, and native look-and-feel
• Use cfg(target_os) sparingly and only when truly needed; prefer cross-platform abstractions
• For file dialogs, system notifications, and other OS integration, use rfd, notify-rust, or similar cross-platform crates

State management:

• Treat application state as a single source of truth; UI renders from state
• Use message/event enums to describe state transitions
• Keep state serializable where practical (enables save/restore, undo/redo)
• For complex state, consider a reducer pattern or Arc<Mutex<State>> for thread-safe sharing

Async and threading in GUI apps:

• Never block the UI thread — offload heavy work to background threads or async tasks
• Use channels (std::sync::mpsc, crossbeam-channel, tokio::sync::mpsc) to send results back to the UI
• For async runtimes alongside GUI event loops, use the framework's built-in async support or run tokio on a separate thread
• Debounce expensive operations triggered by rapid UI events (typing, resizing)

6. Code Style

• Use the repo's rustfmt and clippy configuration; never change them; fix all warnings
• snake_case for functions/variables/modules/files; PascalCase for types; UPPER_SNAKE_CASE for constants
• Group imports: crate::, external crates, std::; no glob imports in production code
• Doc comments (///) on all public items with # Errors / # Panics sections where applicable
• Comments explain "why", not "what"; no commented-out code
• Functions ~50 lines max; extract helpers when they grow
• match over if let chains for multiple variants; guard clauses for early returns

7. Dependencies

• Check the existing Cargo.toml before adding new dependencies
• Prefer well-maintained, widely used crates (check download counts, recent activity, unsafe usage)
• Pin major versions; use cargo update for patch updates
• Feature-gate optional functionality to keep compile times and binary size down
• For cross-platform apps, verify that dependencies support all target platforms
• Dependencies should be always kept up-to-date with the latest stable versions

Commonly useful crates:

• CLI: clap (derive), indicatif (progress bars)
• Serialization: serde + serde_json / toml / ron
• Async: tokio (only when genuinely needed)
• Logging: tracing or log + env_logger
• File I/O: tempfile (tests), walkdir (traversal)
• Cross-platform paths: dirs, directories

8. Performance

• Use BufReader/BufWriter for file I/O
• Pre-allocate Vec capacity when size is known; use Cow<'_, str> to avoid unnecessary allocations
• Use std::sync::LazyLock (or once_cell::sync::Lazy) for expensive one-time inits like compiled regexes
• Profile before optimizing — use cargo flamegraph, criterion for benchmarks
• For GUI: keep frame budgets in mind (~16ms for 60fps); avoid allocations in hot render paths

9. Testing

• Unit tests: #[cfg(test)] mod tests at the bottom of each file; use super::*
• File-based tests: tempfile::tempdir() for temporary directories
• Follow Arrange-Act-Assert; use helper functions to build test fixtures
• Use assert!(matches!(...)) for enum variant checks
• Test happy paths, error conditions, and meaningful boundary values
• Add tests where it makes sense; don't add them purely for coverage numbers
• For GUI: test logic and state management independently from rendering; use snapshot/golden tests for UI if the framework supports it

10. Forbidden

• unsafe code unless explicitly approved by the user
• unwrap() / expect() in non-test code
• Error libraries other than anyhow (no thiserror, eyre, etc.) unless explicitly approved
• Changing rustfmt or clippy settings without explicit approval
• Blocking the UI/main thread in GUI applications

11. Quality Validation

Run before completion (adjust package name to match the project):

cargo build -p <package-name>
cargo clippy -p <package-name> -- -D warnings
cargo test -p <package-name>
cargo fmt -p <package-name> -- --check

For workspace-wide checks:

cargo build --workspace
cargo clippy --workspace -- -D warnings
cargo test --workspace
cargo fmt --all -- --check

Never run git commit. Summarize changes to the user alongside any problems and caveats.

When to Use This Skill

• Writing new Rust applications, libraries, or tools
• Building cross-platform GUI applications in Rust
• Adding functionality to existing crates
• Refactoring, debugging, or reviewing Rust code
• Any Rust task where production-quality, idiomatic code is expected