---
name: rust-module-architect
description: "A compilable Rust module skeleton designed before the code: public API, core structs, trait boundaries, visibility, and a test scaffold with todo bodies, with a line on why each piece exists. Use when a new Rust module needs its structure decided up front (structs, traits, visibility, ownership) as a compilable skeleton before the logic is written. Do not use for filling in a fully specified module, analysing existing code, or documenting it. Related topics: coding, rust."
---

# Rust Module Architect

A compilable Rust module skeleton designed before the code: public API, core structs, trait boundaries, visibility, and a test scaffold with todo bodies, with a line on why each piece exists.

## When to use

Use this skill when a new Rust module needs its structure decided up front (structs, traits, visibility, ownership) as a compilable skeleton before the logic is written. Do not use it for filling in a fully specified module, analysing existing code, or documenting it.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Settle the ownership model: which struct owns the data, which borrow it, and where Arc or lifetimes are required.
3. Define the smallest public API that fulfils the purpose, applying the chosen visibility consistently and keeping everything else private.
4. Derive the selected traits where possible and write stub impls where a derive cannot work.
5. Give every function a signature, a doc comment, and a todo!() body so the skeleton compiles as written.
6. Add a #[cfg(test)] module with behaviour-named tests at the chosen depth and summarise the design in the table and rationale lines.

## Inputs

- **Module name** (free text, e.g. "my_module")
- **Purpose** (longer free text)
- **Core structs** (choose any: Config, State, Manager, Handler)
- **Traits to implement** (choose any: Serialize, Clone, Debug, AsyncRead)
- **Visibility** (choose one: pub, pub(crate), private)
- **Test depth** (choose one: minimal, standard, thorough)
- **Input 7** (choose one: cfg(test))

## Output

A code block with the compilable skeleton, a markdown table of name, purpose, structs, traits, visibility, and test depth, and one rationale line per struct or trait.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Rust Module Skeleton

Design the structure of a Rust module.

- Module name: {{Module name}}
- Purpose: {{Purpose}}
- Core structs: {{Core structs}}
- Traits to implement: {{Traits to implement}}
- Visibility: {{Visibility}}
- Test depth: {{Test depth}}

Decide the ownership story first: which struct owns the data, which borrows it, and where lifetimes or Arc are needed, because that decision shapes every signature. Define the public API as the smallest set of functions that fulfils the purpose, with the selected visibility applied consistently and everything else private. Derive the selected traits where a derive works and write a stub impl where it does not (AsyncRead needs a manual impl with poll_read). Give each function a signature, a doc comment, and a todo!() body so the skeleton compiles and the team fills in behaviour later. Add a #{{Input 7}} module with test names that describe behaviour at the chosen depth: one happy path for minimal, error cases for standard, property-style cases for thorough.

Return one code block with the module skeleton, then a markdown table listing the module name, purpose, structs, traits, visibility, and test depth, then one line per struct or trait explaining why it is there.

## Pitfalls

- Deriving Clone on a struct that holds a mutex or a file handle, which either fails to compile or clones the wrong thing.
- Making every item pub so the module compiles quickly, which freezes the internal layout into the public API.
- Leaving function bodies empty instead of todo!(), so the skeleton fails type checking on missing return values.
