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):

bash

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:

bash

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