AI coding agents

Why does my AI coding agent keep building the wrong thing?

Short answer: your agent isn't guessing badly — it's guessing at all. The plan it needs lives in your head and in scattered notes no agent ever reads, so on every task it reconstructs your intent from the code plus your last prompt. Small misreads compound into confidently-built wrong things. This is agent drift, and it gets worse as the codebase and the team grow.

Three things that cause agent drift

1. The spec isn't machine-readable. A Notion page or a README is prose; an agent can't reliably extract "this system must not touch billing" from a paragraph. It needs boundaries and acceptance criteria as structure, not vibes.
2. The plan goes stale the moment code starts. You designed it, the agent built something slightly different, nobody updated the doc — so the next session builds on a fiction.
3. Nothing flows back. When the agent discovers a needed change mid-build, it just does it. Your design and your code silently diverge, and you find out later.

The fix: a design source-of-truth the agent reads before it builds

Give the agent structured intent it can build against. Concretely, describe each part of your project as a System with a Goal, a Boundary (what it must not do), and Acceptance criteria — plus ordered milestones — and expose that to the agent over MCP. Now the agent builds against intent, not a guess.

Two properties matter as much as the structure itself:

• Propose, don't overwrite. When the agent discovers a change, it proposes it back for you to approve — your design is never silently rewritten.
• Loop back to real code. Each system maps to the files that implement it, so you can see what was actually built vs what was designed. The doc can't quietly rot.

Related: Keeping a whole team's AI coding agents aligned →