If you tell a coding agent “fix it” and then act shocked when it rewrites half the app, that’s on you. Same as handing a junior a Slack message that says “make it work” and then reviewing a 40-file PR like you were ambushed by fate.
Write a definition of done into the brief. Not a novel. A short contract. The model is fast. It is not psychic. If “done” lives only in your head, you will get a tour of everything it thought might be helpful.
This is the checklist to paste, in some form, almost every time.
Done means a small, reviewable change
Aim for a patch you can read in one sitting. Not a new architecture. Not a rename of every file because the agent liked a different folder shape.
If the change needs more than one concern, split the work. First make the test fail for the right reason. Then make it pass. Then stop.
Agents love momentum. Momentum is how a login bug becomes a new design system. Say it out loud: “Smallest diff that satisfies the criteria. Do not refactor adjacent code unless it is required for the fix.”
If it still comes back wide, reject the PR the same way you would with a person. “Smaller. Show me the patch.” You train the loop by what you accept.
Done means tests, not vibes
“It should work” is not acceptance criteria. Ask for:
- the behavior in plain English
- a test or two that would fail if the behavior regressed
- what you will run locally before you merge
If the repo already has a test command, tell it the command. If it doesn’t, do not let the agent invent a whole framework to feel complete. One focused test beats a synthetic suite that mocks the universe.
Also tell it not to delete tests to make the suite green. That sounds obvious until you watch it happen. Models optimize for the scoreboard you imply. If green is the only scoreboard, they will find a shortcut.
Done means it did not invent an API
This failure mode shows up enough that it deserves its own line.
Do not invent endpoints, env vars, or library methods that would be convenient. Use what exists. If you need something that does not exist, stop and ask.
Agents are excellent at hallucinating a helper that “should” be there. The code looks clean. The import is confident. Then you run it and discover you now own a fiction.
Same rule for dependencies. No new package unless you asked for it. Surprise dependencies are how you inherit a supply chain and a license you did not want on a Tuesday.
Done means the boring production stuff is not skipped
For anything that might actually ship, add:
- error handling that matches the surrounding code
- logs that would help you debug at 1am, without dumping secrets
- no comments that narrate the obvious
- no leftover debug prints
- types or schemas if the file already uses them
Also say what not to touch. Auth. Billing. Migrations. Production config. Patient data paths. The model will wander into those rooms to be helpful. Helpful is not the same as allowed.
If the task is “add a column to this admin table,” done is not “I also redesigned the navigation because it felt dated.”
A brief you can reuse
Keep a stub and fill it in:
- Goal:
- Files that matter:
- Done means:
- Tests to add or run:
- Do not:
- Output: a small diff and a short summary of what changed
The summary is for you, not for LinkedIn. “Updated the missed-call query to use created_at instead of updated_at so overnight rows don’t vanish.” That’s a summary. “Refactored services for maintainability” is a fog machine.
Attach the error, the screenshot, the failing test, the SOP, whatever is the source of truth. If you don’t attach it, you are asking the agent to improvise. Improvisation is for jazz. It is a bad default for production code.
How to review so the definition of done sticks
Read the diff like you don’t trust the narrator. Because you shouldn’t. Check the test. Run the thing. Look for extra files. Look for names you didn’t ask for.
If the agent followed the contract, say so. Positive reinforcement works on models and on humans.
If it didn’t, don’t start a philosophical chat about AGI. Paste the definition of done again and point at the violation. Tight loops beat lectures.
Why this feels slower and isn’t
Writing the contract takes three minutes. Untangling a rewrite takes an afternoon. The people who say “I tried agents and they made a mess” often skipped the part where they specified the mess they would accept.
A definition of done is not bureaucracy. It is how you stay the lead engineer in a pairing session with something that types faster than you think.
Bottom line
Give it a finish line. Then make it cross that line, not a different one it found more interesting. Small diff, real tests, no invented APIs, clear do-nots. That is done.
