Automation

Checks and maintenance run mechanically instead of being remembered each time.

39 items in this guidance cluster.

Tagged guidance

RuleAgent WorkflowToolingVerificationMake 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 WorkflowToolingDocumentationPrefer Tools Over PromptsAGENT-PREFER-TOOLS-OVER-PROMPTSMove repeated instructions into tools, checks, templates, or durable guides. Tooling catches failures even when prompts are short, compacted, or interpreted differently.RuleAgent WorkflowDocumentationReviewabilityTurn Feedback Into GuidanceAGENT-TURN-FEEDBACK-INTO-GUIDANCEConvert repeated review corrections into rules, templates, snippets, or checks. Durable guidance fixes the workflow problem instead of requiring the same steering again.RuleAgent WorkflowVerificationReleaseVerify 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 CorrectnessToolingAgent WorkflowMake Exec Tools NoninteractiveBOUNDARY-MAKE-EXEC-TOOLS-NONINTERACTIVEDefault agent, CI, and background exec paths away from prompts, editors, pagers, and credential UI. Commands then fail or complete predictably, while human interactive modes remain explicit opt-ins.RuleBoundary CorrectnessGenerated ArtifactsVerificationStage 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.

RuleChange ShapeGenerated ArtifactsOwnershipRespect 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.RuleChange ShapeGenerated ArtifactsVerificationSync 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.

RulePerformanceVerificationRun 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.

RuleRustSecurity PrivacyToolingDeny Accidental UnsafeRUST-DENY-ACCIDENTAL-UNSAFEUse a crate-level lint when a crate intends to avoid unsafe code entirely. Executable policy catches accidental unsafe before it becomes normal implementation detail.RuleRustToolingLocal ConventionsEncode 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.RuleRustVerificationTestingKeep 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.RuleRustToolingFailure OutputKeep Lints ActionableRUST-KEEP-LINTS-ACTIONABLEEnforce lints that improve correctness, API quality, docs, portability, or maintenance in ways reviewers want automated. Scope suppressions tightly so exceptions stay visible.RuleRustToolingReviewabilityPrefer Expect For Lint SuppressionsRUST-PREFER-EXPECT-FOR-LINT-SUPPRESSIONSUse #[expect] for targeted lint suppressions that should disappear when the warning is fixed. Reserve broad allow attributes for deliberate policy choices that are not expected to expire.

RuleTestingToolingVerificationCheck 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.RuleTestingRustVerificationCheck 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.RuleTestingReviewabilityPerformanceKeep Slow Checks out of PR CITEST-KEEP-SLOW-CHECKS-OUT-OF-PR-CIKeep long fuzzing, exhaustive matrices, and noisy benchmarks out of required PR CI. Fast gates preserve review flow, while heavier checks belong in release or scheduled validation.RuleTestingDocumentationExamplesRun Docs as a First-Class GateTEST-RUN-DOCS-AS-FIRST-CLASS-GATETreat documentation checks as real validation for examples, links, commands, and claims. Prose-only edits may need less proof, but API-facing docs should fail before stale guidance ships.RuleTestingToolingReviewabilityRun Fast Format and Lint Gates EarlyTEST-RUN-FAST-FORMAT-AND-LINT-GATES-EARLYRun cheap format and lint gates early in the feedback loop. They remove mechanical failures quickly, but they do not replace validation of risky behavior.

RuleVCS JJAgent WorkflowToolingAvoid Interactive JJ in Agent WorkVCS-AVOID-INTERACTIVE-JJ-IN-AGENT-WORKUse noninteractive jj commands with explicit messages, targets, and files in agent work. Interactive editors, prompts, merge tools, and pagers can hang unattended sessions.RuleVCS JJToolingQuote Revsets and Shell SyntaxVCS-QUOTE-REVSETS-AND-SHELL-SYNTAXQuote jj revsets, bookmark syntax, and other shell-sensitive command fragments. Shell metacharacters can alter commands, so examples should prefer simple safe quoting.RuleVCS JJToolingAgent WorkflowRun JJ Mutations SequentiallyVCS-RUN-JJ-MUTATIONS-SEQUENTIALLYDo not overlap jj commands that write repo, working-copy, bookmark, or config state. Sequential mutations avoid locks, stale reads, and confusing operation order.

PatternSource TruthToolingAgent WorkflowCode Is Memory Of Processcode-is-memory-of-processCode accumulates the history of decisions, shortcuts, and workflows that produced it. When changing it, preserve useful operational memory while removing obsolete process scars that no longer serve readers.PatternAgent WorkflowAgent ContextSource TruthGarbage Collect Agent Driftgarbage-collect-agent-driftAgent-generated notes, plans, and assumptions can outlive their usefulness and mislead later work. Periodically remove, update, or promote them so durable guidance stays current and temporary scaffolding does not become false context.PatternToolingOwnershipLocal 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.PatternToolingAgent WorkflowVerificationMake 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 WorkflowVerificationFeedback 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.PatternToolingAgent WorkflowPrefer Tools Over Promptsprefer-tools-over-promptsProse instructions are weak guardrails for repeatable constraints because agents can forget or apply them too late. Use tools, tests, templates, and checks for mechanical preferences, while reserving prompts for judgment and tradeoffs.PatternToolingAgent WorkflowTeach Agents Through Toolsteach-agents-through-toolsRepeated agent confusion often means the repo lacks a command, fixture, wrapper, or check rather than another instruction. Convert repeatable setup, inspection, validation, and remediation into tools when they will improve future runs.PatternAgent WorkflowSource TruthFeedback LoopsTurn Feedback Into Guidanceturn-feedback-into-guidanceRepeated steering signals that a preference is missing from durable repo guidance or tooling. Fix the current artifact and encode the reusable lesson at the right level when the feedback applies beyond one line.PatternVerificationTestingVerify 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.

PrincipleAgent WorkflowToolingAgent ContextAgent Instructions Are Operational Controlsagent-instructions-are-operational-controlsAgent instructions should change future behavior, not merely restate a preference. Compact rules need enough trigger, purpose, and boundary context for agents to apply them without blind literalism.PrincipleToolingAgent WorkflowReviewabilityMechanize Repeated Feedbackmechanize-repeated-feedbackRepeated corrections should become checks, templates, generators, lints, or reusable guidance when the pattern is stable. Mechanizing the feedback moves human attention back to judgment instead of recall.

MechanismDocumentationSource TruthReviewabilityGuidance Content Model Stewardshipguidance-content-model-stewardshipContent-model stewardship keeps guides, rules, patterns, principles, mechanisms, references, snippets, and downstream templates in distinct roles. The mechanism combines mechanical inventory checks with maintainer review queues for overlap, thin guidance, noisy tags, and subjective content-quality decisions.MechanismToolingDocumentationSource TruthGuidance Generation And Auditguidance-generation-and-auditGenerators and audits keep rule indexes, compressed agent snippets, downstream templates, and Markdown synchronized. The checks catch recurring drift so review attention stays on judgment instead of mechanical bookkeeping.MechanismRustToolingDocumentationRust 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.MechanismRustToolingVerificationRust 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.MechanismTestingPerformanceVerificationTesting 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 WorkflowGenerated ArtifactsSource TruthReviewed Rule Agent Packagent-reviewed-rule-packGenerated compact execution surface for every reviewed rule. The pack gives agents stable rule IDs and instructions while leaving rationale, examples, and deeper context in the canonical rule files.