Your New Coding Model Inherited Last Quarter's Instructions

TL;DR: Agent instructions are a cache of past failures, but the model version is missing from the cache key. When you upgrade the model, invalidate the cache: remove the instruction layer on a branch, run representative work, and restore only what current failures justify. Keep domain judgment. Turn mechanical policy into checks. Delete the scaffolding.

Your prompt has no cache invalidation

You upgraded the coding model. But you kept a prompt full of workarounds for the old one.

Open your AGENTS.md and read it as an archaeologist.

A warning remains from a migration that finished in March. A workaround for a model that could not follow imports. A reminder to write tests that nobody can prove ever changed anything. A skill that walks an older agent through behavior the new model handles by default.

Each line probably began with a real failure. That does not make it permanently true.

Instruction files accumulate like a cache of agent failures. A model makes a mistake, a reviewer gets annoyed, and another sentence enters the prompt. The file rarely records which model failed, whether the repository later changed, or when the advice should expire.

Then the team upgrades the model and preserves its old compensations.

The model changed. The cache key did not.

A model upgrade should trigger invalidation of the instruction layer. Not because instructions no longer matter, but because you no longer know which ones do.

Separate capability, judgment, and policy

Most instruction debt falls into three categories:

This is why the dbt Developer Agent and dbt Agent Skills do not undermine the case for deleting instructions. They sharpen it.

General coding agents have improved, but dbt still teaches them when to inspect lineage, preview data, check contracts, and reason about semantic models. Those skills package analytics-engineering judgment. A general model cannot infer that practice from its weights.

The general capability belongs to the model. Domain practice belongs to the team. Mechanical guarantees belong to the environment.

Better models make the separation more important because they follow instructions more reliably, including stale ones.

You cannot audit this by reading it

The normal cleanup is to keep the useful-looking lines and trim the obvious clutter. That is how stale context survives. Every line sounds prudent in isolation, so every line passes review.

Missing context and wrong context fail differently. With missing context, an agent may slow down, inspect current code, or ask for help. With wrong context, it skips discovery because the prompt has already told it what to believe. A March migration note becomes a confident lie in July.

Instead of asking whether an instruction sounds reasonable, ask:

What would the current model do wrong if this line disappeared?

You need an observed answer, not a plausible one. That requires an experiment.

Run a clean-context diff

Treat the instruction reset like a code change: isolate it, exercise it, review the delta, and keep only what earns its place.

1. Remove the instruction layer on a branch

Temporarily remove the instruction surfaces your agents routinely use: AGENTS.md, CLAUDE.md, .cursor/rules, .github/copilot-instructions.md, and general-purpose skills.

Keep tests, hooks, CI, ADRs, domain documentation, CODEOWNERS, permissions, and security controls. They are the environment under test, not prompt baggage. Use fixtures or a sandbox for risky domains.

Git is the rollback. The deletion is an instrument, not an ideology.

2. Run work that represents the repository

Use four or five tasks, not toy prompts:

• an ordinary bug fix;
• a small feature;
• a change in an unfamiliar module;
• a task in a domain with a known business boundary;
• a known trap such as generated files or a package-manager rule.

Where the cost is reasonable, run the same tasks with and without the current instructions. Otherwise compare the clean run with recently accepted work from the same model.

Score outcomes rather than workflow mimicry:

• Localization: Did it find the right files, tests, and domain concepts?
• Correctness: Did the behavior work without unnecessary changes?
• Verification: Did it choose checks that could disprove its work?
• Recovery: Did repository feedback lead it to the right repair?
• Reviewability: Could a reviewer understand intent, evidence, risk, and omissions?

The new model does not need to reproduce the old ritual. It needs to produce work that is at least as safe and easy to review.

3. Review without watching the run

Use a reviewer who did not watch the agent work. Builders normalize away detours and near misses, which overstates an instruction's value.

Record concrete deltas. "The old run felt more disciplined" is not evidence. "The clean run edited a generated client because nothing identified its source schema" is.

4. Re-solve failures instead of restoring prose

A clean-run failure proves that a problem exists. It does not prove that the deleted sentence was the right solution.

Classify the failure before restoring anything:

• If the repository was hard to read, improve a name, script, boundary, or local README.
• If the agent broke a mechanical rule, add a hook, lint rule, permission boundary, or CI check.
• If domain judgment was missing, add it to the relevant playbook, ADR, scoped skill, or nested instruction file.
• If the current model has a recurring quirk, add the smallest model-specific instruction and define when to remove it.

Git history proves that the team once had a problem. Do not use it as the source for the new patch.

Rebuild from the strongest surfaces inward

Restore knowledge in this order:

1. The repository itself. Prefer clear names, scripts, types, and boundaries for facts the model can discover.
2. Deterministic feedback. Use hooks, CI, and permissions for mistakes the system can detect.
3. Scoped knowledge. Put domain judgment in an owned source and load it only near relevant work.
4. Startup context. Reserve root instructions for decisions the model cannot infer and mistakes too expensive to discover late.

For example, replace this:

Never edit generated files. Be careful to update the source schema instead.

With a check that fails at the mistake and explains the route out:

✗ src/generated/** is machine-written.
  Edit the source schema and run `bun run codegen`.

For domain knowledge, route instead of narrating:

# src/billing/AGENTS.md
 
Read docs/billing/playbook.md before changing invoice behavior.
Run `bun run test:billing` and attach invoice-preview evidence.

The rebuilt root file should contain little else:

## Checks
 
- Use `bun run check` for ordinary changes. It runs checks in CI order.
- The full end-to-end suite takes 40 minutes. Skip it for docs-only work.
 
## Boundaries
 
- Shipped migrations are immutable. Add a new migration instead.
 
## Evidence
 
- Pull requests state intent, commands run, skipped checks, risks, and UI evidence.

No directory tour. No motivational poster. Every line changes a decision the model could not make correctly from the repository alone.

Expect new sediment

Stronger models also expand the work you delegate. An agent that once handled a small bug now attempts a cross-service feature or a multi-day migration. Those tasks expose boundaries nobody documented because no agent had reached them before.

Write new guidance when new failures justify it. If guidance describes one model or harness, keep it model-specific and attach an expiry condition: remove it when a successor completes the failing task set without it.

Shared instructions should contain shared knowledge.

Do this now: invalidate ten lines

Open the first ten non-blank lines of your root instruction file. Label each one:

• S for generic model scaffolding;
• J for team or domain judgment;
• P for mechanically enforceable policy;
• ? when nobody knows what failure it prevents.

Then act on one line before you close the file:

1. Delete one S or ? line on a branch.
2. Run one real task that should expose whether it mattered.
3. Move one P line into an issue for a check, hook, or permission boundary.
4. Give one J line a source and an owner.

If nobody would notice the deleted line by Friday, leave it deleted.

Start with ten lines. The next model should not inherit them unquestioned.