Tooling

Commands and interfaces that make a preferred workflow repeatable.

60 items in this guidance cluster.

Tagged guidance

Coding 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.JJ workflowJJ workflow guidance covers source-control inspection, reviewable changes, descriptions, bookmarks, publication, and recovery in jujutsu repositories. It keeps agents and maintainers thinking in jj changes and operations instead of Git-shaped habits.

Grant scoped capabilitiesGive agents only the permissions and external authority the task actually needs. Scoped capability keeps progress possible while reducing accidental mutation, publication, or exposure.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.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.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.

Give tools identity policy and limitsGive effectful callable units typed identity, authorization policy, cancellation, and bounded output. The added ceremony is reserved for real tool boundaries where auditability, recovery, and blast-radius control matter.Make dynamic conflicts deterministicDefine stable ordering, duplicate handling, priority, or override policy for dynamic registrations. Deterministic conflict behavior prevents hash order or load timing from changing which plugin, guest, generated item, or handler wins.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.Track dynamic registration provenanceStore stable source names, versions, paths, owners, or generated identifiers for extension, guest, generated-code, and config registrations. Provenance makes conflicts and failures diagnosable while avoiding sensitive source details.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.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.

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

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.

Configure docs.rsConfigure docs.rs metadata when features, cfgs, or rustdoc flags affect rendered API docs. Users should see the documentation surface the crate expects to support.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.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.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.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.

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

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.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.Configure JJ pagerScope pager control with --no-pager, JJ_PAGER=cat, or session configuration. Direct output keeps source-control evidence visible without changing the users global pager.Do not fall back to Git for JJ issuesDiagnose jj locks, pager issues, and state problems through jj before switching tools. Git bypasses jj change-graph semantics, so use it only for transport after jj state is coherent.Inspect sparse stateCheck sparse checkout state before treating a missing path as absent from history. Sparse patterns can hide files, so inspection prevents recreating or editing the wrong path.JJ as source of truthUse jj for local workflow in repositories with .jj state. This preserves descriptions, stack shape, operation-log recovery, and bookmark semantics.Match JJ topology to repo roleAlign fetch remotes, push remotes, tracked bookmarks, aliases, and PR bases to repo role. Owned, maintainer, and fork-only workflows need different topology assumptions.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.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.Repair remote topology coherentlyRepair fetch, push, tracking, trunk alias, PR base, and PR head assumptions together. Remote topology is coupled, so partial fixes can leave publication commands half-correct.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.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.Treat bookmark remote syntax as version sensitiveVerify bookmark@remote and remote-bookmark syntax against the installed jj version. Durable guidance should avoid assuming one spelling works across commands and releases.Use Git-formatted diffs for agentsPrefer jj diff --git when agents or patch-oriented tools need diff text. Git patch format preserves hunks and paths in a shape those consumers can parse reliably.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.Workspace add for second checkoutsUse jj workspace add only when a task needs another filesystem checkout. Ordinary review separation should use jj new; workspaces fit clean validation or parallelism.

Choose 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.Code 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.Grant scoped agent capabilitiesBroad tool access increases the blast radius of agent mistakes and makes review harder. Grant the smallest capabilities needed for the current task, then expand deliberately when the work proves it needs more reach.Keep 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.Make 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.Make the change easy firstSome changes are risky because the path to make or verify them is unnecessarily hard. First add the smallest harness, boundary, helper, tool, or runbook that makes the real change cheaper to understand and review.Prefer 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.Prefer 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.Shape tool output for agentsHuman-oriented tool output can bury the failure signal an agent needs to act. Prefer quiet summaries, structured output, and saved full logs so agents see the actionable slice first without losing debugging context.Teach 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.

Agent 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.JJ topology is repo role dependentJJ publication behavior depends on whether the checkout is owned, maintained, or fork-based. Align remotes, bookmarks, trunk, and GitHub handoff with that role before mutating public state.Mechanize 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.

Guidance 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.JJ agent workflowNoninteractive jj defaults, topology checks, and local override conventions make agent source-control work safer. The mechanism keeps local workflow state explicit without leaking private checkout assumptions into shared artifacts.Rust 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.Rust 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.Testing 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.

Coding agent workflow instructionsCompact workflow instructions for repositories that delegate implementation or review work to coding agents. The snippet emphasizes objectives, boundaries, durable handoff, repo-owned context, and feedback that becomes reusable guidance.Jujutsu agent instructionsCompact source-control instructions for coding agents working in repositories that use jujutsu. The snippet covers fresh changes, descriptions, non-interactive commands, recovery, remote handoff, and publication approval.