Skip to content

project rulesWorkflowrust

Rust CLI Rules

Project rules for Rust command line tools: clap derive, thiserror and anyhow errors, exit codes, tracing logs and assert_cmd tests.

npx workspacetemplates add rust-cli-rules --tool claude-code

Writes 1 file to your project root

CLAUDE.mdadd to your file21 lines · 1.2 KBFile
# Project rules: Rust CLI

## Layout
- Split a library crate (`src/lib.rs`) from a thin `src/main.rs`. Put commands in modules; `main` parses, calls the library and maps the result to an exit code.
- Pin `rust-version`, commit `Cargo.lock` for binaries and keep dependencies few.

## Arguments
- Define arguments with `clap` derive (`Parser`, `Subcommand`, `ValueEnum`). Document every flag with doc comments so `--help` is useful. Support `--json` for machine output.

## Errors and exit codes
- Library errors are typed with `thiserror`; the binary may wrap them with `anyhow` and `.context(...)`.
- No `unwrap`, `expect` or indexing on user data outside tests. Return `Result` and let `main` print one line to stderr.
- Exit `0` on success, `1` on failure, `2` for usage errors. Handle broken pipes quietly.

## Output and logging
- Results go to stdout; diagnostics go to stderr through `tracing` with an `EnvFilter` and `-v` flags.
- Prefer borrowing (`&str`, `&Path`) in signatures and `PathBuf` for owned paths.

## Quality
- Unit-test logic in the library. Test the binary with `assert_cmd` and `predicates`, using `tempfile` for files.
- Run `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings` and `cargo test` before finishing.

What it does

These rules shape a Rust command line tool into a small binary over a testable library. Parsing, domain logic and error reporting each get a clear home.

They help an agent avoid common slips such as panicking on bad input, printing diagnostics to stdout or burying logic in main.

Example

you › Add a stats subcommand that counts lines per file

agent › The agent adds a clap subcommand, a library function returning a typed result, stderr-only logging and an assert_cmd test with a temp file.

Questions

Why both thiserror and anyhow?
Typed errors suit the library where callers match on them; anyhow is convenient in the binary where you only report.
Does it cover async?
It assumes a synchronous tool. Add tokio rules to the file if your command needs a runtime.
  • Go CLI Rules

    Project rulesgo

    Free
  • Python CLI Rules

    Project rulespython

    Free
  • Bug Report Triage

    SkillWorkflow

    Free
  • Codebase Onboarding

    SkillWorkflow

    Free