# Why Does Your Coding Agent Keep Using Deprecated APIs? (And How to Stop It) URL: https://getunblocked.com/blog/ai-agent-deprecated-api/ Published: 2026-08-07T09:00:00Z Author: Brandon Waselnuk Categories: AI Agents, Context Engine AI agents suggest deprecated APIs because training data is frozen and retrieval can't rank freshness. 65% of devs say AI misses context. Here's the fix. --- Your coding agent keeps using deprecated APIs for two reasons, and neither one is fixable with a sterner prompt. First, its training data is frozen in the past: every model ships with a knowledge cutoff, so a deprecation your team announced in March simply doesn't exist in the model's head. Second, its retrieval can't tell current from stale. Your codebase still contains the old pattern in a hundred call sites, your wiki still documents it, and an example file from 2023 still demonstrates it beautifully. The agent takes the first plausible match, and the first plausible match is usually the old one, because old code outnumbers new code in almost every repository on earth. ## Why do agents reach for deprecated code at all? Because the old API dominates everything the model has ever seen. Anthropic publishes a training data cutoff for every Claude model, and even distinguishes it from a "reliable knowledge cutoff," the date through which knowledge is most trustworthy ([Anthropic model docs](https://platform.claude.com/docs/en/about-claude/models/overview)). OpenAI does the same for GPT models ([OpenAI model docs](https://developers.openai.com/api/docs/models)). Anything deprecated after those dates is invisible to the weights, and the gap is bigger than it looks: a model released this summer can be confidently wrong about a library that changed before you finished reading its launch post. Frequency makes it worse. An API that lived for five years has five years of tutorials, Stack Overflow answers, and blog posts behind it; its replacement has a few months. Stack Overflow's own analysis of the developer AI trust gap lists "methods that were deprecated years ago" among the most common failure modes developers report, alongside APIs that never existed at all ([Stack Overflow, 2026](https://stackoverflow.blog/2026/02/18/closing-the-developer-ai-trust-gap/)). When the model emits deprecated code, it's doing exactly what its training distribution taught it to do. ## How does an agent decide which API version to trust? It doesn't decide. It satisfices. When your agent needs to call your billing service, it searches, finds something that compiles, and moves on. The wiki says one thing, the code says another, and an old example file says a third, and nothing in the loop ranks those against each other. This is [satisfaction of search](https://getunblocked.com/blog/satisfaction-of-search/) in action: the agent stops at the first plausible answer, not the best one. Ask for a new webhook handler and it models it on whichever existing handler it found first. If that's deprecated code, you now have one more copy of it. That's why the [same prompt on the same model produces different code](https://getunblocked.com/blog/same-prompt-same-model-different-context/) depending on which files happen to land in context. The deprecation decision exists, but it lives in a Slack thread and a merged PR, exactly [where your coding agent can't see](https://getunblocked.com/blog/what-your-coding-agent-cant-see/). ## Why doesn't a bigger context window solve it? Stuffing everything into a million-token window makes the ranking problem worse, not better. Anthropic's own docs are blunt about it: more context isn't automatically better, because accuracy and recall degrade as token count grows, a phenomenon they name context rot ([Anthropic context docs](https://platform.claude.com/docs/en/build-with-claude/context-windows)). We've written about how that plays out in practice in [Claude Code sessions](https://getunblocked.com/blog/context-rot-claude-code/). The independent numbers back this up. Zylos Research's 2026 survey of long-context evaluation found models typically become unreliable 30-40% before their claimed context limit, and attributes nearly 65% of 2025 enterprise AI failures to context drift or memory loss during multi-step reasoning ([Zylos, 2026](https://zylos.ai/research/2026-01-19-llm-context-management/)). If you paste the old docs, the new docs, and the migration guide into one giant prompt, you haven't told the agent which one wins. You've just given it more plausible matches to satisfice against. The window is working memory, not a source of truth, and something upstream still has to decide what deserves the space. ## What does shipping deprecated code actually cost? It compounds. GitClear's 2026 analysis of 623 million code changes found duplicated blocks up 81% since 2023, while moved code, its proxy for refactoring, fell to 3.8% of changed lines ([GitClear, 2026](https://www.gitclear.com/the_ai_code_quality_maintainability_gap)). Every time an agent copies a deprecated pattern into a new file, it adds one more stale call site for the next agent to find and imitate. Multiply that across a team where agents write a growing share of commits, and deprecated APIs stop being a cleanup chore and become load-bearing. Sonar's Tom Howlett describes the same dynamic: agents add code but rarely delete it, so superseded functions accumulate next to their replacements ([InfoWorld, 2026](https://www.infoworld.com/article/4182518/shipping-enterprise-quality-code-with-ai-agents.html)). Note what this isn't: a capability problem. Stanford's 2026 AI Index reports SWE-bench Verified performance rose from 60% to near 100% in a single year ([Stanford HAI, 2026](https://hai.stanford.edu/ai-index/2026-ai-index-report)). The models can write the code. They just can't tell which API you actually want written. ## Do rules files and deprecation comments fix this? Partially, and honestly, that's worth having. A line in CLAUDE.md saying "use PaymentClientV2, never PaymentClient" works the day you write it. `@deprecated` annotations help too, when the agent reads the annotated file. But three limits show up fast. First, rules files rot: nothing breaks when a rule goes stale, so [the drift stays invisible](https://getunblocked.com/blog/rules-file-rot/) until an agent acts on it. Second, they don't scale. Keeping [CLAUDE.md, AGENTS.md, and .cursorrules in sync](https://getunblocked.com/blog/keeping-claude-md-agents-md-cursorrules-in-sync/) is hard in one repo and hopeless across fifty. Third, nobody updates them, because the deprecation decision happened in a PR review or a Slack thread, and writing it into a rules file is unrewarded manual work. That's the honest assessment behind the [rules files vs. context engine](https://getunblocked.com/blog/rules-files-vs-context-engine/) tradeoff. Qodo's survey of 609 developers found 65% say AI misses relevant context during critical tasks ([InfoWorld, 2026](https://www.infoworld.com/article/4183153/why-ai-coding-debt-is-different.html)). A hand-edited file was never going to close that gap alone. ## What actually works: ranking sources of truth The fix is a context layer that knows recency and authority, so the agent stops treating a 2023 example file and last month's migration PR as equal witnesses. This is what Unblocked does: it synthesizes your PRs, Slack decisions, and migration history into [decision-grade context](https://getunblocked.com/blog/decision-grade-context/), so instead of three conflicting matches, the agent sees "this API was deprecated in March, use X instead," with the reasoning attached. It's [institutional memory your agents can query](https://getunblocked.com/blog/claude-code-institutional-memory/) instead of a file someone has to remember to edit. Here's how one team wires it in: > The first instruction in every agent project file is: before making any changes, gather context. That pulls from Jira, Confluence, and Slack via Unblocked — because that's where most of our knowledge actually lives, in threaded discussions. I set it up the day it was announced and now I don't even think about it. I just get the relevant information. > > — Andrei Antanovich, Software Engineer, Waste Logics Unblocked doesn't generate code. It's the [context engine that feeds your agents](https://getunblocked.com/blog/unblocked-context-engine-for-agents/), whichever agent you run, the current answer instead of the most common one. ## Frequently asked questions ### Why does my agent repeat the mistake even after I correct it? Your correction lives in one session's context, and it evaporates when the session ends. The model's weights still favor the old pattern, and the stale sources that misled it are all still there. Unless the correction lands somewhere durable that gets retrieved next time, every fresh session starts from the same frozen prior. That's why teams that fix this fix it at the retrieval layer, not the prompt. ### Will a newer model stop suggesting deprecated APIs? It moves the cutoff, not the problem. A newer model knows about public deprecations up to its training date, but your internal deprecations never appear in any training set. The day after release, the model is frozen again while your codebase keeps moving. Retrieval that ranks freshness is what closes the gap, not the release calendar. ### Should I delete old code so agents can't find it? Deleting genuinely dead examples and stale wiki pages helps a lot; they're pure noise. But you can't delete a deprecated API mid-migration while callers still exist. That's exactly when agents do the most damage, and when a context layer that flags "deprecated, migration in progress, use X" earns its keep. ## The 20-minute version to try this week Pick the one deprecation your agents trip over most, and run this: grep the old call sites and check what an agent doing "search, then imitate" would find. Read where the current guidance actually lives; if it's a Slack thread and a merged PR, no rules file mentions it, which means no agent can honor it. Then do two cheap things: delete or quarantine the stalest example file, and add one line to your rules file naming the replacement. That buys you weeks. For the durable fix, make context-gathering the first step of every agent session, the way Andrei's team does, with a context layer that ranks your sources of truth by recency and authority. Your agent was never confused about how to write code. It was confused about which of your five answers was current, and that's a problem you can now actually solve.