Software Practices

Ownership

Where behavior and state belong, and which module or layer should make the decision.

38 items in this guidance cluster.

Tagged guidance

Agent Workflow rules

RuleAgent WorkflowChange ShapeVCS JJPreserve Human WorkAGENT-PRESERVE-HUMAN-WORKInspect and protect unrelated local edits before changing files. Preserving human work keeps the task diff focused and avoids destroying unfinished or intentional changes.

Boundary rules

RuleBoundary CorrectnessState TransitionsSource TruthKeep One Authoritative Owner Per FactBOUNDARY-KEEP-ONE-AUTHORITATIVE-OWNER-PER-FACTGive each state fact one definite authority and derive other views from it where practical. Cached, persisted, or adapter-specific projections may duplicate a fact only when their source and invalidation or reconciliation contract are explicit.

Change Shape rules

RuleChange ShapeReader LocalityLocal ConventionsIdentify 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.RuleChange ShapeVCS JJPreserve Unowned WorkCHANGE-PRESERVE-UNOWNED-WORKTreat nearby edits from users, agents, generators, or earlier changes as outside your ownership unless the task says otherwise. Adapting around them protects parallel work and context.RuleChange ShapeGenerated ArtifactsAutomationRespect Generated Artifact OwnershipCHANGE-RESPECT-GENERATED-ARTIFACT-OWNERSHIPFix generated outputs through their source inputs, templates, metadata, or generator configuration whenever those own the result. Hand edits are durable only when the tool workflow explicitly supports curation.

Documentation rules

RuleDocumentationSide EffectsPublic APIDocument Lifecycle and Side EffectsDOCS-DOCUMENT-LIFECYCLE-AND-SIDE-EFFECTSDocument caller-visible lifecycle, ownership, platform, feature, and side-effect obligations. Skip internal narration, but make operational responsibilities clear.

Observability rules

RuleObservabilitySide EffectsSecurity PrivacyLog at Owned BoundariesOBSERVABILITY-LOG-AT-OWNED-BOUNDARIESEmit logs where the code still knows the operation, intent, input class, and external boundary. That placement gives useful context without duplicating noise through every layer.

Refactoring rules

RuleRefactoringChange ShapeBoundary CorrectnessAlign Seams with Real VariationREFACTORING-ALIGN-SEAMS-WITH-REAL-VARIATIONPut abstraction seams where code already varies across backends, policies, protocols, tests, or ownership boundaries. Avoid adding names and jumps for hypothetical futures unless the next change or risk clearly justifies them.RuleRefactoringReader LocalityChange ShapeDo Not Over-apply DRYREFACTORING-DO-NOT-OVER-APPLY-DRYKeep similar-looking code separate until it has the same meaning and changes together. Premature sharing can couple unrelated policies and make later edits harder.RuleRefactoringReader LocalityChange ShapeExtract Concept HelpersREFACTORING-EXTRACT-CONCEPT-HELPERSExtract helpers when the new function names a real concept boundary with a stable purpose. Hiding a few lines behind a weak name adds a jump without reducing the readers burden.RuleRefactoringReader LocalityChange ShapeKeep Weak Abstractions CloseREFACTORING-KEEP-WEAK-ABSTRACTIONS-CLOSE-TO-THEIR-USEKeep tentative helpers, types, or traits near their first use until the boundary proves itself. Local placement makes weak abstractions easier to revise, inline, or delete before other modules depend on them.

Review rules

RuleReviewabilityBoundary CorrectnessDocumentationUse ADRs for Boundaries and OwnershipREVIEW-USE-ADRS-FOR-BOUNDARIES-AND-OWNERSHIPRecord durable ownership, API, storage, topology, runtime, or service-boundary decisions in ADRs. A decision record gives later contributors a stable tradeoff to affirm, revise, or replace.

Rust rules

RuleRustReader LocalityChange ShapeAvoid Empty Wrapper TypesRUST-AVOID-EMPTY-WRAPPER-TYPESAdd a wrapper type only when it carries an invariant, behavior, or ownership boundary. Otherwise it adds conversions and concepts without improving correctness.RuleRustReader LocalityLocal ConventionsAvoid 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 LocalityModule LayoutAvoid 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 APIBoundary CorrectnessDo Not Default pub(crate)RUST-DO-NOT-DEFAULT-PUB-CRATEStart items private and widen to pub(crate) only for deliberate shared internals. This keeps modules independent and makes crate-local contracts visible.RuleRustDocumentationPublic APIDocument Visibility OwnershipRUST-DOCUMENT-VISIBILITY-OWNERSHIPPair widened visibility with names and docs that identify the owning concept. This prevents shared internals from looking like accidental stable API.RuleRustReader LocalityKeep Concepts CoherentRUST-KEEP-CONCEPTS-COHERENTGive each module, type, or helper one recognizable idea to own. Coherent ownership keeps readers from carrying unrelated parsing, state, rendering, and policy facts at once.RuleRustPublic APIChange ShapeKeep 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.RuleRustChange ShapeReviewabilityKeep Edits Scoped to Owning ConceptRUST-KEEP-EDITS-SCOPED-TO-OWNING-CONCEPTChange the module, crate, feature, or facade that owns the behavior being fixed. Scoped edits keep reviews atomic and prevent nearby files from pulling in unrelated concepts.RuleRustPublic APIReader LocalityKeep 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 LocalityModule LayoutPrefer 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.RuleRustReader LocalityPrefer Small Clear ShapesRUST-PREFER-SMALL-CLEAR-SHAPESFavor small functions, narrow structs, and simple enums that keep live facts local for readers. Do not split cohesive logic into fragments that force more navigation than understanding.RuleRustReader LocalityDocumentationUse 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.RuleRustReader LocalityChange ShapeUse Functions For Incidental TypesRUST-USE-FUNCTIONS-FOR-INCIDENTAL-TYPESPrefer free or module functions when a type does not own the operation or invariant. Move behavior onto a type when the method relationship clarifies state, policy, or trait design.

VCS rules

RuleVCS JJVerificationChange ShapeInspect State Before MutatingVCS-INSPECT-STATE-BEFORE-MUTATINGInspect working-copy, stack, bookmark, conflict, and unowned state before mutation. Current state keeps edits scoped and avoids rewriting work the agent did not inspect.RuleVCS JJSource TruthScope JJ File TrackingVCS-SCOPE-JJ-FILE-TRACKINGPass intended paths to jj file track and jj file untrack. Scoped tracking keeps local-only, generated, or unrelated files out of publication state.

Pattern items

PatternObservabilitySecurity PrivacySide EffectsContain Observability Policycontain-observability-policyLogging, metrics, tracing, and privacy choices become inconsistent when every call site invents its own policy. Put observability decisions at owned boundaries so lower layers expose facts without duplicating policy.PatternAgent WorkflowAgent ContextVCS JJIsolate Agent Workspacesisolate-agent-workspacesShared worktrees make it easy for agent edits, generated files, or validation steps to collide with unrelated work. Use isolated workspaces when concurrent tasks or uncertain changes need clear ownership and cleanup.PatternAutomationToolingLocal ConventionsKeep Automations Repo Ownedkeep-automations-repo-ownedCritical checks and generation steps become fragile when they live only in personal scripts or local memory. Put repeatable automation in the repository so agents and humans can run the same workflow.PatternObservabilityBoundary CorrectnessSide EffectsLog At Owned Boundarieslog-at-owned-boundariesLogs become noisy and inconsistent when every helper records the same failure from a partial viewpoint. Log where the code owns the operation and can attach useful, safe diagnostic context.PatternReader LocalityChange ShapeName Couplingname-couplingRelationships between pieces are hard to judge when the reason they change together is unnamed. Describe the change pressure first, then decide whether the coupling belongs directly, behind a clearer owner, or across an explicit boundary.PatternChange ShapeVCS JJPreserve Unowned Workpreserve-unowned-workShared working copies may contain edits from another person or an earlier task. Check state before editing, work around unrelated changes, and stop for direction when unowned work blocks the current change.PatternReader LocalityChange ShapeStrengthen Cohesionstrengthen-cohesionA concept becomes harder to understand when its data, rules, and behavior are scattered or bundled with unrelated concerns. Move elements that change for the same reason toward one named owner, while separating nearby code that belongs to another concept.

Principle item

PrincipleBoundary CorrectnessState TransitionsSide EffectsAvoid Global Mutable Stateavoid-global-mutable-stateMutable process-wide state hides ownership, lifecycle, reset, ordering, and concurrency policy. Prefer explicit owners or narrow handles unless the global behavior has a documented policy.

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.