Coding agents
Coding-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.
This guide covers agent-task setup, AGENTS.md guidance, agent-output review, and decisions that
should become tooling instead of another prompt.
Use this guide with Software change preferences. Agent work still needs small reviewable chunks, honest verification, and careful working-copy ownership.
Core preference
Treat agents as productive workers in a system, not as magic sessions to supervise line by line. A good agent workflow gives the agent enough objective, context, tools, authority, and validation to produce a reviewable artifact while preserving human attention for ambiguity and judgment.
Optimize for:
- Objectives with boundaries over brittle step lists.
- Durable repo-owned context over transient prompt memory.
- Tools, checks, and workspaces over repeated human steering.
- Review evidence over confidence language.
- Long-term coherence over one prompt's local success.
Objectives and acceptance
Define the work before delegating it or starting judgment-heavy execution. The useful setup is not a step list; it is a clear objective with boundaries, success criteria, available tools, and expected proof at handoff. For naming, grouping, review-shape, public API, or other taste-heavy work, establish the quality bar before changing the artifact, then leave room for the agent to choose a better route inside safe boundaries.
Use Give agents objectives with boundaries when a task should preserve the user's goal without freezing the implementation route. Use Define good before judgment-heavy work when the acceptance criteria, evidence, or remaining human judgment need to be explicit. Use Agent give objectives with boundaries and Agent Define Good Before Judgment-Heavy Work when this guidance needs compact agent-execution wording.
For ambiguous work, spend human attention at the ambiguity boundary. Use Spend human attention on ambiguity before asking an agent to bury product, architecture, security, or public API decisions inside a large diff.
Carry existing authorization through the task. Resolve routine implementation and validation details within it, and ask only about unresolved choices that materially change the result or scope. Define acceptance from the user's goal and examples without making every criterion another permission gate.
Context and knowledge
Agents work best when the repo is legible and the relevant context arrives at the point of use. Keep
large or reusable context on disk, keep AGENTS.md as a map, and make accepted artifacts part of
the discovery path.
Use Distill from blessed artifacts when existing code, tests, docs, or reviews are denser than the prompt. Use Deliver context just in time and Use disk as context sink when the context is too large or too specialized for one static instruction block.
Use Use AGENTS.md as map to keep top-level instructions compact and linked. Use Optimize for agent legibility when repo structure, docs, commands, and runtime signals should help future agents find and validate the right thing. For ongoing projects whose software doctrine no longer fits in a short map, use Project operating manual as the project-owned interpretation layer between the broad catalog and the current repo. Use Agent keep durable context on disk, Agent Use AGENTS.md As Map, and Agent distill from blessed artifacts when context should live in repo-owned artifacts rather than transient prompt memory.
Tools and guardrails
Prefer tools and checks over heroic prompting. If a mistake is repeatable, move it into the cheapest enforcement layer: type shape, API design, lint, test, formatter, schema, template, runbook, or review checklist.
Use Prefer tools over prompts, Make bad output mechanically hard, and Teach agents through tools when feedback points to a missing guardrail or capability. Use Agent prefer tools over prompts and Agent make bad output hard when repeated prompt steering should become a tool, check, template, or schema.
Use Make the change easy first when the requested change is risky because the repo lacks a harness, test, boundary, or workflow that would make the behavior change straightforward. Use Code is memory of process and Keep automations repo owned when stable process knowledge should become a checked artifact.
For systems that agents can reload, extend, or self-modify, prefer staged changes with validation and rollback over direct mutation of the live runtime. Generated or guest code should be inspectable after failure without replacing the last known good behavior.
Use Agent prefer build preserving edits when a long broken state would make recovery and review harder.
Workspaces and capabilities
Keep agent work isolated by task. Each independent edit should have a clear workspace, source-control change, ownership boundary, logs, and cleanup policy. Do not make a human track five interactive sessions when the work can be represented as durable tasks.
Use Manage agent work not sessions, Isolate agent workspaces, and Preserve agent context coherence when parallel or long-running work would otherwise smear state across threads and checkouts. Use Agent isolate workspaces by task and Agent preserve human work when multiple edits, agents, or human changes share source-control state.
Grant only the authority the task needs. Use Grant scoped agent capabilities and Keep secrets out of context when credentials, external systems, or privileged tools are involved. Use Agent grant scoped capabilities and Agent keep secrets out of context when task authority, credentials, or external systems need explicit limits.
Verification and review
Agent output should arrive with proof. The right proof depends on the task: failing and passing tests, logs, screenshots, traces, benchmark output, specialist reviews, canaries, or deployment notes.
Review Stance
Review agent output from the perspective of a future maintainer who did not write the code. Prioritize correctness, edge cases, API clarity, documentation truthfulness, rendering behavior, terminal-state behavior, and focused tests for the contract.
When code is hard to read, identify the cause precisely: concept mixing, poor ordering, hidden state, vague names, too much abstraction, or missing tests.
Edit Preparation
Before editing, identify the owning module, local dependencies, existing tests, and narrowest useful validation command. While editing, preserve current user behavior unless the task intentionally changes it. Before handoff, report focused checks, broad checks, skipped checks, residual risk, and follow-up.
Handoff Shape
Handoff notes should say what changed, where the important files are, what validation ran, what did not run, and what risk remains. Avoid long implementation diaries.
Keep implementation, observed behavior, and product acceptance separate. For UI work, inspect and exercise complete workflows in the built app; test counts and screenshots alone do not establish that the result is usable. For library reviews, state compatibility and release impact against a named baseline and consumer configuration. Use Match Evidence To Surface for choosing direct checks.
Use Review proof not just code, Produce review packets, and Report verification honestly when handing work to a maintainer. Use Review Agent Output As Future Maintainer when evaluating whether agent output is maintainable after the session context disappears. Use Agent produce review packets and Agent report proof in handoffs when a handoff needs compact proof-focused wording.
For risky operations, use Verify with canaries before cutover. For security work, use Prove security impact so hypotheses, reachability, and concrete impact stay separate.
Feedback loops
Every repeated correction is a chance to improve the system. Capture reusable feedback in patterns, guides, tools, tests, templates, or runbooks so future sessions do not need the same steering.
First establish whether the guidance was missing, unclear, unreached, or ignored. Inspect the instruction, action, correction, and result together, including successful counterexamples. Adding another rule does not repair a routing failure or prove that an existing rule was followed.
Use Turn feedback into guidance, Record agent operating lessons, Close the agent loop, and Garbage collect agent drift when agent work exposes a repeated failure mode.
Budget time and tokens for loops that reduce human attention and improve outcomes. Use Budget tokens for feedback loops when evaluating review agents, cleanup loops, security scans, docs checks, or harness evals. Use Agent budget for feedback loops and Agent turn feedback into guidance when repeated corrections should become durable guidance or automation.
Maintainer review loop
Match the loop to the user's requested mode. In an interactive review session, present concrete next chunks at the agreed decision points. In an authorized implementation batch, keep changes reviewable and validate them while continuing through the agreed scope. A small change boundary does not require another permission question.
When a choice is needed, name the actual next chunk and recommend a path. Start a fresh jj change when the next unit is separate. Mark new guidance reviewed only after the maintainer explicitly accepts it; permission to continue implementing is not acceptance of its contents.
Explain why each offered path is worth choosing. Include the tradeoff that matters for review: scope, risk, latency, validation depth, naming, structure, or follow-up cost. If the maintainer gives feedback instead of choosing the next chunk, address that feedback before continuing.
For fast manual review sessions, separate note capture from correction. Capture reviewer notes in a durable queue without applying corrections unless asked, then apply corrections later in scoped batches such as one content type, one page, or one ownership area.
Use Agent present concrete next options and Agent separate notes from corrections when maintainer review needs clear next choices or a separate review-note queue.
Long-term coherence
Agent work should scale to the next many changes. A correct-looking patch can still damage the system if it adds parallel concepts, hides side effects, weakens tests, or loses the repository's shape.
Use Optimize for long term coherence, Preserve intent over literalism, and Encode nonfunctional requirements when the prompt is narrower than the actual quality bar. Use Agent encode nonfunctional requirements and Agent preserve intent when acceptance depends on compatibility, privacy, performance, determinism, or the user's real goal.
Use Ask what were you trying to achieve when surprising legacy code may be preserving an old intent. Use Choose good enough tools and Prefer in distribution tools when selecting tooling for agent-friendly work.
Agent snippet
For copyable AGENTS.md guidance, use Coding agent workflow instructions. For a
broader repo baseline, use Core agent instructions. For a compressed execution pack
generated from reviewed rules, use Reviewed rule agent pack.
Review questions
Task Setup
- Is the objective clear without overfitting the implementation path?
- Are boundaries, capabilities, and forbidden actions explicit?
- Is the relevant context on disk or linked from a stable owner?
- Can the agent validate the work with tools it can access?
Handoff And Loop
- Does the handoff include proof instead of confidence language?
- Did feedback become a reusable improvement where appropriate?
- Did the agent continue already-authorized work and pause only at a real decision boundary?
- Does each option explain why that path would be chosen?
- Does the evidence establish the claimed outcome on the relevant user or consumer surface?
- Did the retrospective distinguish a guidance defect from a routing or execution failure?
Coherence
- Does this change preserve the repo's long-term concepts and reviewability?