Software Practices

Local Conventions

Established repository rules and language idioms, followed consistently unless the work changes them.

31 items in this guidance cluster.

Tagged guidance

Agent Workflow rules

RuleAgent WorkflowSource TruthDocumentationDistill From Blessed ArtifactsAGENT-DISTILL-FROM-BLESSED-ARTIFACTSStudy accepted code, docs, tests, and reviews first. Adapt local convention to this task.RuleAgent WorkflowToolingPrefer In-Distribution ToolsAGENT-PREFER-IN-DISTRIBUTION-TOOLSUse standard project commands, supported CLIs, and documented workflows before inventing ad hoc tool paths. Familiar tools reduce misuse and make agent output easier to rerun.RuleAgent WorkflowAgent ContextSource TruthSuggest Local Override FilesAGENT-SUGGEST-LOCAL-OVERRIDE-FILESPut checkout-only facts in ignored override files instead of shared guidance. Local overrides keep machine-specific steering useful without leaking it to every contributor.

Boundary rules

RuleBoundary CorrectnessSide EffectsPublic APIKeep Backend Adapters At EdgeBOUNDARY-KEEP-BACKEND-ADAPTERS-AT-EDGEKeep provider-specific terminal, storage, network, and runtime APIs in adapter layers at the boundary. Core logic stays stable and testable while real backend differences remain modeled instead of hidden behind a false common API.RuleBoundary CorrectnessToolingTestingTreat Terminal UI As Product SurfaceBOUNDARY-TREAT-TERMINAL-UI-AS-PRODUCT-SURFACETreat terminal layout, input, scroll behavior, color, viewport size, and platform differences as a user-facing contract when people rely on the interface. This makes regressions reviewable without requiring full visual testing for every tiny internal tool.RuleBoundary CorrectnessToolingVerificationUse Conservative Terminal DefaultsBOUNDARY-USE-CONSERVATIVE-TERMINAL-DEFAULTSChoose first-run terminal behavior that works with limited color, small viewports, ordinary keyboard input, and varied fonts or accessibility settings. Advanced styling can remain opt-in or capability-detected after the baseline is readable and usable.

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.

Documentation rules

RuleDocumentationToolingReviewabilityKeep Markdown LintableDOCS-KEEP-MARKDOWN-LINTABLEUse project Markdown style so formatting stays enforceable and review noise stays low. Treat lint exceptions as intentional local choices, not accumulated drift.RuleDocumentationReader LocalityName Destination, Not DirectionDOCS-NAME-DESTINATION-NOT-DIRECTIONUse labels that name the section, object, or decision the reader will reach. Directional labels make readers follow the page order before knowing whether it is relevant.RuleDocumentationReader LocalityUse Descriptive HeadingsDOCS-USE-DESCRIPTIVE-HEADINGSWrite headings that name the section content, destination, or decision area. Reserve imperative headings for procedures where the section is truly a step.

Refactoring rules

RuleRefactoringReader LocalityChange ShapeUse Whitespace as Function ParagraphsREFACTORING-USE-WHITESPACE-AS-FUNCTION-PARAGRAPHSUse blank lines to group related statements inside a function before extracting more names. Paragraph-like spacing can reveal the local story while avoiding unnecessary helper jumps.

Rust rules

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 LocalityOwnershipAvoid 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 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.RuleRustToolingAutomationEncode Durable Rules in LintsRUST-ENCODE-DURABLE-RULES-IN-LINTSUse lint configuration for project policies stable enough to automate. Durable lints catch repeated mistakes without turning subjective taste into CI noise.RuleRustDocumentationRustdocFormat Docs and Comments ConsistentlyRUST-FORMAT-DOCS-AND-COMMENTS-CONSISTENTLYApply stable formatting to Rustdoc, examples, attributes, and prose comments. Consistent source formatting keeps docs readable and prevents noisy future diffs.RuleRustReader LocalityGroup Module ImportsRUST-GROUP-MODULE-IMPORTSGroup related imports by module when that matches local style. This makes dependency shape easier to scan and avoids churn from one-import-per-line edits.RuleRustReader LocalityPublic APIGroup Private Imports Before Public Re-ExportsRUST-GROUP-PRIVATE-IMPORTS-BEFORE-PUBLIC-RE-EXPORTSSeparate implementation imports from public re-exports in module prologues. The grouping lets readers distinguish internal dependencies from the API surface being presented.RuleRustReader LocalityUse Field Init ShorthandRUST-USE-FIELD-INIT-SHORTHANDUse field init shorthand when variable names already match struct fields so initialization stays compact and familiar. Spell fields out when renaming, conversion, or policy deserves visible attention.

Source rules

RuleSource TruthDocumentationAgent WorkflowGeneralize Project-Specific RulesSOURCE-GENERALIZE-PROJECT-SPECIFIC-RULESExtract the portable failure mode before promoting local lessons into shared guidance. Provider, repo, or tool details should stay local unless they clarify the durable rule.

VCS rules

RuleVCS JJToolingReview HandoffAsk Before Repairing JJ AliasesVCS-ASK-BEFORE-REPAIRING-JJ-ALIASESAsk before changing jj aliases when they disagree with the observed repository topology. Aliases encode workflow policy, so silent repairs can alter future user commands.

Pattern items

PatternDocumentationSource TruthAgent ContextBootstrap Repo Docsbootstrap-repo-docsRepositories without a documentation map make newcomers infer structure from scattered files and conventions. Add the smallest durable entry points that explain purpose, layout, commands, and where deeper guidance belongs.PatternToolingAgent WorkflowReviewabilityChoose Good Enough Toolschoose-good-enough-toolsTooling choices can become a distraction when the available tool is already adequate for the risk. Prefer the simplest tool that gives trustworthy feedback, upgrading only when accuracy, repeatability, or scale requires it.PatternSource TruthDocumentationAgent ContextDistill From Blessed Artifactsdistill-from-blessed-artifactsDurable guidance should come from accepted examples, reviewed decisions, and working artifacts rather than transient preferences. Distill stable lessons from blessed sources and keep uncertain ideas marked as draft.PatternChange ShapeReviewabilityFollow Local Conventionsfollow-local-conventionsInconsistent style and structure make each change feel like a new design decision. Start from nearby patterns and only diverge when the local convention cannot support the current need.PatternAutomationToolingOwnershipKeep 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.PatternDocumentationSource TruthKeep Docs Near Their Subjectkeep-docs-near-their-subjectDocumentation drifts when it is far from the code, policy, or workflow it explains. Let shared rationale rise to the nearest stable owner while item docs retain their local contracts, differences, edge cases, and side effects.PatternDocumentationReviewabilityRustdocPrefer 100-Column Prose Wrapprefer-100-column-prose-wrapWrap Markdown prose and Markdown-bearing doc comments around 100 columns as a maintainer readability preference. The exact number is subjective, but it balances source reading, monospace density, review diffs, and common screen sizes better than 80 or 120 columns.PatternToolingAgent WorkflowPrefer In Distribution Toolsprefer-in-distribution-toolsUnusual tools, layouts, and formats consume agent attention before domain work begins. Prefer common, stable conventions when they meet the need, and document specialized choices when the domain honestly requires them.PatternDocumentationSource TruthPreserve Local Doc Voicepreserve-local-doc-voiceDocumentation edits can become bland or mismatched even when they are grammatically correct. Patch only what needs changing while keeping local terms, structure, density, and tone unless the existing voice blocks clarity or accessibility.PatternAgent ContextDocumentationUse AGENTS.md As Mapuse-agents-md-as-mapA giant AGENTS.md grows stale and crowds out the context the agent actually needs. Keep it as a compact map to canonical guides, patterns, commands, and safety rules, with details living in owned files.