Context drift is the hidden tax on AI-assisted teams

Context drift — the slow divergence between what your team wrote down and what the code actually does — is a tax every engineering team pays, usually without measuring it. AI-assisted coding raises the rate, because agents generate change faster than anyone keeps the notes current. The only durable fix is to anchor knowledge to the code it describes and re-check it when that code moves.

You have felt this tax even if you never named it: the README that lied, the comment that described a function two refactors ago, the architecture doc everyone quietly stopped trusting. Each one is context drift, and each one bills you.

What drift actually costs

• Broken changes. Someone reads a stale note, trusts it, and ships a change that violates a constraint the note no longer describes.
• Re-derived knowledge. A new engineer or agent spends hours reconstructing a decision the team already made, because the record of it rotted.
• Eroded trust. Once a few docs are wrong, people stop trusting all of them — so even the accurate notes go unread. This is the most expensive line item, because it makes the whole layer worthless.

Why AI raises the rate

Drift is a function of how fast code changes relative to how fast notes are maintained. AI-assisted coding pushes the numerator up hard. As of the 2024 Stack Overflow Developer Survey, 62% of developers already use AI tools in their workflow, and that share is climbing. More change, generated faster, by actors that start every session with no memory of the last one — the gap between code and recorded knowledge widens by the week.

An agent writes code competently but starts cold. It cannot know the decision behind a piece of code unless that decision was captured somewhere it can read — and if what it reads is stale, it inherits your drift and amplifies it.

Why the wiki can’t save you

The standard answer is "document more," and it fails for a structural reason: wikis, READMEs, and design pages are written once and have no link to the code they describe. Nothing tells them when the ground shifted. The longer a page survives untouched while its code churns, the less of it is true — and confidence in documentation does not decay as fast as its accuracy does, which is exactly what makes stale docs dangerous rather than merely useless.

The fix: context integrity

Stopping the tax means maintaining context integrity — the property that recorded knowledge still matches the system as it exists now. Two moves get you there:

1. Anchor knowledge to code. Attach each note to the specific globs it governs, so the system knows which knowledge applies to which files.
2. Re-check on change. When the anchored code changes, flag the note for a fresh look and route it back to a human. The note is kept honest against the system that actually exists.

This is the difference between static documentation and living documentation: the second has a feedback loop, the first does not.

Make it a habit, not a project

Drift is not paid down in a one-time documentation sprint; it is held at bay by a small loop. After a session, persist what you learned. Before you touch an area again, pull what is already known. On the way to a commit, refresh the context your diff touches:

driftless context get --diff

The value compounds with the count. A handful of well-anchored notes, kept honest, and every future change — human or agent — starts with the context instead of re-deriving it.

FAQ

How is context drift different from technical debt?

Technical debt is in the code; context drift is in what you wrote about the code. You can have clean code and badly drifted context — and the drift will still cause broken changes.

Can I detect drift automatically?

You can detect the signal: when code a note is anchored to changes, the note becomes a candidate for re-review. A human still decides whether the meaning actually changed — drift detection flags, it does not auto-rewrite.

Where should a team start?

Anchor one note to one area that has burned you before, then add the pre-commit refresh to your routine. Start small; the loop is what compounds. See why AGENTS.md isn’t enough for where this fits.

Driftless keeps your team’s context honest as the code changes. See how it works.