# Coding agent best practices

> Mac Anderson's guide to coding agent best practices: task scope, code context, tests, review, and evidence before autonomous agents ship software.

Published 2026-10-28 by Mac Anderson. Canonical page: https://macanderson.com/research/coding-agent-best-practices

A coding agent can finish a patch before anyone has agreed on what a correct patch must do. The diff looks plausible. The tests pass. A caller still breaks because the task never named the behavior it had to preserve.

My research focuses on the system around that patch: the task, the context, the tools, and the checks that decide whether it can ship. These are practices for teams using autonomous software developer agents. They are a working method drawn from the [field manual](/manual), not a claim that one prompt makes an agent reliable.

## Task scope

Give the agent an observable result. Name the affected behavior, the constraints, and the evidence needed to accept the change. For a defect, include a way to reproduce it. For a feature, include an example of a user completing the task.

A useful brief for a subscription form might say: an invalid address stays on the page, an error explains how to fix it, and a failed request preserves the entered text. That brief gives the agent something it can test.

Assign one owner to each shared edit. Parallel work helps when tasks have separate files or interfaces. Two agents changing the same function need a handoff.

## Repository context

Start with the code that owns the behavior, its callers, the tests, and the repository's rules. Read the error path as well as the success path. A small patch can change a contract used elsewhere.

Search can find the likely entry point. A [code graph](/research/code-graphs-vector-search-graph-rag) can add callers, imports, and tests. Neither replaces reading the current source. Check the revision the index describes before using its results to make a change.

Keep durable instructions in the repository. State how to run the relevant checks and where the system enforces access rules. Avoid filling the prompt with logs that have no bearing on the task.

## Verification

For a bug, write a test that fails for the reported behavior before the fix and passes afterward. That proves the test can see the defect. A test that only repeats the new implementation provides less evidence.

Check failure branches: an empty result, a rejected request, a timeout, or a missing permission. Choose checks by the changed behavior. A text edit and a database migration need different evidence.

A benchmark score answers a narrower question than whether your change works in production. Read [what SWE-bench measures](/research/what-swe-bench-measures-and-what-it-misses) before using a leaderboard to choose a delivery process.

## Review and delivery

Have a separate review inspect the diff against the brief. Ask what can break, which caller depends on the old behavior, and which claim the tests do not prove. The reviewer needs the patch and the requirements, not a verdict supplied by the author.

Attach results to the commit that was checked. If the patch changes after review, decide which checks the new edit affects. A green result from an older commit does not establish that the current code works.

Treat merge, deployment, and live behavior as separate facts. Record the deployed revision and verify the changed behavior where it runs. The [agent software development lifecycle](/research/agent-software-development-lifecycle) puts those steps in order.

## Research and practice

The [reliability and cost research](/research/why-agents-fail-measuring-reliability-and-cost) examines why a successful demonstration is weak evidence for repeated operation. The [self-correction research](/research/the-limits-of-self-correction-and-model-collapse) explains why an agent's own confidence is an inadequate acceptance test.

For Claude Code, use the [Claude Code practice guide](/research/claude-code-software-development-best-practices). To assess your current process, use the [field manual self-assessment](/manual/self-assessment). Keep the result of each run with the task: what changed, what was checked, and what remains unverified.