Software Practices

Module Layout

Module and file placement, ownership, crate-root navigation, and public re-export paths.

20 items in this guidance cluster.

Tagged guidance

Guide item

GuideRustPublic APIReader LocalityRust Maintainabilityrust-maintainabilityRust maintainability guidance applies the repos software-change preferences to Rust code, APIs, modules, errors, tests, dependencies, documentation, and release risk. It favors Rust that is easy to read locally, hard to misuse, and honest about public behavior.

Change Shape rules

RuleChange ShapeOwnershipReader LocalityIdentify Owning Module Before EditingCHANGE-IDENTIFY-OWNING-MODULE-BEFORE-EDITINGFind the component that owns the concept before adding or moving logic. That keeps invariants, tests, and future maintenance close to the responsible code.

Rust rules

RuleRustReader LocalityPublic APIAvoid Giant Crate RootsRUST-AVOID-GIANT-CRATE-ROOTSUse the crate root to teach the public shape and route readers to focused modules. This keeps lib.rs or main.rs from becoming the whole implementation surface.RuleRustPublic APIReviewabilityAvoid Glob Re-ExportsRUST-AVOID-GLOB-REEXPORTSRe-export public facade names explicitly instead of using globs. This prevents accidental API expansion and makes exported names visible during review.RuleRustReader LocalityOwnershipAvoid Inline ModulesRUST-AVOID-INLINE-MODULESPut nontrivial modules in named files unless tests, preludes, or generated code justify inline layout. Stable paths make search, review, and ownership clearer.RuleRustReader LocalityLocal ConventionsAvoid mod.rs by DefaultRUST-AVOID-MOD-RS-BY-DEFAULTPrefer named module files when they make tabs, paths, and search results clearer. Reserve mod.rs for cases where local convention or layout makes it the better signal.RuleRustReader LocalityLocal ConventionsAvoid Path AttributesRUST-AVOID-PATH-ATTRIBUTEUse normal Rust module lookup unless generated or platform-specific layout needs #[path]. Predictable file paths make navigation and ownership easier to infer.RuleRustReader LocalityOwnershipAvoid Tiny Module MazesRUST-AVOID-TINY-MODULE-MAZESKeep small helper code near its use unless a separate module owns a real concept. This reduces file-jumping and preserves reader locality.RuleRustPublic APIReader LocalityExpose Primary Path from Crate RootRUST-EXPOSE-PRIMARY-PATH-FROM-CRATE-ROOTMake the crate root show the main workflow, types, and import path. Users should not have to infer the intended entry point from private layout details.RuleRustOwnershipPublic APIKeep Crate Boundaries NarrowRUST-KEEP-CRATE-BOUNDARIES-NARROWPut behavior and tests in the crate or module that owns them before extracting shared helpers. Narrow boundaries reduce dependency fan-out, feature pressure, and hidden coupling.RuleRustPublic APIOwnershipKeep Preludes Re-Export OnlyRUST-KEEP-PRELUDES-REEXPORT-ONLYPut only re-exports in prelude modules and keep original behavior in its owning module. Users expect preludes to aid imports, not hide implementation ownership.RuleRustPublic APIReader LocalityMake Public API Browseable From LayoutRUST-MAKE-PUBLIC-API-BROWSEABLE-FROM-LAYOUTAlign public modules, re-exports, and source files so readers can navigate from API to ownership without translation. Facades are fine when they improve discovery and still point toward the owning concept.RuleRustReader LocalityOwnershipPrefer Concept Owned Modules And Named FilesRUST-PREFER-CONCEPT-OWNED-MODULES-AND-NAMED-FILESOrganize modules around domain concepts and give important concepts named files that own their types, invariants, tests, and docs. Use infrastructure modules only when the cross-cutting concept is real and bounded.RuleRustPublic APIReader LocalityReexport For DiscoveryRUST-REEXPORT-FOR-DISCOVERYRe-export public items where callers naturally look so the crate surface is discoverable without hiding ownership. Keep canonical definitions and docs clear so re-exports do not become competing homes.RuleRustRustdocDocumentationTeach Crate From Crate RootRUST-TEACH-CRATE-FROM-CRATE-ROOTUse crate-root docs and exports to teach the crates main concepts, entry points, and common paths. Keep the root focused enough to orient readers without duplicating every item-level contract.RuleRustReader LocalityOwnershipUse Directory Modules As Tables Of ContentsRUST-USE-DIRECTORY-MODULES-AS-TABLES-OF-CONTENTSLet directory module files introduce, organize, and re-export the concepts owned by that directory. Keep substantial implementation in named child files so the module remains a readable table of contents.RuleRustRustdocPublic APIUse Doc Inline For Canonical ReexportsRUST-USE-DOC-INLINE-FOR-CANONICAL-REEXPORTSUse #[doc(inline)] when a re-export should be the canonical place readers encounter an item. Avoid inlining re-exports that would obscure the owning module or create duplicate-looking documentation.

Mechanism item

MechanismRustReader LocalityReviewabilitySource Coherence Reviewsource-coherence-reviewSource-coherence review inventories named declarations separately from behavior, maps both inventories in both directions, and inspects the declaration outline before implementation detail. The pass finds unnamed owners, unjustified abstractions, split facts, misleading modules, and line-count concerns that disappear once docs and tests are distinguished from implementation.

Agent items

AgentAgent WorkflowAgent ContextSource TruthFull Software Doctrine Prompt Packagent-full-software-doctrine-prompt-packLarge single-file prompt pack that combines the repos software rules and the reasons behind them into one coherent artifact. This version is tuned for Rust-heavy maintenance and refactoring work, especially when existing code needs to be reshaped toward better locality, coherence, ownership, and documentation.AgentRustPublic APIReader LocalityRust Agent Instructionsagent-rust-instructionsCompact Rust maintainability instructions for agents working on APIs, Rustdoc, tests, dependencies, and reviewable implementation changes. The snippet routes agents toward reader locality, explicit boundaries, documented contracts, validation evidence, and pragmatic performance work.