A Cursor session opens. The agent reads the repo's README, the JSDoc comments, two or three Confluence pages someone bookmarked in the project rules. Then it confidently writes a 400-line PR against logic that was refactored six months ago. The diff looks clean. CI passes. It ships.
Three days later, a customer reports a regression in an edge case the agent had no idea existed — because the documentation it read for context never described that edge case in the first place.
This is the failure mode nobody is talking about. We've spent the last year worrying about hallucinations in agent output. The bigger problem is the hallucinations baked into the input.
Every agent has a context-gathering step
Cursor, Claude Code, Copilot Workspace — they all do roughly the same thing before writing code. They scan the repo. They read your README. They open files referenced in the prompt. They pull in linked Confluence or Notion pages if your editor has those wired up. Some pull in Linear tickets, Jira epics, Slack threads.
That context window is what the model conditions on. Everything it generates downstream is steered by what it read at the start.
Which is fine, if what it read is true.
Most of what it reads is not. According to Port.io's 2025 research, only 3% of engineers completely trust their internal documentation. The other 97% have been working around stale wikis for years. The agent doesn't know which 3% to trust. It reads everything, weights everything, and produces output that averages out the staleness.
Drift compounds when the reader is a machine
I wrote earlier about comprehension debt — the gap between what AI tools ship and what any human on the team can explain. That post focused on the human side: nobody reads the agent's output carefully enough to catch drift.
The agent-input side is worse, for one reason: machines don't hedge.
When a human reads a Confluence page that is 18 months old, they get a feeling. Hmm, this looks dated. They ping someone. They check the actual behaviour against staging. They are cautious. The agent has no such instinct. The agent reads the doc, treats every sentence as currently-true, and writes code that conforms to a description of a product that no longer exists.
The same drift that costs your PMs 4–12 hours a week of doc maintenance now also corrupts the input layer of every AI coding tool your engineers run. Two problems, one root cause.
The DORA 2024 report found that AI adoption correlates with lower delivery stability — more code shipped, more rework required. People pin this on the agent's writing quality. Most of it is the input. The agent isn't bad at coding. It is coding against a fiction.
The spec is the context layer the agent actually needs
The fix isn't more docs. It is the same fix the human side needs: a spec derived from the code itself, which is structurally incapable of falling behind because it is downstream of the source of truth.
When the spec is generated from the codebase, three things change for the agent:
- Every scenario describes current behaviour. The agent reads what the product does today, not what someone planned 14 months ago.
- Edge cases are written down. The hidden third branch in the billing logic — the one humans forget but the code handles — shows up as its own scenario, not as buried implementation detail.
- The spec updates on every release. When the code changes, Specsight updates the affected scenarios automatically. The context the agent reads tomorrow reflects what shipped this morning, not last year's intent.
Specsight exposes the spec to AI tools through MCP — the Model Context Protocol, the standard way agents query external systems. Cursor, Claude Code, and any other MCP-capable agent can call list_features, get_scenarios, search_scenarios directly, without parsing PDFs, scraping wiki pages, or asking the developer to paste in context manually. The model gets a structured, accurate, queryable description of the product before it writes a line.
That is the loop closing. The code generates the spec. The spec feeds the agent. The agent writes code. The next release updates the spec.
What changes when the loop closes
Two concrete changes show up first.
Regressions stop coming from misunderstood edge cases. When the agent's context includes the edge-case scenarios for the feature it is editing, it stops casually breaking them. The ghost-feature bug — a behaviour the agent did not know existed and quietly removed — gets caught at the prompt stage, not at the support stage.
PR review gets faster. Code review is the current bottleneck for AI-assisted teams: the agent ships at a higher volume than the human, but humans still have to verify it. When the spec is the reference, the reviewer can ask "does this PR change any scenarios, and if so, are the changes intentional?" That is a much shorter loop than reading 400 lines of agent diff and trying to infer the behaviour change from scratch.
I am not claiming this eliminates code review. I am claiming that a structured, current spec gives the reviewer something concrete to anchor against — and gives the agent something concrete to start from. Both ends of the loop tighten.
The teams that ship fastest with AI are the ones least able to hold the product in their heads. They are also the ones whose agents are reading the most stale context. The two problems are the same problem.
The demo project shows the spec in action, including the MCP layer that exposes scenarios to AI tools. If you want to connect your own repository and see what your agent could be reading instead, get started free.
