You hand the agent a context pack: a map of the codebase, the relevant files, the architecture notes, the recent diff. It looks great. The agent reads it, nods, and starts making changes.

Here's the problem nobody talks about: that pack is a snapshot at time T. By the time the agent finishes reading and starts acting, someone on your team has renamed a function, merged a PR that changed an endpoint, or restarted the dev server on a different port. The agent is now confidently working from a map that no longer matches the territory.

The drift isn't dramatic. That's what makes it dangerous.

It's not that the agent hallucinates something wild. It's that it uses the correct function name from your context pack — the one that existed when you wrote the notes — and that function was renamed three days ago. The agent gets a module-not-found error, tries to fix it by guessing, and now you're debugging a problem that didn't exist until the agent's stale context collided with reality.

I've seen this pattern enough times to recognize it: the agent isn't wrong about what to build. It's wrong about where to build it. The instructions were right; the map was old.

Bigger context windows don't fix this

The reflexive answer is to stuff more into the prompt — more files, more documentation, more architecture diagrams. But a bigger snapshot is still a snapshot. If anything, a bigger context pack rots faster, because it covers more surface area that can change.

The real question isn't how much context you give the agent. It's how fresh that context is when the agent acts on it.

The cheap freshness check

You don't need a real-time sync system. You need a cheap check that fails loud when the context has drifted.

The version I use is embarrassingly simple: before the agent starts making changes, ask it to run one command that proves the current state matches the context pack. For a codebase task, that's something like git log --oneline -5 — if the HEAD commit doesn't match what you described in the context pack, stop and refresh. For an API task, it's hitting the health endpoint and checking the response shape matches what you told the agent to expect.

This adds ten seconds. It catches the class of bug where the agent confidently works from a stale map and produces something that looks right but doesn't compile, doesn't route, or doesn't match the live system.

The most reliable truth is the running thing

Here's the principle I've landed on: documentation, architecture notes, and context packs are all claims about the system. The only thing that's not a claim is the system itself, running.

For most of the codebase, that means running the tests, running the dev server, running the build. For the API surface specifically, it means hitting the endpoint and checking the response against the contract — not trusting the markdown that describes the endpoint.

This is the problem I kept running into with API work: I'd hand an agent an OpenAPI spec, it would generate code against it, and the code would be correct relative to the spec but wrong relative to the live endpoint, because the spec hadn't been updated since the last deploy. The spec was a snapshot. The endpoint was the truth.

That's why I built Powerduck as a local-first tool: the spec stays on your machine, and you can re-run it against the live endpoint in one step. No waiting for a cloud sync, no wondering if the spec in your editor matches what's actually deployed. The freshness check is the workflow, not an afterthought.

What this means for context engineering

Context engineering isn't about being generous with what you give the agent. It's about being honest about when what you gave it has gone stale.

A few practical rules I've settled into:

  • Never hand an agent a context pack without a timestamp. If the pack says "here's the current architecture," put the commit hash or the date. The agent can then check whether that's still true.
  • One cheap verification command before the agent acts. It doesn't have to be sophisticated. It just has to fail when the world has moved on.
  • Prefer running the thing over reading about the thing. If the agent can verify a claim by running a command, it should. Documentation is a hypothesis; execution is the experiment.
  • Your external truth layer should be local and fast. If checking freshness requires a 30-second cloud round-trip, you won't do it. If it's one command on your laptop, you will.

The next time an agent produces something that looks right but doesn't quite work, ask yourself: was the logic wrong, or was the map it started from already old? Nine times out of ten, it's the map.