Seven things that break when AI coding agents meet a real codebase

The first week with an AI coding agent feels like a superpower. The second week feels like a code review backlog with a ghost author.

These are the seven failures I kept hitting, and what actually fixed each one.

1. It changes what you did not ask it to change

Ask for a null check on one function and you get the surrounding module refactored. The prompt is not the problem; the missing piece is a scope contract the agent reads before it touches anything.

Naming the files it may not edit does more than any amount of "be minimal" instruction.

2. It forgets the project after about 30 turns

Context resets are not a bug you can prompt away. You need a file on disk the agent re-reads: how money is stored, how IDs are generated, what is never allowed to change.

If that file is long and vague, the agent skims it. Twelve short sections beat forty aspirational ones.

3. It rubber-stamps its own diff

An agent asked to "review" its own change will usually say it looks good. A review needs a written bar: a checklist it must answer PASS/FAIL against, with file:line evidence.

The moment you require evidence, the rubber stamp stops.

4. It deletes the test that was failing

The fastest path to green CI is deleting the test. If your instructions do not explicitly forbid it, expect it - and check the diff for removed test files specifically.

5. It writes money as a float

parseFloat on a cart total is the classic. The agent has no model of your money type unless you tell it.

Put "integer minor units, no floats, currency explicit" in the memory file and add it to the pre-merge checklist; this is the single highest-value rule in the whole setup.

6. It treats retries as impossible

Webhook handlers, payment capture, email sends: the agent writes them as if they run once. They do not. Require the idempotency key to be visible in the diff.

7. You cannot review what you do not understand

If you only read the diff when you already distrust it, you have no acceptance criteria. The fix is boring: make the agent state what must be true before merge, then check those statements.

None of this is exotic. It is the same discipline we apply to human contributors, minus the onboarding doc - which is exactly what the agent is missing. Write the onboarding doc.

If you want a head start, I put the template I use in a free repo: CLAUDE.md template + /review command + the 6 money checks. The full kit is 18 files including a 4-week adoption order, because installing everything at once is how these setups get abandoned.