Verification

Evidence for a claim: checks, inspection, measurements, or comparison with a trusted source.

103 items in this guidance cluster.

Tagged guidance

GuideAgent WorkflowAgent ContextToolingCoding Agentscoding-agentsCoding-agent guidance covers task setup, repo-owned context, tools, workspaces, verification, handoff proof, feedback loops, and maintainer review flow. It treats agents as workers in a system whose output should be reviewable, durable, and easy to integrate.GuideChange ShapeReviewabilityReview HandoffSoftware Change Preferencessoftware-change-preferencesSoftware-change guidance covers broad preferences for change size, structure, validation, review artifacts, commit history, and handoff. It favors small coherent changes, explicit tradeoffs, and evidence matched to the changed surface.

RuleAgent WorkflowReview HandoffFeedback LoopsBudget for Feedback LoopsAGENT-BUDGET-FOR-FEEDBACK-LOOPSReserve enough time and tokens for checks, failure inspection, and handoff proof. Planning for the feedback loop keeps validation from being squeezed out after the first edit.RuleAgent WorkflowSecurity PrivacyPerformanceEncode Nonfunctional RequirementsAGENT-ENCODE-NONFUNCTIONAL-REQUIREMENTSPut invisible constraints such as security, accessibility, latency, and compatibility near the task. Encoding them upfront makes those requirements part of the implementation target.RuleAgent WorkflowToolingAutomationMake Bad Output HardAGENT-MAKE-BAD-OUTPUT-HARDTurn recurring bad agent output into scripts, templates, lint, or checks that fail fast. Mechanical enforcement lowers review cost more reliably than repeated prompt reminders.RuleAgent WorkflowChange ShapeTestingPrefer Build-Preserving EditsAGENT-PREFER-BUILD-PRESERVING-EDITSMake multi-step edits in slices that keep compilation or tests close to green when the route allows it. Build-preserving work keeps failures close to the edit that caused them.RuleAgent WorkflowReview HandoffDocumentationProduce Review PacketsAGENT-PRODUCE-REVIEW-PACKETSHand off agent work with purpose, changed files, evidence, skipped checks, risks, and follow-ups. A review packet lets maintainers inspect the output without replaying the session.RuleAgent WorkflowSecurity PrivacyReview HandoffProve Security ImpactAGENT-PROVE-SECURITY-IMPACTSeparate security hypotheses from proof of reachability, exploitability, assets, and user impact. This keeps prioritization and mitigation tied to demonstrated risk.RuleAgent WorkflowReview HandoffTestingReport Proof in HandoffsAGENT-REPORT-PROOF-IN-HANDOFFSReplace confidence language with the exact checks, inspection, screenshots, and skipped validation behind a handoff. Proof lets reviewers decide what to trust and what remains risky.RuleAgent WorkflowReleaseAutomationVerify Risky Changes With CanariesAGENT-VERIFY-RISKY-CHANGES-WITH-CANARIESUse staged rollout, shadowing, dry runs, or partial publication for changes that can fail only under real conditions. Canaries reduce blast radius while evidence accumulates.

RuleBoundary CorrectnessAgent ContextState TransitionsDefine Compaction InvariantsBOUNDARY-DEFINE-COMPACTION-INVARIANTSState the budget and cut-point rules before deleting, summarizing, or moving context. Explicit invariants make compaction reviewable and reduce the risk that later work treats lossy or nondeterministic summaries as authoritative.RuleBoundary CorrectnessGenerated ArtifactsAutomationStage Generated BehaviorBOUNDARY-STAGE-GENERATED-BEHAVIORValidate generated, reloadable, or plugin-provided behavior in a staging path before promoting it over known-good behavior. Staging adds recovery cost only where runtime-loaded or generated artifacts can fail after deployment.RuleBoundary CorrectnessToolingLocal ConventionsUse 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.

RuleChange ShapeReviewabilityMinimal but CompleteCHANGE-MINIMAL-BUT-COMPLETEKeep the diff as small as the purpose allows while including the evidence that purpose needs. Reviewers should see one coherent unit they can understand, validate, and revert.RuleChange ShapeTestingPin Behavior With Early TestsCHANGE-PIN-BEHAVIOR-WITH-EARLY-TESTSAdd characterization tests before changing messy behavior when the existing contract is unclear. The baseline separates intentional behavior changes from accidental drift.RuleChange ShapeGenerated ArtifactsAutomationSync Generated ArtifactsCHANGE-SYNC-GENERATED-ARTIFACTSUpdate checked-in generated outputs when their source inputs change and they are part of review. Keeping them aligned prevents consumers from seeing stale artifacts.

RuleDocumentationReviewabilityAvoid Unearned PraiseDOCS-AVOID-UNEARNED-PRAISEReplace vague ranking words with observable behavior, evidence, or tradeoffs. Use evaluative claims only when the basis is explicit enough for readers to verify.RuleDocumentationRustdocExamplesBuild Docs Like Users Read ThemDOCS-BUILD-DOCS-LIKE-USERS-READ-THEMReview rendered Rust documentation, links, cfg behavior, and examples in the modes users see. Match validation depth to the risk of feature, metadata, or public example changes.RuleDocumentationDependenciesSource TruthCompare Libraries AccuratelyDOCS-COMPARE-LIBRARIES-ACCURATELYCheck current upstream behavior before comparing nearby libraries or crates. Charitable, source-backed comparisons preserve trust while still helping users choose.RuleDocumentationExamplesDistinguish Example RolesDOCS-DISTINGUISH-EXAMPLE-ROLESName whether an example is focused, canonical, survey, integration, or showcase work. That role controls how complete, copyable, and validated the example must be.RuleDocumentationExamplesRustdocMark Noncompiling Examples HonestlyDOCS-MARK-NONCOMPILING-EXAMPLES-HONESTLYLabel examples that are sketches, partial snippets, or intentionally not run. Honest labels keep readers from treating illustrative code as a supported copy-paste contract.RuleDocumentationExamplesPublic APIProve Real Use With ExamplesDOCS-PROVE-REAL-USE-WITH-EXAMPLESUse examples that show realistic ownership, errors, lifecycle, configuration, or integration shape. Keep them focused, but make them strong enough to prove the contract.RuleDocumentationReviewabilityReview HandoffReview Correctness and Risk FirstDOCS-REVIEW-CORRECTNESS-AND-RISK-FIRSTLead documentation review with false contracts, drift, operability, and unsupported claims before style polish. This separates blocking risk from wording cleanup.RuleDocumentationExamplesSide EffectsShow Side Effects in Live ExamplesDOCS-SHOW-SIDE-EFFECTS-IN-LIVE-EXAMPLESShow setup, visible effects, and cleanup when examples touch live resources or persistent state. Gate costly or externally visible actions so examples stay honest and safe to adapt.RuleDocumentationSource TruthState Current Behavior, Not AspirationDOCS-STATE-CURRENT-BEHAVIOR-NOT-ASPIRATIONDescribe what the system does now and label limitations or future plans separately. Otherwise roadmap language becomes a false contract for readers and agents.RuleDocumentationSource TruthPublic APITreat Docs as ContractsDOCS-TREAT-DOCS-AS-CONTRACTSTreat supported behavior, commands, errors, and examples in docs as promises readers may rely on. Separate normative claims from background, examples, and future plans.RuleDocumentationSource TruthUse Source Links as SupportDOCS-USE-SOURCE-LINKS-AS-SUPPORTUse references to verify, frame, or contrast local guidance instead of supplying the wording. This keeps the repo voice original while still making claims checkable.RuleDocumentationToolingVerify Commands, Paths, and LinksDOCS-VERIFY-COMMANDS-PATHS-AND-LINKSCheck commands, file paths, and linked references because readers treat them as executable instructions. Note assumptions when credentials, services, or platforms prevent a full run.

RulePerformanceReviewabilityAvoid Single-Run Performance ConclusionsPERF-AVOID-SINGLE-RUN-CONCLUSIONSDo not land performance conclusions from one short benchmark run. Repeat and contextualize timing evidence because warmup, scheduling, cache state, and background load can make a single result non-reproducible.RulePerformanceReviewabilityMeasure Goal, Change, and ComparisonPERF-MEASURE-GOAL-CHANGE-COMPAREState the performance goal, baseline measurement, implementation change, and comparison result together. Those pieces let reviewers judge whether the patch improved the relevant workload enough to justify its tradeoffs.RulePerformanceChange ShapeOptimize Measured HotspotsPERF-OPTIMIZE-MEASURED-HOTSPOTSOptimize code that measurement shows is on the important runtime path. This keeps review attention on changes whose user-visible impact justifies altering the code shape.RulePerformanceToolingSource TruthRecord Benchmark ProvenancePERF-RECORD-BENCHMARK-PROVENANCERecord the commands, inputs, tool versions, build profile, and runner conditions behind benchmark numbers. Provenance makes future comparisons meaningful and helps separate real changes from environment drift.RulePerformanceTestingRun Correctness Before TimingPERF-RUN-CORRECTNESS-FIRSTRun relevant correctness checks before interpreting performance timing. Fast code that changes behavior invalidates the benchmark claim and wastes review effort.RulePerformanceAutomationRun Timing Benchmarks SequentiallyPERF-RUN-TIMING-BENCHMARKS-SEQUENTIALLYSerialize timing-sensitive benchmarks when their numbers will be used as evidence. Concurrent runs compete for shared resources and can make the comparison describe the runner more than the code.

RuleReviewabilityChange ShapeReader LocalityClassify Prototype ReuseREVIEW-CLASSIFY-PROTOTYPE-REUSEClassify whether a rebuild is reusing behavior, evidence, replaceable internal shape, or load-bearing boundaries. That separation helps preserve proven compatibility while discarding prototype scaffolding.RuleReviewabilityReview HandoffDocumentationExplain PR Problem Model and ProofREVIEW-EXPLAIN-PR-PROBLEM-MODEL-AND-PROOFUse PR descriptions to explain the problem, mental model, tradeoffs, validation, and documentation impact. Reviewers can then evaluate the diff against stated intent instead of reverse-engineering it.RuleReviewabilitySource TruthDocumentationLabel Speculation as Inferred or UnknownREVIEW-LABEL-SPECULATION-AS-INFERRED-OR-UNKNOWNMark review claims as observed, inferred, assumed, or unknown when the evidence level matters. Clear labels keep guesses from hardening into false project knowledge.

RuleRustPerformanceReviewabilityAdd Benchmarks for Performance ClaimsRUST-ADD-BENCHMARKS-FOR-PERFORMANCE-CLAIMSUse benchmarks when Rust changes rely on speed, allocation, or hot-path claims. The evidence makes performance tradeoffs reviewable instead of relying on intuition.RuleRustTestingAutomationKeep CI High SignalRUST-KEEP-CI-HIGH-SIGNALKeep required Rust checks strict, fast, deterministic, and actionable. Slow or flaky ritual trains maintainers to ignore failures while real drift accumulates.RuleRustDependenciesKeep Compatible Updates in LockfileRUST-KEEP-COMPATIBLE-UPDATES-IN-LOCKFILELet lockfiles record newer compatible dependency versions when the manifest floor has not changed. This tests fresh releases without narrowing downstream compatibility.RuleRustReleaseRelease Only After Artifact ValidationRUST-RELEASE-ONLY-AFTER-ARTIFACT-VALIDATIONValidate the actual release artifact before publishing instead of trusting the working tree. This catches missing files, stale generated content, and packaging mistakes while the release can still be fixed.RuleRustTestingDependenciesRun Feature Gated ValidationRUST-RUN-FEATURE-GATED-VALIDATIONExercise the feature combinations touched by a Rust change so gated code, docs, and integrations actually build. Choose representative combinations when exhaustive feature matrices would be too expensive.RuleRustDependenciesPublic APIUse Honest Minimum DependenciesRUST-USE-HONEST-MINIMUM-DEPENDENCIESSet dependency requirements to the lowest compatible versions the crate actually supports. Raise minimums only for required APIs, fixes, features, security needs, or MSRV interactions.RuleRustReleaseValidate Package Contents Before ReleaseRUST-VALIDATE-PACKAGE-CONTENTS-BEFORE-RELEASEInspect and build the package users will receive, not just the repository checkout. This catches missing assets, accidental inclusions, README drift, and include/exclude mistakes before publication.RuleRustRustdocTestingValidate Rust Docs As CodeRUST-VALIDATE-RUST-DOCS-AS-CODETreat Rust documentation examples, links, feature assumptions, and generated README content as code that must be checked. Use docs builds, doctests, feature-gated checks, and Markdown lint according to the changed surface.RuleRustPublic APIReleaseValidate Semver Breaks Against External UseRUST-VALIDATE-SEMVER-BREAKS-AGAINST-EXTERNAL-USECheck semver-breaking changes against real examples, dependents, or migration paths before treating an API cleanup as cheap. External evidence informs the cost even when security, soundness, or design repair still justify the break.RuleRustReviewabilityWorking Rust Code Not EnoughRUST-WORKING-RUST-CODE-NOT-ENOUGHTreat compilation as necessary but insufficient evidence for long-lived Rust code. Review API shape, docs, errors, tests, features, dependencies, and module organization because users and maintainers inherit those choices.

RuleSource TruthDocumentationPublic APIPrefer Primary Stable SourcesSOURCE-PREFER-PRIMARY-STABLE-SOURCESAnchor durable guidance in sources readers can inspect, compare, and challenge. Use links to clarify judgment, not to decorate rules or depend on private memory.

RuleTestingValidation PolicyCheck Important Feature CombinationsTEST-CHECK-IMPORTANT-FEATURE-COMBINATIONSExercise default, disabled-default, all-feature, and important feature-pair builds. Feature flags change APIs and compile paths, so use a risk-based matrix instead of every combo.RuleTestingAutomationToolingCheck Maintainer Commands in CITEST-CHECK-MAINTAINER-COMMANDS-IN-CIPut documented maintainer commands, or intentionally stronger equivalents, in CI. This keeps local instructions honest while leaving slow or credentialed checks to special jobs.RuleTestingRustAutomationCheck MSRV and PlatformsTEST-CHECK-MSRV-AND-PLATFORMSRun checks for declared Rust versions and supported platforms when they are promised. Compatibility claims are public contracts, so skip matrices only when no such claim exists.RuleTestingValidation PolicyReviewabilityChoose Validation by RiskTEST-CHOOSE-VALIDATION-BY-RISKMatch the amount and kind of validation to the changed surface and failure cost. Cheap checks come first, but risky or uncertain behavior needs targeted evidence.RuleTestingAsyncState TransitionsCover Async Routing Edge CasesTEST-COVER-ASYNC-ROUTING-EDGE-CASESTest late replies, unrelated input, timeouts, and unmatched async responses. These cases protect request correlation and cleanup without relying on wall-clock luck.RuleTestingReader LocalityCover Local Logic with Unit TestsTEST-COVER-LOCAL-LOGIC-WITH-UNIT-TESTSUse unit tests for small local logic such as parsing helpers and policy branches. They give fast precise feedback, while boundary behavior still needs higher-level tests.RuleTestingBoundary CorrectnessCover Navigation BoundariesTEST-COVER-NAVIGATION-BOUNDARIESExercise first, last, empty, oversized, and repeated-navigation states in tests. Boundary cases catch cursor and scrolling bugs that polished manual demos often miss.RuleTestingValidation PolicyCover Policy OutcomesTEST-COVER-POLICY-OUTCOMESTest allowed, denied, redacted, fallback, and unsupported policy outcomes. Policy value lives at decision boundaries, so assert caller-visible behavior instead of internals.RuleTestingPublic APIBoundary CorrectnessCover Public Boundaries with Integration TestsTEST-COVER-PUBLIC-BOUNDARIES-WITH-INTEGRATION-TESTSUse integration tests to prove public module, crate, or adapter boundaries. They catch composition failures unit tests miss, while local logic can stay unit-tested.RuleTestingExamplesRustdocCover Public Examples with DoctestsTEST-COVER-PUBLIC-EXAMPLES-WITH-DOCTESTSCompile public documentation examples as doctests when they do not need fragile state. Executable examples catch stale guidance, reserving no-run or ignored examples for real limits.RuleTestingSource TruthDocumentationKeep Drift Claims AlignedTEST-KEEP-DRIFT-CLAIMS-ALIGNEDTie support claims, fixtures, examples, docs, and API paths to executable drift checks. Stable claims need evidence, but wording-only changes should not break broad tests.RuleTestingReviewabilityMatch Evidence to SurfaceTEST-MATCH-EVIDENCE-TO-SURFACEValidate the actual changed surface, such as rendered docs, API behavior, or byte output. The narrowest relevant proof is more persuasive than unrelated broad test success.RuleTestingToolingPrefer Deterministic TestsTEST-PREFER-DETERMINISTIC-TESTSPrefer tests controlled by fixed inputs, clocks, ordering, and local state. Deterministic failures are reproducible, while real integration checks should be isolated by cost.RuleTestingToolingProve Command Construction and DisplayTEST-PROVE-COMMAND-CONSTRUCTION-AND-DISPLAYTest both executable command shape and displayed command text when users rely on them. Quoting, redaction, ordering, and platform formatting can fail even when a local happy path works.RuleTestingPublic APIProve Contracts Not TriviaTEST-PROVE-CONTRACTS-NOT-TRIVIAWrite tests around observable contracts instead of private helper trivia. This preserves refactoring freedom unless the detail is itself the promised behavior, such as a stable user-facing output contract.RuleTestingDependenciesRustValidate Declared Minimum Dependency VersionsTEST-VALIDATE-DECLARED-MINIMUM-DEPENDENCY-VERSIONSCheck that declared minimum dependency versions still build the supported behavior. Lockfile tests can hide newer API usage, so use targeted minimal-version checks when needed.RuleTestingChange ShapeWrite Regression Tests for Bug FixesTEST-WRITE-REGRESSION-TESTS-FOR-BUG-FIXESAdd a test that fails before the bug fix and protects the repaired contract. Skip only when reproduction is impractical, and then record the closest trustworthy validation.

RuleVCS JJReviewabilityReview HandoffConfirm Broad JJ OperationsVCS-CONFIRM-BROAD-JJ-OPERATIONSConfirm jj operations that abandon, rebase, squash, split, restore, publish, or go broad. Confirmation protects unrelated work when a command can reshape history or public state.RuleVCS JJReview HandoffReleaseConfirm GitHub Remote TopologyVCS-CONFIRM-GITHUB-REMOTE-TOPOLOGYInspect origin, upstream, push remote, PR base, and PR head before publication. Fork and owned-repo layouts differ, so defaults can push or target the wrong repository.RuleVCS JJChange ShapeReviewabilityCreate an Operation Log Point Before ReshapingVCS-CREATE-OPERATION-LOG-POINT-BEFORE-RESHAPINGCreate a recent jj operation boundary before risky stack reshaping. Recovery is easier when there is a known point before rebases, splits, squashes, or repairs.RuleVCS JJReleaseReview HandoffDry Run Surprising PublicationVCS-DRY-RUN-SURPRISING-PUBLICATIONUse dry-run for ambiguous or surprising remote publication, not every routine push. Extra verification pays off when remotes, bookmarks, force-like updates, or PR bases are unclear.RuleVCS JJOwnershipChange 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 JJToolingReviewabilityName Exact JJ Mutation TargetsVCS-NAME-EXACT-JJ-MUTATION-TARGETSSpecify revisions, filesets, bookmarks, and destinations for mutating jj commands. Explicit targets make intent reviewable and prevent defaults from acting on surprising state.RuleVCS JJSource TruthRecover with Operation LogVCS-RECOVER-WITH-OPERATION-LOGUse jj operation-log recovery before destructive cleanup habits. The operation log preserves recoverable graph states, but inspect the target before restoring.RuleVCS JJToolingStop Repeated JJ Retries And Localize StateVCS-STOP-REPEATED-JJ-RETRIES-AND-LOCALIZE-STATEStop repeating a failing jj command after a transient retry and inspect relevant state. Diagnosis beats command spam when locks, sparse paths, bookmarks, or remotes disagree.RuleVCS JJSource TruthUse Evolog and Operation LogVCS-USE-EVOLOG-AND-OPERATION-LOGUse jj evolog for a changes evolution and jj op log for repository operations. Picking the right log distinguishes rewrite history from workspace, bookmark, and import events.RuleVCS JJToolingUse Ignore Working Copy CarefullyVCS-USE-IGNORE-WORKING-COPY-CAREFULLYUse --ignore-working-copy only for understood lock-safe inspection or metadata work. It may read stale file state, so do not use it to bypass normal synchronization before edits.

PatternAgent WorkflowAgent ContextFeedback LoopsBudget Tokens For Feedback Loopsbudget-tokens-for-feedback-loopsLong-running agent work can exhaust context before validation, review, or handoff happens. Reserve space for feedback loops by summarizing durable state and avoiding unnecessary transcript growth.PatternTestingReviewabilityCharacterize Then Fixcharacterize-then-fixBefore fixing incorrect behavior, add a passing test that records the observed result and labels it as known incorrect. Then fix the implementation, update that same expectation to the intended contract, and rewrite the rationale as durable regression context.PatternAgent WorkflowReview HandoffFeedback LoopsClose The Agent Loopclose-the-agent-loopAgent work is incomplete when it stops at edits without checking the result or explaining residual risk. Finish the loop by validating, reporting evidence, and making the next human decision clear.PatternAgent WorkflowReviewabilityDefine Good Before Judgment-Heavy Workdefine-good-before-judgment-heavy-workWork that depends on taste or judgment drifts when success is not defined up front. Establish acceptance criteria, examples, and review dimensions before spending effort on subjective iteration.PatternAgent WorkflowSecurity PrivacyPerformanceEncode Nonfunctional Requirementsencode-nonfunctional-requirementsPerformance, security, accessibility, privacy, and reliability expectations are easy to lose when they live only in prose. Encode important requirements in tests, budgets, schemas, automation, or review gates where the system can keep enforcing them.PatternDocumentationSource TruthLabel Doc Claims By Evidencelabel-doc-claims-by-evidenceDocumentation loses trust when speculation, observed behavior, policy, and verified facts look the same. Label claims by their evidence level so readers know what can be relied on and what still needs confirmation.PatternAutomationToolingAgent WorkflowMake Bad Output Mechanically Hardmake-bad-output-mechanically-hardRepeated review failures usually belong in a tool, type, schema, template, lint, or checklist instead of another reminder. Encode stable rejection criteria early, but keep escape hatches when legitimate exceptions are common.PatternAgent WorkflowAutomationFeedback LoopsPractice Agent Workoutspractice-agent-workoutsHigh-risk or repeated agent workflows are unreliable when first exercised during real work. Build safe practice tasks with explicit win conditions so the workflow, skill, or runbook can improve before pressure arrives.PatternReview HandoffAgent WorkflowProduce Review Packetsproduce-review-packetsReviewers lose time when a handoff contains only a diff and no acceptance evidence. Package the goal, validation, risks, and proof artifact in proportion to the review burden.PatternSecurity PrivacyReview HandoffProve Security Impactprove-security-impactSecurity reports create noise when they imply exploitability without showing reachability or consequence. Prove the attacker path and impact, or clearly label the finding as an unproven hypothesis.PatternDocumentationSource TruthRemediate Doc Driftremediate-doc-driftDocumentation drift misleads readers when behavior, workflow, or project shape has moved on. Fix the source of truth and nearby references together, choosing whether the code or the doc represents the intended contract.PatternReview HandoffReport Verification Honestlyreport-verification-honestlyHandoffs become risky when verification is overstated, omitted, or blurred with assumptions. Report exactly what ran, what passed or failed, what was not checked, and what risk remains.PatternReviewabilityReview HandoffReview Proof Not Just Codereview-proof-not-just-codeCode review is weaker when it inspects the diff without checking whether the claimed behavior was proven. Ask for the smallest trustworthy evidence that the change works and that the likely failure mode was covered.PatternTestingReviewabilitySmallest Trustworthy Verificationsmallest-trustworthy-verificationVerification is weak when it is either skipped or broad without covering the likely failure. Run the cheapest check that could catch the risk introduced by the change, broadening only when shared contracts or user-visible behavior require it.PatternTestingObservabilityTest Observable Behaviortest-observable-behaviorTests that pin private structure can block useful refactors while missing broken user outcomes. Test observable outputs, errors, side effects, state, events, and boundaries, reserving private tests for dense rules that are otherwise hard to reach.PatternTestingAutomationVerify With Canaries Before Cutoververify-with-canaries-before-cutoverAutomation is risky when production cutover is the first real proof. Use a canary path, rollback plan, and human approval for operations with remote access, credentials, production data, or long-lived service impact.PatternReview HandoffReviewabilityWrite PR Narrativewrite-pr-narrativeA correct diff can still waste reviewer attention when it lacks purpose, risk, review order, and verification. Write the PR narrative as a guide to the decision the reviewer needs to make, scaled to the burden of the change.

PrincipleChange ShapeReviewabilityReview HandoffChange Shape Controls Review Costchange-shape-controls-review-costChange boundaries determine how much intent, risk, validation, and revert cost a reviewer must reconstruct. Use the smallest coherent unit that preserves trust without splitting one decision into noise.PrincipleDocumentationSource TruthPublic APIDocs Are Contractsdocs-are-contractsDocumentation near code is part of the supported behavior surface. Keep prose, examples, and implementation aligned so humans and agents can rely on the same contract.PrinciplePerformanceTestingMeasure Before Optimizingmeasure-before-optimizingPerformance work needs a workload, baseline, goal, change, and comparison. Evidence keeps optimization from becoming readability, dependency, or API churn without a proven payoff.PrincipleTestingFailure OutputTests Should Explain Failurestests-should-explain-failuresA failing test should point at the broken contract, not merely report that a predicate was false. Choose assertion shapes that expose the relevant value, variant, order, or case name.

MechanismRustPublic APIReleaseRust API And Release Checksrust-api-and-release-checksCargo release, semver, feature, packaging, and minimum-version checks protect downstream users from accidental compatibility changes. Use these checks when public API, crate metadata, or release artifacts are part of the changed surface.MechanismRustRustdocDocumentationRust Docs Validationrust-docs-validationDoctests, Rustdoc warnings, rendered docs, and docs.rs-style builds prove documentation surfaces the way users will see them. Use this mechanism when examples, public API docs, feature docs, or release-facing documentation changes.MechanismRustToolingAutomationRust Lints And Formattingrust-lints-and-formattingRust and Markdown formatting plus targeted project lints encode stable mechanical preferences. The mechanism removes repeat style debate from review while leaving design judgment to humans and higher-level guidance.MechanismRustToolingAutomationRust Tooling Profilerust-tooling-profileThe broad Rust tooling profile gathers lints, docs, release, CI, performance, and agent workflow checks in one place. Use it as a menu of mechanical supports, not as a substitute for project-specific risk judgment.MechanismTestingPerformanceToolingTesting And Benchmarkingtesting-and-benchmarkingTest, feature-matrix, fuzzing, property, and benchmark tools should be chosen by risk and feedback cost. This mechanism helps match validation depth to the behavior, integration surface, or performance claim under review.

AgentAgent WorkflowAgent ContextReview HandoffCore Agent Instructionsagent-core-instructionsBroad baseline instructions for coding agents working in repositories that adopt these development preferences. The snippet keeps AGENTS.md short while routing agents to canonical guides, principles, mechanisms, and the reviewed rule pack.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.