home / skills / busirocket / agents-skills / busirocket-rust

busirocket-rust skill

safe

This skill enforces Rust project standards for modular structure, SQL and prompt separation, and one-thing-per-file discipline to improve maintainability.

npx playbooks add skill busirocket/agents-skills --skill busirocket-rust

Review the files below or copy the command above to add this skill to your agents.

Files (9)

SKILL.md

2.4 KB

---
name: busirocket-rust
description:
  Rust language and module standards for maintainable codebases. Use when
  writing Rust code, structuring modules, separating SQL/prompts from code, and
  enforcing one-thing-per-file discipline.
metadata:
  author: cristiandeluxe
  version: "1.0.0"
---

# Rust Standards

Strict, reusable standards for Rust codebases (libraries, CLIs, or backend
services).

## When to Use

Use this skill when:

- Writing or refactoring Rust code
- Structuring modules (services, utils, models)
- Separating SQL queries or LLM prompts from Rust code
- Enforcing one-thing-per-file discipline

## Non-Negotiables (MUST)

- **One public symbol per file** (function / type / trait).
- **No inline SQL strings** in `.rs` files; use dedicated SQL files with
  `include_str!()` (e.g. `sql/<area>/Xxx.sql`).
- **No inline LLM/AI prompts** in `.rs` files; use dedicated prompt files with
  `include_str!()` (e.g. `prompts/<area>/Xxx.prompt`).
- Handlers (HTTP, commands, etc.) must be thin: validate, call service, return.

## Module Layout

- `src/services/`: external boundaries (IO, DB, network).
- `src/utils/`: pure logic (no IO).
- `src/models/`: domain types (one type per file).
- No "misc" modules like `helpers.rs` or `common.rs`.

## Rules

### Language & Style

- `rust-language-style` - Language & style (English-only, struct/enum, error
  types)

### One Thing Per File

- `rust-one-thing-per-file` - One thing per file (STRICT)
- `rust-module-manifests` - Module manifests exception (mod.rs)

### Module Layout

- `rust-module-layout` - Module layout (STRICT) - services, utils, models

### SQL Separation

- `rust-sql-separation` - SQL separation (STRICT) - no inline SQL

### Prompt Separation

- `rust-prompt-separation` - Prompt separation (STRICT) - no inline prompts

### Boundaries

- `rust-boundaries` - Boundaries (thin handlers, validate, call service, return)

### Validation

- `rust-validation` - Validation (run checks after changes)

## Related Skills

- `busirocket-core-conventions` - General file structure principles
- `busirocket-tauri` - Tauri-specific layout and commands (when building desktop
  apps)

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/rust-one-thing-per-file.md
rules/rust-sql-separation.md
rules/rust-module-layout.md
```

Each rule file contains:

- Brief explanation of why it matters
- Code examples (correct and incorrect patterns)
- Additional context and best practices

Overview

This skill defines strict Rust language and module standards to keep codebases maintainable and auditable. It enforces single-responsibility files, clear module boundaries, and separation of SQL and LLM prompts from Rust source. Use it to standardize libraries, CLIs, and backend services for long-term clarity and testability.

How this skill works

The skill inspects project layout and source files against a set of non-negotiable rules: one public symbol per file, no inline SQL or prompts, and a strict services/utils/models module layout. It flags violations, points to the relevant rule files, and recommends corrections such as moving SQL to include_str!() files or extracting logic into utils. Handlers are validated to be thin and to delegate to services.

When to use it

Writing or refactoring Rust code to improve structure and readability
Organizing modules into services, utils, and models
Separating SQL queries and LLM prompts from Rust sources
Enforcing one-thing-per-file discipline for public symbols
Validating handler boundaries and service layering

Best practices

Keep exactly one public function/type/trait per file; use mod manifests only where necessary
Place IO and external effects under src/services, pure logic under src/utils, and domain types under src/models
Store SQL under sql/<area>/Name.sql and load with include_str!(), never inline SQL strings
Store prompts under prompts/<area>/Name.prompt and load with include_str!(), never inline prompts
Make handlers thin: validate input, call a service, and return results; avoid embedding business logic in endpoints

Example use cases

Refactor a monolithic handlers.rs into per-endpoint files each exposing one public handler and delegating to services
Move embedded SQL from multiple .rs files into sql/<area>/ files and replace with include_str!() calls
Extract shared pure logic into src/utils/ and keep IO in src/services/ to simplify testing
Introduce a new domain type by adding a single file under src/models/ with one public type and associated tests
Add validation checks in CI to enforce the one-thing-per-file and SQL/prompt separation rules automatically

FAQ

What counts as a public symbol for the one-thing-per-file rule?

Any pub function, struct, enum, trait, or const that is intended for external use. Helper privates can coexist but prefer extracting helpers if files grow large.

How should I handle small related types that feel awkward split into files?

Prefer one type per file for discoverability; use folder-level mod.rs or lib.rs to re-export related items so callers get a cohesive API without merging definitions.