rust-idioms
Skill25 starsChanged 27 days agoMITView on GitHub
Idiomatic, production Rust for Vorn's crates (types, errors, memory, async, testing, performance, tooling, dependencies). Use while writing or reviewing any Rust in the repo, and as the checklist for re-reading your own diff before a push.
3 other projects use a version of this.
Adopted by
Most recently taken up by
- irahardianto/awesome-agvtheir own version, first seen Oct 14, 2026
- JSBtechnologies/rustkbtheir own version, first seen Oct 11, 2026
- tstapler/dotfilestheir own version, first seen Oct 10, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- irahardianto/awesome-agv★ 157same name
- tstapler/dotfiles★ 8same name
- JSBtechnologies/rustkb★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository3 other files it gives its agents.
- vorn-extension-authorSkill
- vornui-craftSkill
- vorn-wp-builderSkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 4 are distinctive, and 5 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 48
Prefer moving and borrowing to cloning.
- Very specific: line 69
Never block inside an async task: no std::fs, std::process, long loops or Mutex held across .await.
- Very specific: line 79
Avoid block_on inside a runtime.
- Distinctive: line 85
Do not test what the type system proves.
- Very specific: line 108
Do one pass over the bytes.
- Distinctive: line 114
No portable SIMD or nightly features.
- Distinctive: line 123
Hidden or offscreen panes cost nothing to draw: Keep feeding their screen model.
- Very specific: line 141
After adding a dependency locally, cargo tree -p <crate> shows what it pulls in.
- Distinctive: line 158
Do new public items have docs, and do error messages say what failed?
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Rust idioms for Vorn
Written for the pinned toolchain (packages/core/rust-toolchain.toml) and for
a terminal core where every byte a shell prints passes through this
code. When a rule here and the surrounding code disagree, match the surrounding
code and raise it in the PR.
Types and data
- Model states as enums, not flags plus
Options. If two fields are only valid together, they belong in one variant. - Newtypes for units that must not mix: byte offsets, record numbers,
epochs, UTF-16 lengths, columns.
struct Rseq(u64)costs nothing and makes a swapped argument a compile error. - Strings: take
&str(or&[u8]for terminal bytes, which are not UTF-8 guaranteed), returnStringonly when the caller needs ownership.Cow<'_, str>when a function usually returns its input unchanged. - Collections:
Vecby default;VecDequefor rings;HashMapfor lookups;BTreeMapwhen order matters or for deterministic output in tests and serialization. DeriveHash, Eq, PartialEqtogether, never by hand unless the semantics differ. - Conversions through
From/TryFrom, not ad hocto_x()helpers. UseTryFromwhenever the conversion can lose information (usizetou32on the wire is the usual one). - Derive
Debugon every public type; deriveClone,Default,Copyonly when they are cheap and meaningful.
Errors
- Library crates return
Result<T, CrateError>with an error enum per crate (implementstd::error::ErrorandDisplay, by hand or withthiserrorif it is already in the tree). The message says what failed and with which input, in the words the TypeScript used when parity matters. ?to propagate, withFromimpls between layers. NoBox<dyn Error>in a library's public API.unwrap()/expect()only for invariants the code itself establishes, withexpect("why this cannot fail"). Never on input from a PTY, a file, the network or a client.- Panics never cross FFI.
Ownership and memory
- Prefer moving and borrowing to cloning. A
.clone()on the hot path needs a reason; on aStringorVecper chunk it is a bug. - Choose the smallest tool:
Boxfor one heap value,Rc/RefCellonly on a single thread,Arcto share across threads,Arc<Mutex<_>>orArc<RwLock<_>>for shared mutation. Before adding a lock, try ownership by one thread plus a channel. - Globals:
std::sync::LazyLock/OnceLock(notlazy_static). Nostatic mut. - Preallocate when the size is known (
Vec::with_capacity,String::with_capacity,reserve), and reuse buffers across calls instead of allocating per chunk.extend_from_slice/copy_from_slicefor byte copies. unsafeonly at an FFI edge, wrapped in a safe function, with a// SAFETY:comment stating the invariant.#[repr(C)]andstd::ffitypes for anything crossing a C boundary.
Async and threads
- Async only where there is real concurrency (I/O, many sessions). A
sequential computation is a plain function; call it from async code with
tokio::task::spawn_blocking. - Never block inside an async task: no
std::fs,std::process, long loops orMutexheld across.await. Usetokio::syncprimitives when a lock must span an await. - Message passing over shared state:
tokio::sync::mpsc(bounded, so a slow consumer applies backpressure),oneshotfor replies,broadcastorwatchfor fan-out. - Bound concurrency explicitly (a
Semaphore, assrc/git.rsdoes) rather than spawning per request. tokio::select!for cancellation and timeouts; every loop that waits has a way out.- Avoid
block_oninside a runtime. Bridging sync to async is a design smell here. - Instrument long-lived tasks with
tracingspans once a daemon exists.
Testing
- Do not test what the type system proves. Test logic, boundaries and invariants: empty input, a chunk split mid escape sequence, mid UTF-8 codepoint, a wide character at the last column, a record at an epoch change, a cursor exactly at a boundary.
- Unit tests next to the code; integration tests in
tests/use only the public API, which also tests that the API is pleasant to use. - Tests run in parallel. No shared mutable globals; give each test its own
temp dir (
tempfile) and its own instance. - Property tests for round trips (serialize then restore, write then read, feed in one chunk versus many). Seed them and keep failing cases as fixtures.
- Fuzz (
cargo fuzz) parsers of untrusted bytes when the spec calls for it; never let a fuzz input panic. #[tokio::test]for async code; prefer paused time (start_paused = true) to real sleeps.- A test that needs something absent (the Ghostty build, git) skips with a clear reason; it never silently passes.
Performance
- Measure in release (
--release); debug numbers mean nothing. Benchmarks are Criterion benches in the plain crate, plusyarn benchfor the end-to-end JS baseline. - Do one pass over the bytes.
memchrfor scanning, slices instead of substrings, iterators over index loops (they elide bounds checks). - Batch work across the FFI boundary; a call per chunk costs more than the work in it.
- Parallelize with
rayononly for independent CPU-bound work on large inputs; the terminal path is usually latency-bound, not throughput-bound. - No portable SIMD or nightly features; the toolchain is stable and pinned.
Per-byte, per-frame and per-pane paths
Terminal output (per byte or chunk), the UI frame, and anything run once per pane are hot paths: 16 panes streaming at once is the normal case.
- No work that grows with panes × bytes. A chunk for one pane touches that pane only; per frame, visit the dirty panes, not all of them.
- Hidden or offscreen panes cost nothing to draw. Keep feeding their screen model; build no view, shape no text and emit no geometry until they show.
- No allocation per byte, or per cell per frame. Reuse buffers
(
clear()and refill), intern styles, borrow slices; a per-row allocation on a changed frame is the ceiling. - Coalesce redraws to the frame clock. Output sets a dirty flag and requests one frame; the frame folds in everything since the last. Never redraw or wake per chunk.
- Measure with the many-pane bench (
yarn bench:panes --panes 8,16) before and after, and quote frame p50/p99 and CPU per pane in the PR.
Tooling and hygiene
cargo fmtandcargo clippy --all-targets -- -D warningsmust be clean. Fix lints;#[allow(clippy::...)]only with a comment saying why, on the smallest item.//!doc on every module and///on every public item, saying why as well as what. Doc examples compile; use them for small API examples.- After adding a dependency locally,
cargo tree -p <crate>shows what it pulls in; check that before committing.cargo tree -i <crate>shows who depends on a crate.cargo expanddebugs a macro. - Dependencies: prefer the standard library and crates already in
Cargo.lock. Turn off default features and enable only what is used. Optional heavy deps sit behind a cargo feature (asghosttydoes). - Patch or fork a dependency only as a last resort, upstream the fix, and get back on the released version quickly.
Cargo.lockis committed; CI builds with--locked.
Before you push: re-read the diff
- Any
unwrap,expect,panic!, indexing orascast on outside input? - Any allocation or clone per chunk that could be a reused buffer? Any work per byte that loops over every pane, or per frame over panes not drawn?
- Any blocking call reachable from an async task or from Node's thread?
- Any
unsafewithout aSAFETYcomment, or exposed without a safe wrapper? - Do new public items have docs, and do error messages say what failed?
- Is every new test checking logic, and does each must-pass id have one?
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

