Coding Agents
The Agent Reads the Repo Before It Writes a Line
Most agent failures are not bad models. They are a correct model editing the wrong file because nobody gave it the map.
The most common failure I see in agent-assisted work is not a bad model. It is a correct model editing the wrong file, because nobody told it how the system fits together. The agent wrote exactly what it was asked, in the place it was pointed at, and the assumption underneath was wrong.
The fix is unglamorous: make the agent read before it writes, and make the reading visible.
The three-file rule
Before editing anything, find the definition, one caller, and one test. Three files, chosen deliberately, tell you the type, the usage and the contract. Most bugs that survive a naive edit live in the gap between those three.
rg -n "functionName" src/ # definition + call sites
rg -n "functionName" --glob "*.test.*" # the contract
rg -n "from .*module" src/ # who depends on this surfaceIf there is no test, that is the finding. Write the failing test first, then let the agent make it pass. A test is a specification the agent cannot argue with, and it is the cheapest review you will ever get.
Plan before diff
Ask for a plan that names the files and the intended change, then approve or reject it. This costs one turn and catches the expensive class of error: the agent that decides to refactor an interface because it was convenient. A plan is also where you notice the agent has misunderstood the requirement, before it has written 400 lines around the misunderstanding.
A wrong plan costs a message. A wrong implementation costs an afternoon.
Feed it the failure, not the theory
The highest-signal prompt is a command and its output. Not "the build is broken" but the actual compiler error, with the file and line. Not "the page looks wrong" but a screenshot and the selector. Agents are very good at closing a loop when the loop is concrete.
$ npm run build
src/components/Feed.jsx:118:9 - error TS2339:
Property 'tags' does not exist on type 'Post'.
> fix the type error above without changing runtime behaviourScope the edit
- One concern per run. A bug fix and a rename are two runs.
- Name the files it may touch. Anything outside that list needs a reason.
- Forbid new dependencies unless you asked for one. Agents install packages to avoid writing twelve lines.
- Ask for the diff before the apply whenever the tool supports it.