The 32,000-token wall
This is the post's most important number, and it comes from a 2025 academic measurement that looked specifically at code comprehension — not prose.
Eight task types, four dimensions (identifying a code unit, comprehension within a unit, relationships between units, long documentation), nine long-context models. The finding, word for word:
The performance of every model examined drops sharply once the code length exceeds 32,000 tokens — in sharp contrast to the advertised context windows of 128,000 to a million.
And the detail is where it bites: between 64,000 and 128,000 tokens, dependency and relationship analysis falls to essentially zero. The model still "sees" the code, but no longer understands how things connect — precisely the thing you went to a legacy codebase for.
| What it has to grasp at once | What works |
|---|---|
| Under ~32K tokens (roughly 2,000–4,000 lines) | the full context — this is the best case |
| Above 32K | it fits on paper, but grasping the relationships degrades |
| Above roughly 400,000 lines | plain search and reading are no longer enough |
The practical rule that follows: do not hand it the repo, hand it one thread.
The "I would rather rewrite it" bias
There is a 2026 measurement that looked specifically at how well a model understands the architecture of an unfamiliar repo. The questions were drawn from real developer conversations, and the scoring was done with a checklist rather than a score.
It has two findings, and both matter.
The first is the editing bias: models "prematurely propose code modifications instead of understanding the architecture of the existing repository". You ask a question and you get a fix.
The second is more insidious still: there is "a persistent gap between high comprehensibility and evidence-based technical correctness". In plain terms: the answer is clear, well structured, confident — and not anchored to the code.
This is why you must not ask it to "understand the repo". What you get back is a good-sounding summary that costs more to verify than it saved.
What the model knows — and where it actually knows it from
This section settles what you can expect inside a closed corporate codebase.
A 2026 study collected 1,318 real developer questions and their accepted answers from 134 open-source projects, and measured two strong models on them. The baseline scores landed around 6.6 and 7.0 on a ten-point scale — respectable, not impressive.
The decisive result is somewhere else, though. When the models were forbidden to use their internal knowledge, their performance dropped. And on questions from after the training cutoff it fell drastically: from 6.59 to 5.44 for one model, from 6.97 to 5.97 for the other. The authors also documented verbatim reproduction of community answers.
Which means the model mostly performs well on what it has already seen. In a closed, corporate, never-published repo, that is exactly the advantage you do not have.
The breakdown is usable too: strong on API usage questions, weak on configuration, integration and querying. Unfortunately, in legacy systems the pain is typically in those last three.
How does it find the code? Three strategies
Semantic index. It cuts the files into chunks, turns them into vectors and searches by meaning. The upside is that a natural-language question finds things even when the word you used does not appear in the code. The downside is a separate index to maintain, a recent change only visible after reindexing, and chunking that can cut related parts apart.
Search-based discovery. No index: it searches on a file pattern, then on content, then reads the file. The maker of one of the big tools was unusually candid about this: their early versions worked with a vector database, but they found that search-based discovery generally works better — which surprised them too.
This has a cost profile worth knowing: file-pattern search is practically free, content search is cheap, but reading a whole file costs 500–5,000 tokens per file. Anyone who issues a "read the whole folder" instruction is burning their context window.
Full context. The best option while it fits — but the 32,000-token limit above is what it runs into.
One common misquote worth correcting: a study is doing the rounds claiming that keyword search reaches 90% of the performance of vector solutions. That is true — but it was measured on general question answering, not on code. Using it to justify what the coding tools decided is overreach.
The 400,000-line threshold
A tool vendor's own measurement examined 1,281 evaluated agent runs across more than forty large open-source repos in nine languages. The finding: agents using local tools only — search and file reading — start getting stuck regularly above roughly 400,000 lines of code.
A concrete example from the same source: in a 1.4 million line, 22,000 file project, without a code search tool no output appeared even after 6,000 seconds; with indexed search it was done in 89 seconds, at good quality. On a multi-file refactoring the plain agent modified two files out of seven; the augmented one modified all seven.
And the most useful detail: below 400,000 lines, adding the code intelligence tool made results worse. So the solution built for a large codebase is needless complication on a small one.
(Vendor measurement, about its own product, not peer-reviewed — the order-of-magnitude threshold is still usable.)
A surprise: comments are sometimes noise
Another measurement — 500 code search tasks, fifty repos, five languages — looked at whether a model can find the function you want from a natural-language description.
Its side result is worth pausing on: removing the comments improved the models' performance (with one model family as the exception).
In legacy codebases this is not surprising. A ten-year-old, outdated, misleading comment is not help, it is noise — and the model can be led astray by it exactly as a human can.
The recipe
1. DO NOT ASK IT TO "UNDERSTAND THE REPO".
You get a confident, well structured, code-free answer.
2. ASK ABOUT ONE THREAD, CONCRETELY.
"How does a request travel from the /checkout endpoint to
the database? List the files and the line numbers."
-> asking for files and line numbers is what anchors it
3. KEEP IT UNDER 32K TOKENS, whatever it must grasp at once.
One module, one flow, one layer - not the whole thing.
4. PUT DISCOVERY IN A SEPARATE SUBAGENT.
It runs in its own context window and returns a summary,
so the main session stays clean. A "have a look around"
with no context makes it read hundreds of files.
5. USE THE VERSION HISTORY.
"Go through this class's git history and summarise how
its API came about." A commit message carries intent
that is nowhere in the code itself.
6. ON A BIG REPO (above 400,000 lines) YOU NEED SYMBOL-LEVEL
NAVIGATION. On a small one it hurts - do not add it early.
7. WRITE DOWN WHAT YOU UNDERSTOOD - in its place, not all of it.
And COBOL?
Any conversation about legacy codebases gets here sooner or later, so it is worth stating exactly where things stand.
The big vendors' products went through a renaming in early 2026 — anyone searching for the old product name lands on outdated documentation. Adoption or outcome numbers, though, are published by none of them.
The most useful quotable professional finding from 2026: AI tools speed up the code analysis and transformation phase, but they do not address the full program scope that decides whether a migration succeeds.
And the specific missing piece: there is no behavioural equivalence checking tool. Nothing proves that the new system really does what the old one did. In a regulated environment that gap is a blocker.
So the thesis is this: AI brings real value in the understanding phase — dependency maps, documentation, code discovery. A migration's bottleneck is not the translation but the proof. Connected to this is the question of what is even safe to restructure: that is what the safe refactoring post is about, with the numbers.
Common misconceptions
- "The context window is a million tokens, so the repo fits." It fits, but above 32,000 tokens grasping the relationships degrades, and between 64,000 and 128,000 it essentially stops.
- "I will just ask how the project is put together." It is a measured bias that the model proposes a fix instead, and that its answer is clear but not anchored to the code.
- "The model knows systems like this anyway." It knows what it has seen. On questions from after the training cutoff its score drops by a point, and in a closed repo it has nothing to fall back on.
- "I will give it everything, comments included." In one measurement, removing the comments improved the hit rate. An outdated comment is noise.
- "We need a code search index." Above 400,000 lines, yes. Below that, the measurement says it hurts.
What to take away
A legacy codebase is not something to have the model "understand"; it is something to have it follow one thread through, with file and line numbers. Keep whatever it must grasp at once under thirty-two thousand tokens, put discovery in a separate subagent, and use the version history — the commit message holds the intent the code is missing. The model is strong on what it has already seen; in your closed repo that advantage is not there.
How to write down what you understood — and what that is really worth — is covered by the documentation you will actually maintain post; from the verification side, the safety net of tests post takes it further.