Stop AI from hallucinating code in your repo

You give a coding agent a task, it starts editing, and by review time you find it rewrote the wrong function, added a dependency that doesn’t exist, or swapped a critical algorithm for a plausible but incorrect one. The mistake wasn’t malice; it was a reasonable assumption nobody asked it to confirm, or context that went stale unnoticed. To stop this, make the agent commit its assumptions and update them as the codebase changes so you catch hallucinations before they reach review.

Start by forcing the agent to surface its assumptions

Agents don’t tell you what they believe unless you make them. When you hand them a ticket or a prompt, they infer constraints from the repo, your style, and the names you used. Those inferences become the hidden ground truth the agent optimizes for, and when the ground truth is wrong the output is wrong too. The only way to surface those assumptions is to require the agent to write them down before it touches a file.

Record decisions and assumptions in a shared workspace

When an agent registers a task, it should write its initial assumptions into a shared space where other agents and reviewers can see them. That space becomes the single source of truth for what the agent believes, not what it later infers from a stale file. Overlap warnings arrive when an agent claims work, which the five tools each contribute to in a different way.

If the task is underspecified, the agent will invent its own constraints. Instead of letting it proceed, force it to state the missing pieces explicitly. For example, if the prompt says “improve the cache layer” but doesn’t specify eviction policy, require it to write “assumption: LRU eviction is acceptable” before it starts. That way the assumption is visible and can be challenged.

Keep the agent’s context current as files change

Even if the agent starts with correct assumptions, the repo moves on. A function it read yesterday could be renamed today, a dependency could be bumped, or a constant could change value. If the agent never revisits its context, it keeps reasoning from stale data and will hallucinate updates to match its outdated view of the world. The fix is to make the agent re-read the shared workspace after every significant file change and update its beliefs accordingly.

Re-sync after each file edit or external signal

After an agent writes a file, another agent or a human reviewer may change it. The next time the original agent acts, it should fetch the latest workspace state and reconcile its assumptions against the new reality. This prevents it from inventing changes that overwrite real ones or inventing dependencies that no longer exist.

External signals like a new issue comment, a dependency bump in package.json, or a renamed export in another module also demand a re-sync. If the agent doesn’t incorporate those signals, its next edit will be based on outdated context and likely wrong.

Make the agent prove its work before it finishes

When an agent thinks it’s done, require it to show its work: the decisions it made, the assumptions it confirmed, the tests it ran, and the risks it identified. If any assumption is still implicit or stale, the agent hasn’t finished. Only mark the task review-ready when every belief is explicit and up to date.

This is where many agents fail. They record a summary at the start and never update it, so by the time they finish their context is months old. Instead, maintain a running log of decisions and assumptions, and append to it after every edit and every external change. When the log is complete and consistent, the agent’s output is less likely to contain surprises.

Include the honest case: the task was underspecified

If the prompt didn’t name the constraints, the agent will have invented them. Before you accept the result, decide whether those inventions are acceptable. If not, tighten the spec, re-run the agent, and require it to state the new constraints explicitly. Underspecification is a common source of hallucinations, and the only cure is to name the practice explicitly.

For example, if the agent added a new sorting algorithm without being told which one to use, ask it to commit to “quicksort is acceptable” before you approve the change. That turns an implicit assumption into an explicit decision, and makes it reviewable.

What this looks like in practice

You open a ticket that says “optimize the image pipeline for 4K uploads.” The agent registers the task and writes its initial assumptions: “assumption: use lossy WebP, max 80 quality, preserve EXIF.” A reviewer sees the assumption and objects: the pipeline must keep lossless PNG for medical images. The agent updates its assumption to “assumption: lossy WebP unless the image is marked medical,” commits the change, and proceeds.

Later, another agent renames the medical flag from is_medical to medical_image. The first agent, acting again, fetches the latest workspace state and sees the renamed flag. Without that re-sync it would have tried to read is_medical, failed silently, and invented a new flag in its next edit. With the re-sync, it adjusts its code to use the new name and continues.

When the agent thinks it’s done, it writes a summary: “decisions: lossy WebP for non-medical, lossless PNG for medical; assumptions: medical_image flag exists; tests: 4K upload benchmark passes; risks: none identified.” A reviewer sees the summary, checks the tests, and approves the change. The entire history of assumptions and decisions is preserved, so future edits can reference it without inventing new facts.

Tools that give you this control

Most MCP servers don’t provide a workspace layer that records intent, decisions, and context. You need a server that offers tools to register presence, claim tasks, record assumptions, re-sync after changes, and finish with a review-ready log. The five tools sequence around a task so agents can surface assumptions, update them, and prove their work before they finish.

If you’re using Claude Code, Cursor, or Codex, make sure your MCP server supports start_work, inspect_work, update_work, transfer_work, and finish_work. These tools let you enforce the workflow above without changing how the agent itself works.

For a concrete implementation, see the open-source concord-mcp server. It provides the five tools and a shared workspace so agents can record their assumptions, re-sync after file changes, and finish with a review-ready log. You don’t need to replace your agent; you just give it a workspace it can call to surface and update its context.

When agents still go wrong

Even with this workflow, agents can still hallucinate. If the initial prompt is too vague or the agent’s model is too creative, it may invent constraints that sound plausible but are wrong. In those cases, the honest answer is that the task was underspecified. Tighten the prompt, record the new constraints explicitly, and re-run the agent. Hallucinations that persist after explicit constraints are usually a sign the agent isn’t suited for the task, not that the workflow failed.

For example, if the agent keeps inventing a new authentication layer when the spec only asked to add a feature flag, the problem isn’t the workflow; it’s that the prompt encouraged invention. Re-write the prompt to say “add a feature flag for dark mode without changing auth,” record the constraint, and run again. The second attempt will be closer to what you need.

If you find yourself in this loop often, reconsider whether the agent should be doing the work at all. Some tasks require human judgment that agents can’t replicate, and no workflow will fix that. In those cases, stop using an agent and do the work yourself.