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
- 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.
- 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.
- 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. 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.
I'm building Forge around exactly this: a living design layer your coding agents (Claude Code, Cursor, Cline) read over MCP and propose changes back to, non-destructively — so design and code stop drifting apart. It's an open free beta, and I'd love feedback on whether this matches a pain you have.
Top comments (1)
Agent drift is a real problem once projects get beyond the MVP stage. We've seen at IT Path Solutions that the biggest issue usually isn't the model it's the lack of structured intent and guardrails. When architecture decisions, boundaries, and acceptance criteria become part of the workflow instead of scattered docs, agents make far fewer "creative" assumptions. The feedback loop you described is an important piece that's often overlooked.