Coding agentsinspect, edit,and verify.
Coding agents:change codeand show their checks.
A coding agent inspects a repository, forms a bounded plan, uses tools, reads the results, revises its work, and returns the final diff with evidence.A coding agent can explore a software project, make a focused change, run checks, and revise when those checks disagree. Its job is to return the change plus a reason to trust it.
- SEARCHLOOK FIRSTbefore changing
- PATCHCHANGE LESSthe smallest surfaceonly what the task needs
- PROVECHECKbefore handing back
AGENTS.mdsrc/export/tests/- inspect→
- plan→
- patch→
- test
2 source files changed
2 checks passed
READY FOR REVIEW ✓Code completion predicts text. A coding agent uses repository feedback.Autocomplete finishes a line. An agent works through a checked task.
A coding agent closes a feedback loop: observe the repository, make a bounded change, run a check, and revise from the result.A coding agent looks around, makes a small change, runs a check that can disagree, and revises when the check fails.
Current code context goes in.It predicts what comes next.
const total = items.reduce(…)A likely next line appears.A plausible continuation comes out. Useful—and then it stops.That suggestion may be useful, but it does not inspect or test the rest of the project.
NO FEEDBACK LOOPA task is evaluated against the repository.A task meets the whole project.
- 01Read rules + current stateRead the project and its rules
- 02Search for the real change surfaceFind the files that actually matter
- 03Patch, execute, inspect, reviseChange, test, inspect, revise
- 04Return the diff + evidence + caveatsShow what changed, the checks, and any uncertainty
A useful handoff includes the diff, the checks that passed, and any remaining uncertainty.A useful result includes the change, the checks that passed, and anything still uncertain.
Repository evidence changes the quality of the patch.
Same task. Same model. One control changes how much repository evidence the loop may collect before it returns a result.
Keep column order stable. Update relevant tests. Do not edit generated output or unrelated dirty files.
Lower settings remove observations and checks that can expose a wrong edit.
- 01git status + AGENTS.md
Read instructions and current state
Find local rules, allowed files, and three unrelated user edits.
- 02rg "owner|csv"
Locate the source
Search connects the schema, exporter, and targeted test.
- 03src/export/csv.ts
Edit the smallest source change
Change the header and source serializer; leave nearby cleanup alone.
- 04pnpm test csv
Run a focused check
FAIL: row serializer omitted owner. Revise the patch. PASS.
- 05typecheck + git diff
Inspect the final diff
Types pass. Diff matches scope. Hand back checks and caveats.
Targeted tests and typecheck pass; the final diff is inspected; pre-existing dirty files stay untouched.
Tool results determine the agent’s next step.
Models propose the next action. The runtime supplies tools, permissions, files, command output, and stopping conditions. Each observation changes what action makes sense next.
- 01INSPECT
Read project instructions and current state.
Load the task, nearest repository instructions, current worktree state, and relevant project map.
- 02LOCATE
Trace the change surface.
Find names, call sites, tests, and ownership before deciding which files to edit.
- 03BOUND
Set boundaries before editing.
Name the files, constraints, expected behavior, and checks. Ask before crossing a permission boundary.
- 04PATCH
Edit the source of truth.
Edit in reviewable increments. Generated files, build output, and vendored code usually have a source upstream.
- 05EXERCISE
Run the closest meaningful check.
Start with a targeted test, typecheck, lint, or build that can expose the specific mistake quickly.
- 06HAND BACK
Return the diff and its evidence.
Inspect the diff. Report what changed, what passed, what was preserved, and what remains uncertain.
A failed check gives the loop specific information for the next revision.
Define the outcome, boundaries, and completion checks.
The agent can discover implementation details. The task should provide the desired outcome, acceptable scope, and definition of done.
“Improve CSV exports.”
- No observable result
- No boundary around adjacent cleanup
- No check that defines “improved”
CSV exports include owner_name after project_name.
Existing column order stays stable; blank owners serialize as empty.
Exporter source + focused tests. Preserve unrelated dirty files.
Do not edit generated clients or change the public schema.
Run export tests and TypeScript checks; report anything not run.
Let the agent discover where the change belongs. Specify what success means.
Six rules for safe, reviewable repository work.
- 01READ
Read the nearest instructions.
Repository guidance, directory-specific rules, conventions, and requested commands define the local constraints.
- 02STATUS
Take a worktree baseline.
Check status before editing. Pre-existing modifications belong to their author; preserve them and avoid accidental bundling.
- 03TRACE
Search through the behavior.
Find definitions, references, tests, schemas, and generators. The first matching file is a clue, not permission to edit.
- 04SMALL
Patch at checkpoint size.
Make one coherent change, inspect the diff, run the closest check, then widen only when evidence requires it.
- 05ASK
Respect sandbox and approval boundaries.
Sandboxes and approval gates are part of the system. If a command needs more access, explain why and request it—do not route around it.
- 06PROVE
Verify in proportion to risk.
A copy change may need a build. A data migration needs considerably more. “Looks right” is not an executable check.
- observe
- edit one idea
- inspect diff
- run closest check
- record evidence
Six recurring coding-agent failures.
Most coding-agent failures are ordinary software-process mistakes performed quickly and at scale.
Editing before searching
Behavior: Opens the obvious file and edits immediately.
Correction: Search references, tests, and ownership before choosing the change surface.
Editing generated output
Behavior: Fixes dist/, a generated client, lock output, or compiled assets.
Correction: Find the generator or source-of-truth; regenerate only when the workflow calls for it.
Overwriting existing work
Behavior: Treats every existing diff as agent-created—or disposable.
Correction: Baseline status, isolate the requested patch, and name what was intentionally preserved.
Expanding the scope
Behavior: Mixes the requested fix with refactoring, formatting, and unrelated cleanup.
Correction: Use small coherent patches. Review and verify before expanding scope.
Bypassing permissions
Behavior: Works around a sandbox, secret, network, or approval boundary.
Correction: Pause, state the blocked action and reason, then request the narrow authority needed.
Claiming success without checks
Behavior: Reports success because the edit looks plausible.
Correction: Run the nearest meaningful check, inspect its output, and disclose checks that could not run.
The model chooses. The runtime makes it real.
“Agent” describes a system, not just a model call. The surrounding runtime decides which files and tools are visible, executes actions, returns observations, enforces permissions, and stops the loop.
function repair(task, repo, policy):
rules = read_nearest_guidance(repo)
baseline = inspect_status(repo)
evidence = search(task, repo)
plan = bound_change(task, rules, evidence)
while plan.has_next_step():
require_permission(plan.next_step, policy)
patch = edit_smallest_source(plan)
result = run_closest_check(patch)
if result.failed:
plan = revise_from(result)
continue
return handoff(
diff=inspect_diff(baseline),
checks=result.passed,
caveats=result.not_run
)
return blocked(reason, next_evidence_needed)Four common misconceptions about coding agents.
“It reads the whole repository.”
Usually it sees selected files, search results, instructions, diffs, and command output inside a bounded context. Good retrieval and inspection still matter.
“More autonomy means fewer checkpoints.”
Longer loops create more opportunities to drift. Small patches and explicit checkpoints make recovery cheaper.
“Passing tests proves correctness.”
Tests prove only the expectations they encode. Review the diff, consider missing coverage, and state caveats.
“The fastest agent makes the biggest patch.”
A smaller change is easier to inspect, test, revert, and trust. Large patches make review and recovery more expensive.